更新记录

1.2.1（2026-09-17） 下载此版本

1.2.0 已上架（2026-09-17）。本版待内容 —— 候选：App 端性能旋钮调优 （accurate 绘制时钟 / pixelRatio 画布像素比 / frameThrottle 回调节流 / precache 预读）， 以及 H5 端按设备像素比渲染（高清屏更锐）。发布前请把本节替换为实际改动。

1.2.0（2026-09-17） 下载此版本

App（Android / iOS，vue 页面）支持：renderjs + vap.min.js（WebGL）

动机：传统 uni-app 的 App 端此前完全没有支持（只在 H5 / 微信小程序可用）。而"原生 UI 组件" 在传统 uni-app 里只能放 nvue（官方文档明确 nvue 已不再维护、且不支持鸿蒙）， 所以走官方推荐的另一条路：在 App-vue 页面里用 renderjs 跑 web 引擎。

为什么选它：

• 不需要自定义基座 ✓ —— renderjs 是 uni-app 内置能力，纯 JS + WebGL，不引入任何原生插件 （对比：lime-pag 60 元、sn-vap 30 元都要求自定义基座）；
• 位置/尺寸由正常 CSS 布局决定 ✓ —— 内联小尺寸（头像挂件、列表卡片）与全屏覆盖层都能用 （对比：UTS 原生"全屏视图"方案只能做覆盖层，场景被窄化）；
• 复用 H5 那份 vap.min.js ✓ —— 同一套引擎代码，行为与 H5 一致（含融合元素、accurate 精确时钟）。

实现：逻辑层只做控制与事件（#ifdef APP-PLUS 分支下发 viewProp / viewCmd）， 渲染全部在视图层的 renderjs 模块（vapRender）里；事件经 ownerInstance.callMethod('onViewEvent') 回传，因此组件的 API 与 H5 / 微信两端完全一致（play/pause/stop/setTime/on、@ready/@frame/@finish/@click）。 尺寸按【容器盒子 + 素材宽高比】contain；融合元素点击命中检测仍在逻辑层（视图层拿不到 vapc 解析器）。 同时带上了 H5 端的两条教训：轮询抓 document.body 上的 <video> + 解静音降级；销毁前先 pause 再 destroy。

真机验证结果（Android 标准基座，2026-09-16）：✅ 通过。 引擎正常启动（77x60 内联 / 316x708 全屏 ✓）、内联与多实例可用 ✓、绘制帧率 25 fps（与素材一致 ✓）。

真机联调中发现并修掉的引擎自身缺陷（都在组件内处理，使用者无需关心）：

1. display:none 拖死绘制时钟 ✗：引擎给注入的 <video> 设 display:none，而 WebView 不给隐藏视频 提交帧 ⇒ 它自己的 requestVideoFrameCallback（accurate=true 时的时钟）几乎不回调。 实测恒定 4~5 fps，且与画布大小无关（77×60 的迷你画布同样慢 ⇒ 排除填充率）。 组件改为"不可见的普通元素"后立刻恢复到素材帧率（25 fps）。
2. fps 必须是 60 的约数 ✗：accurate=false 的 rAF 节拍是 n % (60/fps)（浮点取模）， fps=25 ⇒ 2.4 ⇒ 永不为 0 ⇒ 一帧都不画。组件在 App 端自动吸附到最大 60 约数。
3. 引擎把 video 挂在 document.body（不在容器内）⇒ 多实例时不能用"最后一个 video"定位， 组件用构造前后的差集认领自己的那个。

鸿蒙真机补充（2026-09-16）：✅ 鸿蒙亦可运行 —— renderjs 在鸿蒙 ArkWeb 上正常工作 （24~26 fps，与 Android 同级），此前依据社区报告得出的"鸿蒙不支持 renderjs"结论被实测推翻。 过程中的两处修正：① App 分支原先只写 #ifdef APP-PLUS，而鸿蒙构建不定义该键（只定义 APP-HARMONY） ⇒ 鸿蒙上根本没跑 renderjs，现改为 APP-PLUS || APP-HARMONY；② 鸿蒙 ArkWeb 的 window.devicePixelRatio 为 1（会导致缓冲偏小、画面发虚）⇒ 组件改用 uni.getWindowInfo().pixelRatio。 另：ArkWeb 不允许页面从 file:// 取图 ⇒ App 端融合图片请用 http(s) / data: 地址。

状态：✅ 已真机验证并发布 —— 平台声明已开启 App（vue 页面：Android / iOS / 鸿蒙）。 App 实现走 renderjs + WebGL，不需要自定义基座；nvue 仍不支持（renderjs 只作用于 vue 页面）， 需要原生渲染或 uni-app x 工程请用付费版 axen-vap-x。

1.1.0（2026-09-16） 下载此版本

本版相对 1.0.0（已上架）的唯一主题：传统 uni-app vue2 工程可用。 1.0.0 上架时机早于本项工作（其线上平台表中 Vue2 仍为 -），故独立发版。

Vue2 工程支持验证通过（含 4 个 vue2 专属坑的修复）

在传统 uni-app vue2 工程里完成真机验证：App 启动、组件挂载、融合文字/头像、mode 0 音频、 无音轨素材自动 remux、帧数与比例全部正常。过程中修掉 4 个只在 vue2 复现的问题：

