ohos_YYEVA
简介
YY-EVA HarmonyOS 版提供端侧 MP4 合成能力，适用于礼物动画、动态贴纸等播放场景，兼容 Android 版资源格式，具备以下特点：
- 支持透明通道与遮罩混合渲染，可叠加 UI 图层。
- 覆盖播放、暂停、静音、循环、逐帧等全量控制。
- 提供 JSON/脚本驱动的动态元素替换。
- 支持软硬解码切换与 GPU 加速，可在真机与模拟器上保持一致体验。
案例演示
HarmonyOS 版示例可展示礼物动画、动态资源替换、循环播放等功能
下载安装
ohpm install @ohos/yyevac
OpenHarmony ohpm 环境配置等更多内容，请参考如何安装 OpenHarmony ohpm 包
使用说明
1. 引入组件与常量
import {
EvaAnimComponent,
EvaAnimPlayer,
IEvaFetchResource,
OnEvaResourceClickListener,
EvaConstant
} from '@ohos/yyevac';
2. 创建与挂载播放器
private abilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
@State player: EvaAnimPlayer = new EvaAnimPlayer(this.getUIContext(), 'DemoPlayer');
build() {
Column() {
EvaAnimComponent({ playerEva: this.player, hitTestBehaviorMode: HitTestMode.Default })
.width('100%')
.height('80%');
Button('Play').onClick(async () => {
const rawFd = await this.abilityContext.resourceManager.getRawFd('effect.mp4');
this.player.startPlayByRawFile(this.abilityContext, 'effect.mp4', rawFd);
});
Button('Stop').onClick(() => this.player.stop());
}
}
3. 动态资源替换
class EvaFetchResource implements IEvaFetchResource {
constructor(private ability: common.UIAbilityContext) {}
async setImage(resource: EvaResource,
done: (pixelMap: image.PixelMap | null, fit: EvaSrc.FitType | null) => void) {
if (resource.tag === 'anchor_avatar1') {
const buffer = await this.ability.resourceManager.getMediaContent($r('app.media.avatar').id, 0);
const img = await image.createImageSource(buffer.buffer).createPixelMap();
done(img, null);
img.release();
} else {
done(null, null);
}
}
setText(resource: EvaResource, done: (res: EvaResource) => void): void {
if (resource.tag === 'anchor_nick') {
resource.text = 'YYEVA USER';
}
done(resource);
}
releaseSrc(): void {}
}
this.player.setFetchResource(new EvaFetchResource(this.context));
4. 监听播放事件
import { emitter } from '@kit.BasicServicesKit';
emitter.on(EvaConstant.EVENT_ID_ON_VIDEO_START, data => {
console.info('YYEVA start', JSON.stringify(data));
});
// 页面销毁时清理
emitter.off(EvaConstant.EVENT_ID_ON_VIDEO_START);
核心类与API接口说明
核心类
| 名称 | 类型 | 作用 |
|---|---|---|
EvaAnimPlayer |
类 | 播放控制器，负责加载、播放、暂停、释放资源等完整生命周期管理。 |
EvaAnimComponent |
组件 | ArkTS UI 组件，承载播放器渲染画布并和 EvaAnimPlayer 绑定。 |
IEvaFetchResource |
接口 | 提供动态资源回调，在渲染前替换图片、文本、音频等。 |
OnEvaResourceClickListener |
接口 | 捕获动画内元素点击事件，便于实现交互。 |
EvaResource |
数据结构 | 描述动画中可替换资源的 meta 信息（tag、文本、尺寸等）。 |
核心类说明
EvaAnimPlayer：
EvaAnimPlayer 是播放控制器，负责加载、播放、暂停、释放资源等完整生命周期管理。
属性
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
isNormalMp4 |
boolean | 否 | 是否为不透明 MP4，默认 false。 |
playLoop |
number | 否 | 循环播放次数（通过 setter 同步到解码器）。 |
isLoop |
boolean | 否 | 是否无限循环（通过 setter 同步到解码器）。 |
isSetLastFrame |
boolean | 否 | 是否停留在最后一帧，默认 false。 |
videoMode |
number | 否 | 视频模式，默认 EvaConstant.VIDEO_MODE_NORMAL_MP4。 |
blendMode |
number | 否 | 混合模式，默认 EvaBlendMode.BLEND_SRC_ALPHA。 |
EvaAnimComponent：
EvaAnimComponent 是承载播放器渲染画布并绑定 EvaAnimPlayer 的 ArkTS UI 组件。
属性
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
playerEva |
IEvaAnimPlayer |
是 | 绑定播放器实例，用于驱动渲染与播放控制。 |
xcompID |
string | 否 | XComponent 组件 ID；为空时会在 aboutToAppear 中自动生成 EvaAnimComponent + uuid。 |
xType |
XComponentType |
否 | XComponent 类型，默认 XComponentType.SURFACE。 |
evaView |
EvaAnimView |
否 | 组件内部使用的控制器实例，默认 new EvaAnimView()。 |
hitTestBehaviorMode |
HitTestMode |
否 | 命中测试行为，默认 HitTestMode.Default。 |
IEvaFetchResource：
IEvaFetchResource 是动态资源获取接口，用于在渲染前替换图片、文本等资源。
方法
| 方法名 | 签名 | 必填 | 说明 |
|---|---|---|---|
setImage |
(resource: EvaResource, result: (bitmap: image.PixelMap | null, fitType: EvaSrc.FitType | null) => void) => void |
是 | 获取图片资源并通过回调返回 PixelMap 和适配方式。 |
setText |
(resource: EvaResource, result: (resource: EvaResource) => void) => void |
是 | 获取文字资源并通过回调返回更新后的 EvaResource。 |
releaseSrc |
(resources: EvaResource[]) => void |
是 | 资源释放通知，用于清理缓存等。 |
OnEvaResourceClickListener：
OnEvaResourceClickListener 是资源点击监听接口，用于处理动画内资源的点击事件。
方法
| 方法名 | 签名 | 必填 | 说明 |
|---|---|---|---|
onClick |
(resource: EvaResource) => void |
是 | 点击资源回调，返回被点击的资源信息。 |
EvaResource：
EvaResource 是资源描述类，用于承载可替换资源的元信息。
属性
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
id |
string | 否 | 资源 ID。 |
type |
EvaSrc.SrcType |
否 | 资源类型，默认 EvaSrc.SrcType.UNKNOWN。 |
loadType |
EvaSrc.LoadType |
否 | 加载类型，默认 EvaSrc.LoadType.UNKNOWN。 |
tag |
string | 否 | 资源标签，用于匹配替换。 |
scaleMode |
string | 否 | 缩放模式，示例：scaleFill、aspectFit、aspectFill。 |
bitmap |
image.PixelMap | null |
否 | 图片资源 PixelMap。 |
text |
string | null |
否 | 文本内容。 |
textColor |
number | 否 | 文本颜色，默认 -1。 |
fontSize |
number | 否 | 文本字号。 |
textAlign |
string | null |
否 | 文本对齐方式。 |
typeFace |
string | null |
否 | 字体样式，字体族名。 |
方法
| 方法名 | 签名 | 必填 | 说明 |
|---|---|---|---|
constructor |
(src: EvaSrc) => EvaResource |
是 | 由 EvaSrc 构造资源描述实例。 |
核心API接口
| 方法 | 说明 |
|---|---|
startPlayByRawFile(context, fileName, rawFd) |
播放应用资源目录中的混合 MP4。 |
pause() |
暂停播放。 |
resume() |
恢复播放。 |
stop() |
停止播放并释放底层解码器。 |
setMute(isMute: boolean) |
控制播放器静音状态。 |
setLoop(loop: boolean) |
设置是否循环播放。 |
setSpeed(speed: number) |
调整播放速度（倍率）。 |
setFetchResource(evaFetchResource: IEvaFetchResource | null) |
设置资源获取器。 |
setOnResourceClickListener(evaResourceClickListener: OnEvaResourceClickListener | null) |
设置资源点击监听器。 |
接口图标速览
| 图标 | 功能名称 | 方法 | 说明 |
|---|---|---|---|
[🔗] |
设置资源 | setFetchResource(fetcher) |
绑定 IEvaFetchResource 动态替换图片、文本等。 |
[▶] |
播放视频 | startPlayByRawFile(context, fileName, rawFd) |
从应用资源启动播放。 |
[⏸] |
暂停视频 | pause() |
暂停当前播放进度。 |
[⏹] |
停止视频 | stop() |
停止播放并释放底层资源。 |
[⏯] |
继续视频 | resume() |
从暂停位置继续播放。 |
[🔇] |
静音控制 | setMute(isMute) |
切换播放静音状态。 |
[🔁] |
重播视频 | restart() |
重新从头播放当前动画。 |
[🚀] |
动画开始回调 | emitter.on(EvaConstant.EVENT_ID_ON_VIDEO_START, handler) |
订阅动画启动等事件（EVENT_ID_ON_VIDEO_CONFIG_READY, EVENT_ID_ON_VIDEO_START, EVENT_ID_ON_VIDEO_RESTART, EVENT_ID_ON_VIDEO_RENDER, EVENT_ID_ON_VIDEO_COMPLETE, EVENT_ID_ON_VIDEO_DESTROY）。 |
[🛑] |
关闭回调监听 | emitter.off(EvaConstant.EVENT_ID_ON_VIDEO_START) |
取消动画播放状态监听等事件（EVENT_ID_ON_VIDEO_CONFIG_READY, EVENT_ID_ON_VIDEO_START, EVENT_ID_ON_VIDEO_RESTART, EVENT_ID_ON_VIDEO_RENDER, EVENT_ID_ON_VIDEO_COMPLETE, EVENT_ID_ON_VIDEO_DESTROY）。 |
图标使用 ASCII 包裹的提示符号，方便在纯文本环境中阅读。
约束与限制
在下述版本验证通过：
- DevEco Studio版本: 6.0.0.868, SDK: API18 Release(5.1.0)
已知限制
API18 环境限制说明
本库基于 OpenHarmony API 18 (SDK 5.1.0)开发，在 API18 环境以下存在以下功能限制：
| 限制项 | 说明 | 影响范围 |
|---|---|---|
| 设置混合资源图片 | IEvaFetchResource.setImage 暂不支持，pixelMap.clone()方法仅在API18及以上才支持 |
在API18以下无法填充图片 |
升级建议
提示: 如需获得完整功能支持，建议升级至 API18 或更高版本的 SDK。
目录结构
ohos_YYEVA/
├── entry/ # Stage Ability 示例，演示播放、下载等场景
├── library/ # YYEVA ArkTS 引擎库，导出播放器能力
│ └── src/
│ └── main/
│ └── ets/
│ └── EvaAnimConfig.ets # 解析动画配置
│ EvaAnimConfigManager.ets # YYEVA 配置管理器，负责解析和管理动画配置
│ EvaAnimPlayer.ets # 播放器
│ decoder # 编解码
│ file # 文件管理
│ inter # 定义动态资源获取和替换功能、设置资源监听
│ mix # 混合动画插件，负责处理混合渲染功能
│ plugin # 动画插件管理器，负责管理所有动画插件
│ util # 各种工具类
│ view #视图类，设置回调
├── AppScope/ # 应用范围配置
├── hvigorfile.ts # 根级 Hvigor 构建配置
├── oh-package.json5 # ohpm 依赖与项目信息
└── README_zh.md # 说明文档
entry 模块包含两个示例页面：Eva Demo 展示播放/暂停/静音/重播等控制，Eva Download Demo 演示下载后播放流程。
关于混淆
- 代码混淆，请查看代码混淆简介
- 如果希望yyevac库在代码混淆过程中不会被混淆，需要在混淆规则配置文件obfuscation-rules.txt中添加相应的排除规则：
-keep
./oh_modules/@ohos/yyevac
开源协议
本项目基于 Apache License 2.0 ，请自由地享受和参与开源。