hy/aslan-h5

Fork 0

zhx 572c4cee1b fix: switch h5 assets to global interaction cos

2026-07-08 19:46:39 +08:00

7.8 KiB

Raw Permalink Blame History

VAP 播放接入说明

本文档整理当前项目中 VAP mp4 播放相关的组件、工具函数和活动页用法，方便后续复用、排查和扩展。

文件	作用
`src/components/VapMp4Player.vue`	通用 VAP 播放组件，支持全屏弹层和页面内嵌播放
`src/utils/vapMp4Config.js`	从 mp4 文件中解析 `vapc` 配置并缓存
`src/views/Activities/ActiveGame/vapBg.vue`	ActiveGame 顶部动图背景封装
`src/views/Activities/ActiveGame/index.vue`	ActiveGame 中背景 VAP、奖励全屏 VAP 和预加载示例
`src/config/imagePaths.js`	OSS 图片/视频 URL 生成，包含 `getMp4Url`
`src/utils/protectedAssets.js`	受保护资源地址的编码和还原

播放组件

VapMp4Player.vue 是项目里的通用播放器，内部使用 video-animation-player。

基础用法：

<VapMp4Player
  v-model="show"
  :src="mp4Url"
  mode="overlay"
  fit="contain"
  :loop="false"
  :mute="false"
  :auto-close="true"
  :show-close="true"
  :show-status="false"
/>

主要参数：

参数	类型	默认值	说明
`modelValue`	Boolean	`false`	控制播放组件显示，支持 `v-model`
`src`	String	`''`	mp4 地址
`mode`	String	`'overlay'`	`overlay` 为全屏弹层，`inline` 为页面内嵌
`fit`	String	`'contain'`	`contain`、`cover`、`fill`
`loop`	Boolean	`false`	是否循环播放
`mute`	Boolean	`false`	是否静音
`accurate`	Boolean	`true`	传给 VAP 播放器的精准模式
`autoClose`	Boolean	`true`	非循环播放结束后是否自动关闭
`showClose`	Boolean	`true`	全屏弹层是否展示关闭按钮
`showStatus`	Boolean	`true`	是否展示加载/错误状态文案
`vapData`	Object	`{}`	额外透传给 `new Vap().play()` 的参数

事件：

事件	说明
`update:modelValue`	更新显示状态
`loaded`	VAP 进入 playing 后触发
`ended`	播放结束
`error`	加载或播放失败
`close`	调用关闭逻辑后触发

注意：

overlay 模式会通过 Teleport 挂到 body，默认 z-index: 3000。
inline 模式是 position: absolute; inset: 0，父容器需要有明确尺寸和定位。
组件内部会先调用 resolveProtectedAssetUrl(src)，因此可以直接传 getMp4Url 生成的受保护地址。

VAP 配置解析

src/utils/vapMp4Config.js 负责从 mp4 中读取名为 vapc 的 box，并解析其中的 JSON 配置。

导出方法：

getVapConfigFromMp4(mp4Url)
preloadVapConfig(mp4Url)
clearVapConfigCache(mp4Url)

说明：

getVapConfigFromMp4(mp4Url) 会 fetch 整个 mp4，读取 ArrayBuffer 后查找 vapc。
解析结果以 mp4Url 为 key 缓存在 configCache 中，重复播放同一个地址不会重复解析。
preloadVapConfig(mp4Url) 适合页面预加载阶段使用，失败会吞掉错误并返回 null。
clearVapConfigCache(mp4Url) 可清除某个地址或全部缓存。

常见错误：

错误	可能原因
`vapc box not found`	mp4 不是 VAP 格式，或没有内嵌 VAP 配置
`mp4 request failed: xxx`	地址不可访问、跨域、鉴权、OSS 路径错误
`vapc box does not contain json`	`vapc` 存在但内容不是合法 JSON

mp4 地址约定

src/config/imagePaths.js 中提供了 mp4 URL 方法：

getRawMp4Url(imagePath, filename)
getMp4Url(imagePath, filename)

示例：

import { getMp4Url } from '@/config/imagePaths.js'

const mp4Url = (filename) => getMp4Url('Activities/ActiveGame/', filename)
const bgVapUrl = mp4Url('bg')

生成的线上地址形如：

https://asset.global-interaction.com/h5/Azizi/Activities/ActiveGame/bg.mp4

开发环境会走：

/oss/h5/Azizi/Activities/ActiveGame/bg.mp4