1. main.js 与 vueVersion 必须匹配：vue2 要用 App.mpType='app' + new Vue({...App})； 用 Vue3 的 createSSRApp 会报 Cannot set properties of undefined (setting 'query') （框架挂 $mp 的 mixin 未注册所致，排查过程见 TROUBLESHOOTING 附·A）；
2. 事件回调别取页面生命周期名：onReady 等会被 vue2 编译器从 methods 摘走 ⇒ 报 Page "xxx" does not have a method "onReady"；demo 统一改为 vap* 前缀；
3. 方法名不能与 data 键同名（Method "xxx" has already been defined as a data property）—— 已加静态检查 check-demo-page.sh 兜住；
4. :style 对象对原生组件在 vue2 下不生效：<canvas> 的尺寸改为字符串 style， 并给 .vap-canvas 加 width/height:100% 兜底（宿主已有确定宽高）。

平台兼容性

uni-app(3.8.4)

uni-app x(4.0)

axen-vap VAP 视频动画特效组件（传统 uni-app · 免费版）

传统 uni-app 工程（Vue2 / Vue3）用本免费版即可：H5 + 微信小程序 + App（Android / iOS / 鸿蒙）。 App 端走 WebView + WebGL，不需要自定义基座 —— 装进项目就能运行。 uni-app x 工程，或需要原生渲染（Metal / OpenGL / OHOS-VAP）：请用付费版 axen-vap-x。

✨ 特性

• 透明度动效：VAP 素材（mp4）逐帧渲染，支持透明通道
• 融合元素：头像 / 昵称 / 图片 / 文字随帧合成；文字样式可在运行时覆盖
• 融合元素点击：@click 回传被点元素的 tag（如 [sImg1]）
• 完整事件：ready / started / frame / finished / ended / error / destroy
• 可内联可全屏：位置与尺寸由正常布局决定 —— 头像挂件、列表卡片、全屏覆盖层都能用
• 声音：有音轨素材出声；无音轨素材自动补静音轨走同一条链路（不会静默降级）
• 三端同一套 API：H5 / 微信小程序 / App 的属性、事件、方法完全一致，切换平台不改代码
• 不支持的平台不静默：会 console.error + @error（code: 3），不会留一片空白

📦 安装

在插件市场导入本插件（uni_modules 规范），或在 uni_modules/ 下放置本目录。

组件遵循 easycom，无需注册即可使用：

<axen-vap :src="src" :config="config" />

🚀 快速开始

<template>
    <view style="width: 750rpx; height: 340rpx">
        <axen-vap
            :src="src"
            :config="config"
            :ext="ext"
            :loop="false"
            :autoplay="true"
            @started="vapStarted"
            @click="vapClick"
            @error="vapError"
        />
    </view>
</template>

<script>
    export default {
        data() {
            return {
                // App / H5 可直接传 http(s) 地址；微信端需要**本地文件路径**（先 uni.downloadFile）
                src: '/static/demo.mp4',
                // vapc 配置：JSON 字符串或对象（微信端建议显式传入）
                config: require('@/static/demo.json'),
                // 融合元素：键 = 素材里的 srcTag 去掉方括号
                ext: {
                    sImg1: 'https://your.cdn/avatar.png',
                    sTxt1: '星河Momo 欢迎进入直播间'
                }
            }
        },
        methods: {
            // ⚠️ 回调名别用页面生命周期名（onReady/onShow/onLoad…），vue2 下会被编译器摘走 —— 见「使用前提」
            vapStarted() { console.log('开始播放') },
            vapClick(e) { console.log('点击了融合元素', e.detail.tag) },
            vapError(e) { console.error('播放失败', e.detail) }
        }
    }
</script>

本插件所在工程 uni-vap-demo/ 就是可运行 demo（场景卡片 + 全屏动效），可直接运行对照。

📖 API 文档

属性

事件

错误码

方法（ref）

⚠️ 使用前提（4 条，不注意会"看起来像坏了"）

1. 融合图片/视频的地址规则

融合图片会被引擎以 crossOrigin="anonymous" 加载 ⇒ 服务端必须返回 access-control-allow-origin。 例：q1.qlogo.cn（QQ 头像）不返回该头 ⇒ 头像不会显示。选图前先 curl -I 确认一下。 图片加载失败只影响该元素，不会中断播放。

2. 微信端

• 素材放服务器，运行时 uni.downloadFile（主包只有 2MB）。
• config 建议显式传入（引擎按它确定拼版与总帧数）。

3. Vue2 工程（uni-app 规则，非本插件问题）

1. main.js 必须与 manifest.json 的 vueVersion 匹配：vue2 用 App.mpType='app' + new Vue({...App})。 两者不一致会报 Cannot set properties of undefined (setting 'query')。
2. 事件回调别取页面生命周期名（onReady/onShow/onLoad/onError…）：vue2 编译器会把它们从 methods 里摘走当生命周期用；也别与 data 键同名。统一加前缀（如 @ready="vapReady"）即可。

4. 不支持的平台不会静默

nvue 页面、其它小程序、uni-app x 工程会打 console.error 并触发 @error（code: 3）—— 不会留一片空白让你猜。原因与完整平台矩阵见 PLATFORMS.md。

日志

组件默认静默（与付费版一致）。排查时两种打开方式，都不用改插件源码：

• 页面里设置 uni.$vapDebug = true（设置之后开始的播放即生效）；
• 或 VapLog.setDebug(true)（common/vap-log.js 的默认导出）。

warn / error 始终输出（remux 失败、音频挂载失败、融合图片失败、播放提前结束等）。

免费版 / 付费版怎么选

需要原生渲染性能、或工程是 uni-app x ⇒ 请用 axen-vap-x。

平台实现细节

各端引擎、取帧节拍、音频链路、鸿蒙 ArkWeb 注意点等实现细节统一放在 PLATFORMS.md（本文件只讲怎么用）。

许可证

• H5 内核：腾讯 VAP web 版（MIT）— 见 LICENSE-tencent-vap.txt
• 微信端与 App 端引擎：自研（算法蓝本源自官方 MIT 源码）