如果资源路径属于受保护范围，getMp4Url 会返回保护后的地址。播放器或预加载工具在真正 fetch 前需要用 resolveProtectedAssetUrl 还原。VapMp4Player.vue 内部已经处理播放时的还原；页面手动预加载时也要处理：

import { preloadVapConfig } from '@/utils/vapMp4Config.js'
import { resolveProtectedAssetUrl } from '@/utils/protectedAssets.js'

await preloadVapConfig(resolveProtectedAssetUrl(bgVapUrl))

ActiveGame 当前用法

顶部背景 VAP

src/views/Activities/ActiveGame/vapBg.vue 用于顶部背景：

<VapBg class="vap-background-layer" :src="bgVapUrl" />

内部实际使用：

<VapMp4Player
  v-model="backgroundVisible"
  :src="src"
  mode="inline"
  fit="cover"
  :loop="true"
  :mute="false"
  :auto-close="false"
  :show-status="false"
/>

页面样式中给背景 VAP 固定区域：

.vap-background-layer {
  width: 100vw;
  height: 150vw;
  position: absolute;
  top: 0;
  left: 0;
  z-index: 1;
  pointer-events: none;
}

奖励全屏 VAP

点击奖励展示的左侧奖励图时，展示全屏居中的 VAP：

<VapMp4Player
  v-model="rewardVapShow"
  :src="rewardVapUrl"
  mode="overlay"
  fit="contain"
  :loop="false"
  :mute="false"
  :auto-close="true"
  :show-close="true"
  :show-status="false"
  @error="handleRewardVapError"
/>

当前临时地址：

const rewardVapUrl =
  'https://asset.global-interaction.com/svgasource/manager-d824e59b-1a88-4d4f-aed3-01768ba20542.mp4'

预加载建议

如果页面打开后要尽快展示 VAP，建议同时做两件事：

在页面预加载阶段调用 preloadVapConfig。
不要等 loading 结束后才挂载 VAP 组件，可以让页面在 loading 遮罩下先挂载，VAP 提前初始化。

ActiveGame 当前预加载示例：

await Promise.all([
  preloadImages(criticalImages),
  preloadVapConfig(resolveProtectedAssetUrl(bgVapUrl)),
  preloadVapConfig(rewardVapUrl),
])

说明：

bgVapUrl 来自 getMp4Url，需要先 resolveProtectedAssetUrl。
rewardVapUrl 是普通完整 OSS 地址，可以直接传入。
preloadVapConfig 主要预热 VAP 配置解析和浏览器请求缓存，但最终播放仍由 VapMp4Player 创建 canvas 和播放器实例。

接入新页面步骤

准备带 vapc 配置的 VAP mp4 文件。
如果放在活动 OSS 目录，使用 getMp4Url('Activities/xxx/', 'filename') 生成地址。
页面中引入 VapMp4Player.vue。
全屏播放用 mode="overlay"，页面背景或局部播放用 mode="inline"。
页面预加载阶段调用 preloadVapConfig(resolveProtectedAssetUrl(mp4Url))。
对 @error 做兜底提示或日志，避免静默失败。

全屏弹层模板：

<VapMp4Player
  v-model="vapShow"
  :src="vapUrl"
  mode="overlay"
  fit="contain"
  :loop="false"
  :auto-close="true"
/>

页面背景模板：

<div class="vap-bg">
  <VapMp4Player
    v-model="vapVisible"
    :src="vapUrl"
    mode="inline"
    fit="cover"
    :loop="true"
    :auto-close="false"
    :show-close="false"
    :show-status="false"
  />
</div>

.vap-bg {
  position: absolute;
  width: 100vw;
  height: 150vw;
  overflow: hidden;
  pointer-events: none;
}

排查清单

页面空白或不播放：确认组件 modelValue 为 true，src 非空。
只有 loading 不结束：确认页面预加载流程有 finally 关闭 loading。
提示找不到 VAP 配置：确认 mp4 内有 vapc box。
本地能播线上不能播：检查 OSS 路径、跨域、资源保护地址是否还原。
inline 不显示：确认父容器有 position: relative/absolute 和明确宽高。
overlay 被遮挡：检查是否有更高的 z-index；默认播放器弹层是 3000。
背景遮挡内容：检查页面层级，ActiveGame 当前是页面背景 z-index: 0、VAP 背景 z-index: 1、页面内容 z-index: 2。

7.8 KiB Raw Permalink Blame History Unescape Escape