更新记录
1.7.5(2026-11-16)
- 修复 Android 云打包中诊断地址脱敏索引的 Number/Int 类型不匹配导致 Kotlin 编译失败的问题。
1.7.4(2026-11-15)
- 修复 iOS 云打包中
NSNumber 索引直接传给 substring 导致 Swift 编译失败的问题。
- 修复 iOS 生成 Swift 对暂停终态键长字符串表达式类型检查超时的问题。
1.7.2(2026-11-15)
- 新增 H5 网络媒体的有限自动重试,按 1 秒、2 秒、4 秒退避并回传等待、尝试、恢复和耗尽状态,视频格式、权限和解码错误继续直接失败。
- 修复 H5 进度条与 Android 轨道、滑块、内边距和状态颜色不一致的问题,统一 2px 轨道、10px 白色滑块和已播放段显示。
- 修复 H5 点击喜欢后没有即时视觉反馈的问题,点击后立即更新红色心形和数量,并继续发送宿主动作回写。
- 修复 H5 选集面板点击无试看锁定集时解锁入口无响应的问题,先切换到锁定集再显示解锁入口,与 Android 行为一致。
- 修复 H5 清屏后残留搜索入口、静音文案与 Android 不一致,以及空列表、加载、缓冲和媒体错误提示文案不统一的问题。
- 修复 H5 播放中控件没有按 Android 自动收起、锁定/失败重试入口被暂停控件开关一并隐藏、图集无音乐仍显示视频时间的问题;补齐标题兜底和相邻页信息开关。
- 修复 H5 加载态缺少 Android 中心加载指示器、图集加载文案误用视频文案,以及媒体尚未暂停时提前显示中心播放按钮的问题。
- 修复 Android 播放设置显示 3×、4× 但公共倍率上限为 2× 的无效入口,H5 与 Android 菜单统一展示可执行档位。
查看更多
平台兼容性
uni-app(5.24)
| Vue2 |
Vue3 |
Chrome |
Safari |
app-vue |
app-nvue |
Android |
iOS |
鸿蒙 |
| √ |
√ |
√ |
√ |
√ |
√ |
√ |
√ |
- |
| 微信小程序 |
支付宝小程序 |
抖音小程序 |
百度小程序 |
快手小程序 |
京东小程序 |
鸿蒙元服务 |
QQ小程序 |
飞书小程序 |
小红书小程序 |
快应用-华为 |
快应用-联盟 |
| √ |
× |
× |
× |
× |
× |
× |
× |
× |
× |
× |
× |
uni-app x(5.24)
| Chrome |
Safari |
Android |
iOS |
鸿蒙 |
微信小程序 |
| √ |
√ |
√ |
√ |
- |
√ |
其他
| 多语言 |
暗黑模式 |
宽屏模式 |
蒸汽模式 |
| × |
× |
√ |
√ |
lizhao-video-feed
在同一信息流中浏览短视频、短剧和图片作品,支持 uni-app 与 uni-app x。
功能特色
适合哪些场景
| 场景 |
推荐能力 |
接入方式与边界 |
| 推荐流、社区作品 |
短视频与图片混排、互动、分页 |
全屏 API;图集支持 App / 微信 / H5 |
| 短剧追看 |
连续播放、选集、试看、续看 |
mode: 'drama';内容授权和订单由应用服务处理 |
| 商品、活动、相册展示 |
手动翻图、自动轮播 |
每个图集 1~20 张静态 JPEG / PNG,可配置背景音乐 |
| 已有页面或 Tab 中播放 |
内嵌组件、显隐通知、同组播放互斥 |
uni-app App 的承载页面及其他平台差异见平台表 |
| 分段点播和临时断网 |
HLS、有限播放恢复 |
Android / iOS / 微信;Harmony 视频支持显式手动恢复,不提供 HLS 或自动重试 |
下载与导入
| 宿主 |
示例代码位置 |
| uni-app |
uni_modules/lizhao-video-feed/example/uniapp/index.vue |
| uni-app x |
uni_modules/lizhao-video-feed/example/uniappx/index.uvue |
从基础到进阶
| 示例约定 |
用法 |
| 资源 |
将 https://example.com/ 下的图片、视频和页面替换为自己的可访问地址 |
| JavaScript 片段 |
适用于 uni-app 页面脚本;含 export function 的片段可保存为业务模块再导入 |
| uni-app x |
配置字段相同;完整页及组件给出带公开类型的 UTS 写法 |
| 事件参数 |
名为 event 的参数取自 onEvent;名为 identity 的参数至少含当前 feedId/sessionId |
| 控制时机 |
除监听、解绑、销毁外,命令在 ready / 打开成功之后调用;所有命令传对象 |
| 本地业务演示 |
分页、评论、互动与解锁中的本地数据仅演示回写;替换为自己的服务处理结果 |
基础功能配置示例(简单示例)
| 用途 |
前置条件 |
运行方式 |
| 打开两条短视频 |
已导入完整插件并准备 HTTPS MP4;平台接入见后文 |
将 openSimpleFeed 绑定到页面按钮 |
import { openVideoFeed } from '@/uni_modules/lizhao-video-feed'
export function openSimpleFeed() {
openVideoFeed({
feedId: 'home-feed', // 应用内唯一;同名会话关闭前不能再次打开。
items: [
{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' }, poster: 'https://example.com/one.jpg' },
{ itemId: 'video-2', source: { url: 'https://example.com/two.mp4' }, poster: 'https://example.com/two.jpg' }
],
options: { mode: 'video' }, // 默认自动播放、当前视频循环;上下滑动可切换作品。
onEvent: (event) => {
// created 后可保存会话身份;ready 才表示承载可以接受播放控制。
if (event.type === 'created') console.log('会话身份', event.feedId, event.sessionId)
if (event.type === 'error') console.log('播放失败', event.error?.errCode)
},
success: (result) => { console.log('界面已就绪', result.sessionId) },
fail: (error) => { console.log('打开失败', error.errCode, error.errMsg) },
complete: (result) => { console.log('本次打开已结算', result.ok) }
})
}
高级示例
| 示例 |
配置范围 |
使用时机 |
| 作品信息 |
条目、作者、互动数量 |
创建列表或回写完整作品快照 |
| 图片轮播 |
图片、间隔、循环、填充 |
普通视频模式的图文作品 |
| 图集配乐 |
音乐来源、音量、循环与独立状态 |
需要在图集内播放音乐时 |
| 播放参数 |
起播、声音、倍率、循环、预载、互斥和超时 |
创建会话时 |
| 媒体源 |
MP4 / HLS、源标识、请求头边界 |
选择媒体来源时 |
| 界面与短剧 |
主题、按钮、手势、面板与选集 |
创建会话时 |
| 有限恢复 |
额外尝试次数和错误观察 |
网络不稳定的点播场景 |
| 手动恢复 |
出错后的显式 play、成功与失败处理 |
用户确认网络或资源已恢复后;支持 Harmony 视频 |
作品、作者与互动数据
// 返回值可放入 openVideoFeed.items,也可作为 updateItem 的完整 item。
export function makeVideoItem() {
return {
itemId: 'video-1', // 稳定业务 ID;列表内不能重复,刷新时不要用随机下标代替。
itemType: 'video', // 省略也按视频处理;图集使用下一个示例。
source: {
url: 'https://example.com/one.mp4', // 已有访问权的 HTTPS MP4。
mediaType: 'mp4', // auto 按路径识别;无后缀的 HLS 必须显式设为 hls。
sourceId: 'original', // 应用自己的非敏感资源标识,不代替真实地址。
headers: [] // 当前不支持媒体自定义请求头;使用签名 URL 等可播放资源。
},
poster: 'https://example.com/one.jpg', // 建议显式提供,切页前显示封面。
title: '城市日落', // 作品标题;不是顶部频道标题。
itemDescription: '一段可以展开的作品介绍', // 可折叠简介。
durationHintMs: 30000, // 仅展示时长,单位毫秒;不改变真实 seek 或试看边界。
author: {
authorId: 'author-1', name: '城市记录者', // name 为空字符串时隐藏作者名。
avatar: 'https://example.com/avatar.jpg', // 加载失败时显示占位。
followed: false // 已确认的关注状态;点击关注不会自动修改它。
},
interaction: {
likeCount: 12, commentCount: 3, favoriteCount: 2, shareCount: 1, // 非负整数,省略为 0。
liked: false, favorited: false // 应用确认的状态;业务成功后通过 updateItem 回写。
}
}
}
图片与视频混排、自动翻图
import { openVideoFeed, getVideoFeedCapabilities } from '@/uni_modules/lizhao-video-feed'
export function openPhotoFeed() {
const capability = getVideoFeedCapabilities()
if (capability.galleryPlayback !== true) { console.log('当前平台不支持图集'); return }
openVideoFeed({
feedId: 'photo-feed',
items: [
{ itemId: 'photos-1', itemType: 'gallery', title: '旅行相册', gallery: {
images: [ // 1~20 张;同一图集内 imageId 唯一,url 使用自己的静态 JPEG / PNG。
{ imageId: 'photo-1', url: 'https://example.com/photo-1.jpg' },
{ imageId: 'photo-2', url: 'https://example.com/photo-2.jpg' }
],
autoplay: true, // 默认 false;图片真实显示后才开始自动轮播。
intervalMs: 3000, // 1000~10000 的整数毫秒;每张的完整停留间隔。
loop: true, // 默认 false;自动轮播到末图后是否返回首图。
objectFit: 'contain' // 默认 contain 完整显示;cover 填满并可能裁切。
} },
{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' } }
],
options: { mode: 'video' }, // 图集不能用于 drama 模式,不能同时携带视频源或时长。
onEvent: (event) => {
if (event.type === 'imagechange' && event.state.gallery != null) {
console.log('当前图片', event.state.gallery.imageIndex + 1, '/', event.state.gallery.imageCount)
}
if (event.type === 'imageload') console.log('当前图片已显示')
if (event.type === 'imageerror') console.log('图片失败', event.error?.errCode)
},
fail: (error) => { console.log('打开图集失败', error.errCode) }
})
}
| 操作 |
图片作品的表现 |
| 左右滑动 |
切换同一图集的图片;底部短横仅提示位置,不提供拖动跳转 |
| 上下滑动 |
切换到下一条图片或视频作品 |
| 自动轮播 |
还受会话播放意图、活跃状态、前后台、触摸和面板限制 |
| 单图或清屏 |
单图不显示多图提示;清屏、面板和 ui.showProgress: false 隐藏提示 |
| 大图操作 |
使用效果 |
| 查看大图 |
当前图片成功显示后可进入;支持缩放、拖动、复位,关闭后回到原图集 |
| 自动轮播 |
查看期间暂停翻图,保留会话原播放意图和音乐门禁;换项或卸载时关闭旧预览 |
大图入口默认开启,需要关闭时在创建会话的 options 中配置:
const options = { ui: { showImagePreview: false } } // 同样适用于组件 initial-options。
图集背景音乐
| 用途 |
准备 |
控制方式 |
| 给图集配乐 |
提供可访问的图片和 MP3 / M4A;替换示例地址并查询当前构建能力 |
当前图集首次有图片真实显示且播放条件允许后播放;切图不重建音轨,播放控制见会话方法 |
uni-app
import { openVideoFeed, getVideoFeedCapabilities } from '@/uni_modules/lizhao-video-feed'
export function openMusicGallery() {
const capability = getVideoFeedCapabilities()
if (capability.galleryPlayback !== true || capability.galleryMusic !== true) {
console.log('当前构建暂不支持图集配乐')
return
}
openVideoFeed({
feedId: 'music-gallery',
items: [{
itemId: 'photos-with-music', itemType: 'gallery',
gallery: {
images: [
{ imageId: 'photo-1', url: 'https://example.com/photo-1.jpg' },
{ imageId: 'photo-2', url: 'https://example.com/photo-2.jpg' }
],
music: { url: 'https://example.com/your-music.mp3', loop: true, volume: 0.7 }
}
}],
onEvent: (event) => {
const music = event.state.gallery?.music
if (music != null) console.log('音乐状态', music.status, music.positionMs, music.durationMs)
if (event.type === 'musicerror') console.log('音乐播放失败', event.error?.errCode)
},
fail: (error) => { console.log('打开失败', error.errCode) }
})
}
uni-app x
import { openVideoFeed, getVideoFeedCapabilities, VideoFeedItem, VideoFeedEvent } from '@/uni_modules/lizhao-video-feed'
export function openMusicGalleryX(): void {
const capability = getVideoFeedCapabilities()
if (capability.galleryPlayback != true || capability.galleryMusic != true) { return }
const item: VideoFeedItem = {
itemId: 'photos-with-music', itemType: 'gallery',
gallery: {
images: [{ imageId: 'photo-1', url: 'https://example.com/photo-1.jpg' }],
music: { url: 'https://example.com/your-music.mp3', loop: true, volume: 0.7 }
}
}
openVideoFeed({
feedId: 'music-gallery', items: [item],
onEvent: (event: VideoFeedEvent): void => {
if (event.type == 'musicerror') console.log('音乐播放失败', event.error)
}
})
}
| 配置 / 观察 |
使用方式 |
| 音乐与翻图 |
gallery.music.loop 控制音乐循环,gallery.loop 控制图片轮播,两者独立;不需要音乐时省略 music,不要传入显式 null |
| 音乐状态 |
从 event.state.gallery?.music 读取音轨状态和毫秒时间;尚未报告时该字段可能不存在,音乐状态变化通过 statechange 观察 |
| 音乐失败 |
musicerror 的错误码为 9093008;图片状态保持独立,可继续观察 imageload / imageerror |
| 声音与页面 |
会话播放意图、静音、页面活跃状态、后台和互斥都会影响音轨;iOS 系统音频策略由宿主决定;此功能不承诺后台持续播放 |
播放、预载与会话配置
import { openVideoFeed } from '@/uni_modules/lizhao-video-feed'
export function openConfiguredFeed() {
openVideoFeed({
feedId: 'configured-feed',
items: [{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' } }],
options: {
mode: 'video', initialItemId: 'video-1', // 起始 ID 必须在当前列表内。
initialPositionMs: 2000, // 从 2 秒开始;必须在真实时长和试看许可范围内。
autoplay: true, active: true, // 自动播放意图与页面活跃状态分别控制。
muted: false, rate: 1, // rate 是基础倍率,实际允许范围先查平台能力。
objectFit: 'cover', // contain 完整包含;cover 裁切铺满。
loop: true, autoNext: false, // 两者不能同时 true;连续播下一条则 loop=false、autoNext=true。
maxPlayerCount: 2, preloadCount: 1, // 总播放器最多 2 个;设为 1 时必须关闭预载。
playbackGroup: 'home-media', // 同组会话互斥;预载始终静音且不主动播放。
resumeAfterInterruption: true, // 中断结束后仅在其余播放条件满足时恢复。
maxPlaybackRetries: 0, // 默认手动恢复;自动重试示例见下文。
hasMore: false, loadMoreThreshold: 2, // 启用分页时由 loadmore 事件回写结果。
requestTimeoutMs: 30000, // 分页/评论等待;1000~120000 毫秒。
commandTimeoutMs: 15000, // 一次控制命令等待;1000~120000 毫秒。
ui: {
title: '推荐', showProgress: true,
showPauseControls: true, showTitle: true, showMediaHint: true
}
},
fail: (error) => { console.log('配置或打开失败', error.errCode) }
})
}
HLS、源标识与请求头边界
import { openVideoFeed, getVideoFeedCapabilities } from '@/uni_modules/lizhao-video-feed'
export function openHlsFeed() {
const capability = getVideoFeedCapabilities()
if (!capability.hls) { console.log('当前平台不支持 HLS'); return }
openVideoFeed({
feedId: 'hls-feed',
items: [{ itemId: 'hls-1', poster: 'https://example.com/cover.jpg', source: {
url: 'https://example.com/playlist', // 主列表、子列表和分片都需要可访问的 HTTPS 地址。
mediaType: 'hls', sourceId: 'episode-original', headers: [] // 无后缀时显式声明 hls。
} }],
fail: (error) => { console.log('HLS 打开失败', error.errCode) }
})
}
// 仅示范 headers 的公开结构;当前构建不支持自定义媒体头,下面的能力检查会拒绝此分支。
export function openHeaderSource(url) {
const capability = getVideoFeedCapabilities()
if (!capability.mp4Headers) { console.log('请改用已授权且可直接播放的地址'); return }
openVideoFeed({
feedId: 'header-feed',
items: [{ itemId: 'header-video', source: {
url, mediaType: 'mp4', headers: [{ name: 'X-Trace-Id', value: 'request-123' }]
// name 不得重复、含冒号或换行;value 不得含换行;不把密钥写在页面内。
} }],
fail: (error) => { console.log('请求头或来源不支持', error.errCode) }
})
}
短剧、主题、按钮与手势
import { openVideoFeed } from '@/uni_modules/lizhao-video-feed'
export function openDramaFeed() {
openVideoFeed({
feedId: 'drama-feed',
items: [{
itemId: 'episode-1', poster: 'https://example.com/episode-1.jpg', durationHintMs: 60000,
source: { url: 'https://example.com/episode-1.mp4' }, // 只提供已经获得访问权的试看资源。
drama: {
seriesId: 'series-1', episodeId: 'ep-1', episodeNumber: 1, // 同系列 ID 和集序不能重复。
seriesTitle: '示例短剧', seriesTags: ['剧情', '都市'], seriesDescription: '剧集简介',
episodeTitle: '第一集', totalEpisodes: 12, watched: false, // watched 由自己的观看记录回写。
locked: true, trialEndMs: 10000 // 从原时间轴 0 开始试看至 10 秒;没有试看则省略 source 并设 0。
}
}],
options: {
mode: 'drama', loop: false, autoNext: true, // 当前集结束后切换下一集,不自动回到首集。
ui: {
title: '短剧', safeAreaMode: 'auto', // auto 加系统安全区;manual 仅用下面两个 inset。
topInset: 0, bottomInset: 0, // 非负逻辑像素;按宿主导航实际占用填写,避免重复扣安全区。
theme: {
backgroundColor: '#000000', textColor: '#FFFFFF', secondaryTextColor: '#D6D6D6',
accentColor: '#FF375F', iconSize: 36, fontSize: 14 // 图标覆盖 20~48,信息字号 10~24。
},
actions: [{
action: 'like', visible: true, label: '喜欢', // 未列出的入口继续使用默认配置。
icon: 'https://example.com/like.png', activeIcon: 'https://example.com/liked.png'
}],
showBack: true, showFullscreen: true, showSearch: true, // 搜索只发送 action,不执行自己的搜索服务。
showInformation: true, showProgress: true,
showPauseControls: true, showTitle: true, showMediaHint: true,
clearScreen: false,
enableGestures: true, showLongPressMenu: true, // 单击、双击、长按和分页仍由插件仲裁;可关闭中央长按菜单。
longPressRateRegion: 'right-edge', longPressRate: 2, // 指定侧边长按临时 2 倍;结束恢复基础倍率。
commentPlayback: 'shrink', episodePlayback: 'pause', // shrink 依原播放意图继续,pause 暂停。
panelVideoScale: 0.65, // 0.4~0.8;评论态用于顶部媒体区高度。
episodeLayout: 'grid', // list 展示封面与标题;grid 使用紧凑集号。
episodeActions: [ // 最多两个;只产生 episodeaction,应用处理订单或收藏。
{ buttonId: 'buy-series', label: '购买全集', disabled: false, emphasized: true },
{ buttonId: 'save-series', label: '收藏短剧', disabled: false, emphasized: false }
]
}
},
onEvent: (event) => {
if (event.type === 'trialend') console.log('试看已结束')
if (event.type === 'action') console.log('等待业务处理', event.action?.action, event.action?.buttonId)
},
fail: (error) => { console.log('短剧或界面配置失败', error.errCode) }
})
}
界面开关
showProgress、showPauseControls、showTitle、showMediaHint 和 showLongPressMenu 互相独立,适合宿主自绘短剧或短视频界面:
| 配置 |
关闭后隐藏 |
仍保留 |
showProgress: false |
进度条、时间和图集位置提示 |
播放状态、失败重试与清屏退出 |
showPauseControls: false |
暂停/结束态的直达播放按钮、时间、倍率、静音、横屏和中央播放按钮 |
进度条(由 showProgress 控制)、设置面板、失败重试与清屏退出 |
showTitle: false |
顶部标题文字 |
顶栏布局和其他操作入口 |
showMediaHint: false |
加载、封面缺失、缓冲和播放失败的提示文案 |
加载指示器、失败重试、解锁和状态事件 |
showLongPressMenu: false |
中央长按倍速菜单 |
边缘临时倍速区域、单击暂停、双击点赞和上下滑切集 |
播放中只要 showProgress 保持为 true,视频进度仍可拖动;宿主可以监听状态并使用 context.seek() 完成自定义进度条。互动入口可继续使用 actions: [{ action: 'like', visible: false }] 或 favorite 隐藏。
openVideoFeed({
feedId: 'host-owned-drama-ui',
items,
options: {
mode: 'drama',
ui: {
showProgress: false,
showPauseControls: false,
showTitle: false,
showMediaHint: false,
showLongPressMenu: false,
actions: [
{ action: 'like', visible: false },
{ action: 'favorite', visible: false }
]
}
}
})
有限次数的播放恢复
import { openVideoFeed, getVideoFeedCapabilities } from '@/uni_modules/lizhao-video-feed'
export function openResilientFeed() {
const capability = getVideoFeedCapabilities()
openVideoFeed({
feedId: 'resilient-feed',
items: [{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' } }],
options: { maxPlaybackRetries: capability.playbackRetry ? 3 : 0 }, // 0~3 次额外尝试;非无限重连。
onEvent: (event) => {
const retry = event.state.retry
if (retry != null) console.log('恢复阶段', retry.phase, retry.attempt, retry.maxAttempts, retry.retryAtMs)
if (event.type === 'error' && event.error?.diagnostic != null) {
const diagnostic = event.error.diagnostic
// unknown 保持未知,不依据消息文字猜测 HTTP 状态或网络错误。
console.log('失败分类', diagnostic.kind, diagnostic.retryable, diagnostic.retryScheduled)
}
},
fail: (error) => { console.log('打开失败', error.errCode) }
})
}
视频出错后手动恢复
| 用途 |
前置条件 |
调用与结果 |
| 当前视频失败后主动重试 |
当前会话已经 ready;保存真实 feedId/sessionId,恢复网络或资源可用性 |
将下列函数绑定到重试按钮;不会自动调用,也不改变自动重试配置 |
| Harmony 视频 |
使用同一 play 方法;HLS、请求头和正数 maxPlaybackRetries 仍不支持 |
重建失败播放器,恢复已确认进度、基础倍率和静音;试看、活动页、后台、焦点及播放组限制仍生效 |
| 成功回调 |
当前恢复请求已完成必要准备与定位,或播放请求已按平台确认 |
不代表真实首帧;继续通过 firstframe、state 或 timeupdate 观察画面和推进 |
uni-app:由按钮调用
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
// feedId/sessionId 来自当前会话的 ready 或打开成功;不要填入旧会话身份。
// 仅在用户点击重试时调用。切项、关闭或新请求可能取消本次恢复,应按真实结果处理。
export function retryCurrentVideo(feedId, sessionId) {
const context = createVideoFeedContext({ feedId, sessionId })
context.play({
success: (result) => {
// 命令已确认;原有静音、基础倍率与合法进度会保留,后台等门禁可继续阻止实际播放。
console.log('恢复请求已确认', result.state?.positionMs, result.state?.status)
},
fail: (error) => {
// 9093011 表示试看边界,不能通过重试解锁;9093013 表示请求被取消。
if (error.errCode === 9093011) console.log('请先完成作品解锁')
else if (error.errCode !== 9093013) console.log('本次恢复未完成', error.errCode)
},
complete: (result) => { console.log('本次重试已结算', result.ok) }
})
// 不在此 destroy:当前播放会话仍由原页面按生命周期关闭或销毁。
}
uni-app x:带公开类型的模块
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
import type { VideoFeedCommandResult, VideoFeedFail } from '@/uni_modules/lizhao-video-feed'
// 由自己的按钮传入 ready 中保存的当前身份;不在 error 监听中循环调用。
export function retryCurrentVideo(feedId: string, sessionId: string): void {
const context = createVideoFeedContext({ feedId: feedId, sessionId: sessionId })
context.play({
success: (result: VideoFeedCommandResult): void => {
// ACK 是命令结果;画面是否已显示仍通过真实播放事件观察。
console.log('恢复请求已确认', result.state?.positionMs, result.state?.status)
},
fail: (error: VideoFeedFail): void => {
if (error.errCode == 9093011) console.log('请先完成作品解锁')
else if (error.errCode != 9093013) console.log('本次恢复未完成', error.errCode)
},
complete: (result: VideoFeedCommandResult): void => { console.log('本次重试已结算', result.ok) }
})
// 不销毁仍在使用的会话;原页面继续负责显隐和最终释放。
}
进阶示例
| 示例 |
前置条件 |
调用方式 |
| 基础控制 |
保存当前会话身份并等待 ready |
将返回对象的方法分别绑定按钮 |
| 列表更新 |
最新事件版本及完整业务条目 |
调用独立函数,不顺序执行全部更新 |
| 图片选择与重试 |
当前图集的最新事件 |
用户点击外部切图或重试按钮时调用 |
| 分页 |
hasMore: true |
将处理函数作为 onEvent 或在相应分支调用 |
| 互动与解锁 |
应用服务已经确认业务结果 |
回写完整作品;以事件身份和版本防止过期 |
| 评论 |
commentsrequest 的原请求身份 |
将评论结果回给当前请求 |
| 面板与横屏 |
ready、当前项非空 |
分别绑定对应按钮 |
| 监听与结果 |
当前会话身份 |
注册、解绑并释放自己的会话 |
控制方法与公共回调
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
export function createControls(identity) {
const context = createVideoFeedContext({ feedId: identity.feedId, sessionId: identity.sessionId })
// 此对象返回独立操作;只调用用户当前选择的方法,不把全部操作连续执行。
return {
play() { context.play({ fail: (error) => { console.log('播放失败', error.errCode) } }) },
pause() { context.pause({
success: (result) => { console.log('暂停已确认', result.ok) },
fail: (error) => { console.log('暂停失败', error.errCode, error.errMsg) },
complete: (result) => { console.log('本命令结算', result.operation, result.commandId) }
// 所有命令的 success/fail 互斥一次,然后 complete 一次;不表示整个界面关闭。
}) },
seek() { context.seek({ positionMs: 3000, fail: (error) => { console.log('不能跳转', error.errCode) } }) },
rate() { context.setRate({ rate: 1.25, fail: (error) => { console.log('倍率不支持', error.errCode) } }) },
mute() { context.setMuted({ muted: true }) },
next() { context.switchTo({ itemId: 'video-2', positionMs: 0 }) }, // ID 须在当前列表内。
hide() { context.setActive({ active: false }) }, // 页面/Tab 隐藏;保留用户主动暂停意图。
show() { context.setActive({ active: true }) },
freezeGestures() { context.setGesturesEnabled({ enabled: false }) },
resumeGestures() { context.setGesturesEnabled({ enabled: true }) },
state() { context.getState({ success: (result) => { console.log('当前播放状态', result.state?.status) } }) }
}
}
列表替换、主动追加与作品更新
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
export function createListActions(event) {
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
return {
refresh() {
context.setItems({
items: [{ itemId: 'fresh-1', source: { url: 'https://example.com/fresh.mp4' } }],
initialItemId: 'fresh-1', initialPositionMs: 0, hasMore: false,
fail: (error) => { console.log('刷新失败,旧列表保留', error.errCode) }
})
},
append() {
context.appendItems({
listRevision: event.listRevision, // 使用调用时最新观察版本;这是主动追加,不结算 loadmore。
items: [{ itemId: 'extra-1', source: { url: 'https://example.com/extra.mp4' } }], hasMore: false,
fail: (error) => { console.log('追加失败,请检查版本或重复 ID', error.errCode) }
})
},
replaceSource() {
context.updateItem({
listRevision: event.listRevision,
item: { itemId: event.itemId, source: { url: 'https://example.com/authorized-new.mp4' } },
positionMs: 0, // 只适用于当前条目换源;应提供想保留的其他完整条目字段。
fail: (error) => { console.log('替换失败', error.errCode) }
})
}
}
}
指定图片与失败重试
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
export function selectImage(event, imageId) {
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
context.switchImage({ itemId: event.itemId, imageId, listRevision: event.listRevision,
fail: (error) => { console.log('切图失败,请获取最新状态', error.errCode) } })
}
export function retryCurrentImage(event) {
const gallery = event.state.gallery
if (gallery == null || gallery.imageStatus !== 'error') return
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
// 由用户触发;已在加载、隐藏或不再是当前图片时不能重试。
context.retryImage({ itemId: event.itemId, imageId: gallery.imageId, listRevision: event.listRevision,
fail: (error) => { console.log('重试未建立', error.errCode) } })
}
异步分页:成功、空页与业务失败
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
// 本地异步示例;接入时用自己的请求替换函数体,保留外层捕获的 requestId/listRevision。
function requestPage(lastItemId) {
return Promise.resolve({ items: lastItemId === 'more-1' ? [] : [
{ itemId: 'more-1', source: { url: 'https://example.com/more.mp4' } }
], hasMore: false })
}
export function handleLoadMore(event) {
if (event.type !== 'loadmore' || event.requestId == null) return
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
requestPage(event.lastItemId).then((page) => {
context.resolveLoadMore({
requestId: event.requestId, listRevision: event.listRevision, // 必须原样回传本次请求身份。
outcome: page.items.length > 0 ? 'success' : 'empty', items: page.items,
hasMore: page.hasMore, message: page.items.length > 0 ? '' : '已经到底了',
fail: (error) => { console.log('结果已过期或不合法', error.errCode) }
})
}).catch(() => {
context.resolveLoadMore({
requestId: event.requestId, listRevision: event.listRevision, outcome: 'error', items: [],
hasMore: event.state.hasMore, message: '加载失败,请重试' // error 保留旧边界;不传服务端原文。
})
})
}
业务确认后回写互动与解锁
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
// 将服务端确认后的完整 item 传入;原 itemId 必须保留,不能仅回写 liked 一个字段。
export function applyConfirmedItem(event, confirmedItem) {
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
context.updateItem({ listRevision: event.listRevision, item: confirmedItem,
fail: (error) => { console.log('业务结果未应用,请刷新当前数据', error.errCode) } })
}
// 演示“已获授权”的完整快照构造;仅在自己的服务确认授权后调用。
export function makeUnlockedItem(item, authorizedUrl) {
return { ...item, source: { url: authorizedUrl }, drama: {
...item.drama, locked: false, trialEndMs: 0 // 切换为已经获权的来源;客户端字段不代替服务端鉴权。
} }
}
export function makeLikedItem(item) {
const interaction = item.interaction || {}
return { ...item, interaction: {
...interaction, liked: true, likeCount: (interaction.likeCount || 0) + 1
// 这里仅构造演示结果;正式数量与状态应使用服务端响应,不在重复点击时盲目累加。
} }
}
评论请求与主动评论快照
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
export function handleComments(event) {
if (event.type !== 'commentsrequest' || event.requestId == null) return
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
const firstPage = event.requestKind === 'initial' || event.lastCommentId === ''
const items = firstPage ? [{
commentId: 'comment-1', author: { authorId: 'user-1', name: '读者', avatar: '', followed: false },
text: '本地示例评论', createdAtMs: 1760000000000, likeCount: 2, liked: false
// createdAtMs 为 Unix 毫秒;text 当作普通文本显示。
}] : []
context.setComments({
itemId: event.itemId, listRevision: event.listRevision, requestId: event.requestId,
outcome: items.length > 0 ? 'success' : 'empty', items, hasMore: false, message: '',
fail: (error) => { console.log('评论请求已过期', error.errCode) }
})
}
// 评论提交或点赞由自己的服务完成后,主动替换面板中的完整快照。
export function applyConfirmedComments(event, confirmedComments) {
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
context.setComments({ itemId: event.itemId, listRevision: event.listRevision,
outcome: confirmedComments.length > 0 ? 'success' : 'empty', items: confirmedComments, hasMore: false,
message: '' }) // 主动回写省略 requestId;响应 commentsrequest 时不能省略。
}
// 自己的评论请求失败时调用;previousHasMore 取最近一次确认的评论边界。
export function reportCommentsFailure(event, previousHasMore) {
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
context.setComments({ itemId: event.itemId, listRevision: event.listRevision, requestId: event.requestId,
outcome: 'error', items: [], hasMore: previousHasMore, message: '评论加载失败,请重试' })
}
评论发送中、成功与失败
创建会话时设置 ui.commentSubmitFeedback: true,等待期间避免重复点击。自己的服务确认后,使用本次 action 的身份结算;setComments 仍只负责列表内容。
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
// 在自己的评论服务返回后调用;event 保留本次 onEvent 收到的 action 事件。
export function finishCommentSubmission(event, succeeded) {
if (event.type !== 'action' || event.action?.action !== 'commentsubmit') return
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
context.resolveCommentSubmit({
actionId: event.action.actionId, itemId: event.itemId, listRevision: event.listRevision,
outcome: succeeded ? 'success' : 'error', message: succeeded ? '发送成功' : '发送失败,请重试',
fail: (error) => { console.log('回执过期或未被视图接受', error.errCode) }
})
// 服务成功后,另用 setComments 回写已确认的完整评论快照。
}
uni-app x 使用相同方法和公开类型:
import { createVideoFeedContext, VideoFeedEvent, VideoFeedCommentSubmitOptions } from '@/uni_modules/lizhao-video-feed'
export function finishCommentSubmissionX(event: VideoFeedEvent, succeeded: boolean): void {
const action = event.action
if (event.type != 'action' || action == null || action!.action != 'commentsubmit') return
const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
context.resolveCommentSubmit({ actionId: action!.actionId, itemId: event.itemId,
listRevision: event.listRevision, outcome: succeeded ? 'success' : 'error',
message: succeeded ? '发送成功' : '发送失败,请重试' } as VideoFeedCommentSubmitOptions)
}
| 情况 |
发送框行为 |
| 未配置反馈 |
默认 false,保留原有发送方式 |
| 业务成功 |
相同原文清空;等待期间编辑过的新草稿保留 |
| 业务失败或等待超时 |
原文保留,可再次发送;等待上限使用 requestTimeoutMs |
| 关闭面板、换项或更新列表 |
回执不会重新打开面板;换项或换版使旧回执过期,取消等待不等于取消后台服务 |
面板、清屏与横屏
import { createVideoFeedContext, getVideoFeedCapabilities } from '@/uni_modules/lizhao-video-feed'
export function createViewActions(identity) {
const context = createVideoFeedContext({ feedId: identity.feedId, sessionId: identity.sessionId })
return {
comments() { context.setPanel({ panel: 'comments' }) },
episodes() { context.setPanel({ panel: 'episodes' }) }, // 仅 drama 模式可用。
menu() { context.setPanel({ panel: 'menu' }) },
closePanel() { context.setPanel({ panel: 'none' }) }, // 恢复原播放意图,不清除主动暂停。
clear() { context.setClearScreen({ clearScreen: true }) },
restore() { context.setClearScreen({ clearScreen: false }) },
landscape() {
if (getVideoFeedCapabilities().landscapeFullscreen !== true) return
context.enterFullscreen({ fail: (error) => { console.log('横屏失败或当前忙', error.errCode) } })
},
portrait() { context.exitFullscreen({ fail: (error) => { console.log('恢复失败', error.errCode) } }) }
}
}
订阅、解绑与资源释放
import { createVideoFeedContext, closeVideoFeed } from '@/uni_modules/lizhao-video-feed'
export function subscribeFeed(identity) {
const context = createVideoFeedContext({ feedId: identity.feedId, sessionId: identity.sessionId })
console.log('句柄绑定的身份', context.feedId, context.sessionId) // 句柄只控制这一代会话。
context.on({
listenerId: 'page-progress', event: 'all', // 同一 context 内 listenerId 唯一。
callback: (event) => { if (event.type === 'timeupdate') console.log('进度毫秒', event.state.positionMs) },
success: (result) => { console.log('注册成功', result.ok) },
fail: (error) => { console.log('注册失败', error.errCode) },
complete: (result) => { console.log('本次注册结算', result.operation) }
})
return () => context.off({ listenerId: 'page-progress', // 解绑自己的 ID,不影响其他监听。
success: (result) => { console.log('解绑完成', result.ok) },
fail: (error) => { console.log('解绑失败', error.errCode) },
complete: (result) => { console.log('解绑结算', result.ok) } })
}
export function closeFullScreen(identity) {
closeVideoFeed({ feedId: identity.feedId, sessionId: identity.sessionId,
success: (result) => { console.log('资源已释放', result.ok) },
fail: (error) => { console.log('关闭失败', error.errCode) },
complete: (result) => { console.log('关闭结算', result.ok) } })
}
export function releaseInline(identity) {
createVideoFeedContext({ feedId: identity.feedId, sessionId: identity.sessionId }).destroy({})
// 内嵌也可卸载组件;同 feedId 重新挂载须等 close,不能使用旧 sessionId 控制新会话。
}
读取 VideoFeedCapabilities
| 输入来源 |
使用方式 |
| getVideoFeedCapabilities() 的同步结果 |
在对应回调中调用下列读取函数;只读,不回写对象 |
import { getVideoFeedCapabilities } from '@/uni_modules/lizhao-video-feed'
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedCapabilities} capability */
export function readVideoFeedCapabilities(capability) {
console.log('galleryPlayback', capability.galleryPlayback) // 当前构建已接入静态图集;缺省表示未声明支持。
console.log('galleryAutoplay', capability.galleryAutoplay) // 当前构建已接入图集轮播,仍受 active/前台/面板与组互斥限制。
console.log('galleryMusic', capability.galleryMusic) // true 表示当前构建已接入图集音乐,不检测已安装基座。
console.log('maxGalleryImages', capability.maxGalleryImages) // 当前图集允许的最大图片数;不支持时为 0。
console.log('listPlayback', capability.listPlayback) // 当前构建已接入视频列表及分页;false 时仅允许 0/1 条初始化数据。
console.log('dramaPlayback', capability.dramaPlayback) // 当前构建已接入短剧、试看和选集;false 时相关操作明确失败。
console.log('interactionUI', capability.interactionUI) // 当前构建已接入业务信息层、评论、菜单和清屏。
console.log('platform', capability.platform) // 当前平台;other 表示无法识别,不能
console.log('available', capability.available) // 当前平台已接入原生驱动时为 true,不代表已安装基座包含本插件的当前版本。
console.log('reason', capability.reason) // 不可用或受限原因的安全中文说明,可用且无限制时为空字符串。
console.log('fullscreen', capability.fullscreen) // 当前构建实际具有全屏原生承载。
console.log('landscapeFullscreen', capability.landscapeFullscreen) // Android/iOS 为 true;支持同会话横屏切换,仍受宿主支持方向与承载限制。
console.log('inlineView', capability.inlineView) // 当前平台提供嵌入实现,不检测当前页面类型;uni-app Android/iOS 限 nvue,Harmony 使用 Vue/embed,uni-app x 的 App 使用 native-view;微信使用原生微信组件;H5 使用标准 Web 组件。
console.log('networkSource', capability.networkSource) // 当前实现允许网络源,仍受宿主网络配置、鉴权和原生解码能力限制。
console.log('localSource', capability.localSource) // 当前实现允许已授权的本地源,不代表取得系统目录权限。
console.log('mp4', capability.mp4) // MP4 资源路由可用,不保证任意音视频编码。
console.log('hls', capability.hls) // HLS 资源路由可用,不保证任意加密、分片或编码。
console.log('mp4Headers', capability.mp4Headers) // MP4 链路可按合同传递自定义请求头;false 时带头请求明确失败。
console.log('hlsHeaders', capability.hlsHeaders) // HLS 主列表/子列表/分片链路均能按合同处理请求头时才为 true。
console.log('playbackRetry', capability.playbackRetry) // 当前平台已接入受限次数的播放失败自动重试;Android/iOS/微信为 true,失败分类仍按平台真实信息决定。
console.log('shrinkPanel', capability.shrinkPanel) // 面板缩小画面并继续播放策略可用。
console.log('minRate', capability.minRate) // 当前实现允许的最小倍率;不可用时为 0。
console.log('maxRate', capability.maxRate) // 当前实现允许的最大倍率;不可用时为 0。
console.log('supportedRates', capability.supportedRates) // 非空表示仅允许列出的离散倍率;空数组表示 minRate/maxRate 范围内连续倍率。
console.log('firstFrameEvent', capability.firstFrameEvent) // false 表示平台没有严格可显示首帧事件,不会用播放/元数据事件冒充 firstframe;App 构建省略;H5 按真实浏览器能力提供。
console.log('maxPlayerCount', capability.maxPlayerCount) // 实际播放器总上限,只能为 0、1 或 2;不可用时为 0。
}
readVideoFeedCapabilities(getVideoFeedCapabilities()) // 同步查询,不创建播放器。
读取 VideoFeedEvent
| 输入来源 |
使用方式 |
| onEvent 或监听 callback 的参数 |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedEvent} value */
export function readVideoFeedEvent(value) {
console.log('type', value.type) // 具体事件名称,无
console.log('feedId', value.feedId) // 会话 feedId。
console.log('sessionId', value.sessionId) // 不可复用的会话代次;同 feedId 重新打开产生不同值,组件登记前错误为空字符串。
console.log('itemId', value.itemId) // 事件关联条目;空列表或无关联条目时为空字符串。
console.log('index', value.index) // 关联下标,空列表为 -1,不得用下标替代 itemId。
console.log('generation', value.generation) // 事件所属播放代次,不得将旧 generation 事件应用于新项。
console.log('listRevision', value.listRevision) // 事件产生时列表版本,分页/评论结算须原样返回。
console.log('timestampMs', value.timestampMs) // Unix 时间戳毫秒,用于观察,不替代 generation 排序。
console.log('state', value.state) // 产生事件时的完整只读快照。
console.log('previousItemId', value.previousItemId) // change/episodechange 的旧 itemId;首次选择为空字符串,其余事件省略。
console.log('previousImageId', value.previousImageId) // imagechange 的旧 imageId,首次为空字符串;其他事件省略。
console.log('reason', value.reason) // 状态变化或关闭原因的固定非敏感标记,其余事件省略。
console.log('requestId', value.requestId) // loadmore/commentsrequest 时必填,非空且会话内唯一;其余事件省略。
console.log('requestKind', value.requestKind) // 请求时必填,initial 替换/首取,more 追加,retry 重试上次目标。
console.log('lastItemId', value.lastItemId) // 视频 loadmore 时填列表末条 itemId,空列表为 '';其余事件省略。
console.log('lastCommentId', value.lastCommentId) // commentsrequest 时填已显示的末条 commentId,首取为 '';其余事件省略。
console.log('action', value.action) // action 事件时必填;其余事件省略。
console.log('error', value.error) // error/imageerror/musicerror 时必填;字段遵守脱敏的 VideoFeedFail,其余事件省略。
}
读取 VideoFeedActionRequest
| 输入来源 |
使用方式 |
| action 事件的 event.action(先判空) |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedActionRequest} value */
export function readVideoFeedActionRequest(value) {
console.log('actionId', value.actionId) // 会话内唯一动作标识;宿主可用于去重,不是支付或接口成功凭据。
console.log('action', value.action) // comment 打开评论,commentsubmit 提交文字,其他名称对应显示入口。
console.log('buttonId', value.buttonId) // episodeaction 时必填,原样返回配置 buttonId;其他动作省略。
console.log('targetItemId', value.targetItemId) // 动作目标 itemId;搜索/频道等会话动作可为空字符串。
console.log('requestedSelected', value.requestedSelected) // 点赞/收藏/关注/评论点赞的期望值;其他动作省略,不代表已生效。
console.log('commentId', value.commentId) // commentlike 时必填,其他动作省略。
console.log('text', value.text) // commentsubmit 时必填且非空,其他动作省略;插件不自动加入评论列表。
console.log('seriesId', value.seriesId) // drama/unlock 时填写目标 seriesId,普通视频动作省略。
console.log('episodeId', value.episodeId) // unlock 时填写目标 episodeId,非分集动作省略。
}
读取 VideoFeedState
| 输入来源 |
使用方式 |
| event.state 或 getState 成功结果的 state(先判空) |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedState} value */
export function readVideoFeedState(value) {
console.log('mode', value.mode) // 实际模式,无
console.log('itemType', value.itemType) // 当前图集明确为 gallery;视频、空列表与释放后不填图集值。
console.log('gallery', value.gallery) // 当前图集真实展示状态,旧视频省略。
console.log('ready', value.ready) // 承载和控制器是否就绪;true 不代表媒体已经准备或出现首帧。
console.log('status', value.status) // 当前播放状态;空列表为 idle,资源释放完成为 released。
console.log('itemId', value.itemId) // 当前条目标识;空列表为空字符串。
console.log('index', value.index) // 当前下标从 0 开始;空列表为 -1。
console.log('itemCount', value.itemCount) // 非负整数条目数。
console.log('generation', value.generation) // 会话内单调递增的播放代次;初始为 0,切项/换源/刷新使其递增。
console.log('listRevision', value.listRevision) // 已登记会话从 1 开始递增,列表替换、追加、条目替换均递增;未登记错误快照为 0。
console.log('positionMs', value.positionMs) // 当前进度毫秒,未知或空列表为 0。
console.log('durationMs', value.durationMs) // 媒体时长毫秒,尚未知或空列表为 0。
console.log('bufferedPositionMs', value.bufferedPositionMs) // 当前连续缓冲的末位置毫秒,未知为 0。
console.log('rate', value.rate) // 宿主配置的基础倍率,不含长按临时倍率。
console.log('effectiveRate', value.effectiveRate) // 视频当前实际倍率;长按结束恢复为 rate,图集为 0。
console.log('muted', value.muted) // 当前静音设置。
console.log('active', value.active) // 宿主页面/Tab 活跃标记。
console.log('playRequested', value.playRequested) // 当前播放意图,初值等于 autoplay;play 设 true,pause 设 false,显隐/面板不修改。
console.log('manualPaused', value.manualPaused) // 用户或 pause 命令的暂停意图;仅显式 play/用户继续可清除,切页保持。
console.log('interrupted', value.interrupted) // 当前是否因原生音频中断或焦点丢失暂停。
console.log('backgrounded', value.backgrounded) // 当前是否处于后台;返回前台不清除 manualPaused。
console.log('panel', value.panel) // 当前面板;none 无面板,menu 为倍率/清屏菜单并暂时暂停,关闭不清除主动暂停。
console.log('clearScreen', value.clearScreen) // 是否清屏;清屏不改变播放与退出能力。
console.log('hasMore', value.hasMore) // 宿主最近确认的后续页标记。
console.log('loadMoreState', value.loadMoreState) // 当前视频列表分页状态;error 后由用户重试生成新请求。
console.log('loadMoreRequestId', value.loadMoreRequestId) // 正在等待的视频列表分页请求标识,无请求时为空字符串。
console.log('retry', value.retry) // 可选;默认关闭或原生尚未报告时省略,避免改变旧状态快照。
console.log('presentation', value.presentation) // Android/iOS 报告实际承载,landscape 为横屏全屏;布局切换不改变播放代次。
}
读取 VideoFeedGalleryState
| 输入来源 |
使用方式 |
| event.state.gallery(先判空) |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedGalleryState} value */
export function readVideoFeedGalleryState(value) {
console.log('imageId', value.imageId) // 当前目标图身份,选择后立即更新。
console.log('imageIndex', value.imageIndex) // 从 0 开始的目标下标与图集总张数。
console.log('imageCount', value.imageCount) // 当前图集的图片总数;有效图集为 1~20 张。
console.log('imageStatus', value.imageStatus) // ready 仅表示当前图已真实显示。
console.log('galleryRevision', value.galleryRevision) // 有序图片 ID/URL 列表代次,从 1 开始。
console.log('imageGeneration', value.imageGeneration) // 会话内单调递增的图片展示/重试代次。
console.log('autoplay', value.autoplay) // 图集当前配置,不覆盖已建立的轮播意图。
console.log('intervalMs', value.intervalMs) // 当前轮播间隔,单位毫秒;未请求轮播时也可读取配置。
console.log('loop', value.loop) // 末图后是否回首图的轮播配置,不代表正在运行。
console.log('slideshowRequested', value.slideshowRequested) // 当前图集的轮播意图与真实计时状态。
console.log('slideshowRunning', value.slideshowRunning) // 当前轮播计时是否实际运行;触摸、后台或面板阻止时为 false。
console.log('completed', value.completed) // 非循环末图完整停留后的完成锁存。
console.log('music', value.music) // 配置音乐并收到状态后才存在;可继续读取独立音轨状态。
}
读取 VideoFeedGalleryMusicState
| 输入来源 |
使用方式 |
| event.state.gallery?.music(先判空) |
读取音轨自己的状态与时间,不把它写入视频时间字段 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedGalleryMusicState} value */
export function readVideoFeedGalleryMusicState(value) {
console.log('status', value.status)
console.log('positionMs', value.positionMs)
console.log('durationMs', value.durationMs)
}
读取 VideoFeedRetryState
| 输入来源 |
使用方式 |
| event.state.retry(先判空) |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedRetryState} value */
export function readVideoFeedRetryState(value) {
console.log('phase', value.phase) // 等待、尝试、恢复、耗尽或取消之一。
console.log('attempt', value.attempt) // 本轮已经执行的插件额外尝试次数,非负整数。
console.log('maxAttempts', value.maxAttempts) // 本轮允许的插件额外尝试上限,范围 1 至 3。
console.log('retryAtMs', value.retryAtMs) // waiting 时为计划执行的 Unix 毫秒时间,其他阶段或未知时为 0。
}
读取 VideoFeedCommandResult
| 输入来源 |
使用方式 |
| success / complete 的参数 |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedCommandResult} value */
export function readVideoFeedCommandResult(value) {
console.log('ok', value.ok) // 命令落实为 true,失败、取消或超时为 false。
console.log('errSubject', value.errSubject) // 固定 lizhao-video-feed。
console.log('errCode', value.errCode) // 成功为 0,失败为 VideoFeedErrorCode 中的一个值。
console.log('errMsg', value.errMsg) // 固定可读中文结算说明,不含媒体地址和鉴权内容。
console.log('feedId', value.feedId) // 目标 feedId,创建前参数非法时可为空字符串。
console.log('sessionId', value.sessionId) // 目标会话代次,创建前失败时为空字符串。
console.log('commandId', value.commandId) // 会话内唯一命令标识,用于关联本次结算,不用于重放命令。
console.log('operation', value.operation) // 对应的公开方法名。
console.log('state', value.state) // 结算时的目标会话快照;会话不可用或创建失败时为 null。
}
读取 VideoFeedFail
| 输入来源 |
使用方式 |
| fail 的参数或 event.error(先判空) |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedFail} value */
export function readVideoFeedFail(value) {
console.log('errSubject', value.errSubject) // 固定为 lizhao-video-feed;用于定位错误所属插件。
console.log('errMsg', value.errMsg) // 可读的脱敏错误说明,不含媒体地址或鉴权内容。
console.log('errCode', value.errCode) // 上述固定错误码之一,无
console.log('operation', value.operation) // 发生错误的方法名或事件名,未知时为空字符串。
console.log('feedId', value.feedId) // 目标 feedId,尚未获得有效标识时为空字符串。
console.log('sessionId', value.sessionId) // 目标会话代次,创建前失败时为空字符串。
console.log('diagnostic', value.diagnostic) // 仅播放失败且原生提供结构化诊断时存在,普通参数/业务错误保持缺省。
}
读取 VideoFeedPlaybackDiagnostic
| 输入来源 |
使用方式 |
| error.diagnostic(先判空) |
在对应回调中调用下列读取函数;只读,不回写对象 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedPlaybackDiagnostic} value */
export function readVideoFeedPlaybackDiagnostic(value) {
console.log('kind', value.kind) // 固定脱敏分类,无法可靠识别时为 unknown。
console.log('sourceUrl', value.sourceUrl) // 仅协议、主机和路径,查询参数、片段和凭据已移除。
console.log('nativeErrorCode', value.nativeErrorCode) // 原生提供可信有限整数时返回,不解释为跨平台统一错误码。
console.log('httpStatus', value.httpStatus) // 仅原生可靠取得 100 至 599 的 HTTP 状态时返回。
console.log('retryable', value.retryable) // 该失败分类和状态是否允许插件自动重试。
console.log('retryScheduled', value.retryScheduled) // 本次失败是否已经安排自动重试。
console.log('attempt', value.attempt) // 本轮已经执行的插件额外尝试次数,非负整数。
console.log('maxAttempts', value.maxAttempts) // 本轮允许的插件额外尝试上限,范围 0 至 3。
}
读取 VideoFeedComponentEvent
| 输入来源 |
使用方式 |
| uni-app x 微信组件 @event 的参数 |
在对应回调中调用下列读取函数;App 先解析原生 detail,uni-app 直接读取正文 |
/** @param {import('@/uni_modules/lizhao-video-feed').VideoFeedComponentEvent} value */
export function readVideoFeedComponentEvent(value) {
console.log('detail', value.detail) // uni-app x 微信的事件正文;App 解析原生 detail 后使用相同字段,传统 uni-app 直接接收正文。
}
完整示例
| 宿主 |
代码范围 |
独立演示页 |
| uni-app |
Vue 2 / Vue 3 页面脚本:打开、控制、显隐与卸载 |
uni_modules/lizhao-video-feed/example/uniapp/index.vue |
| uni-app x |
UTS 页面:公开类型与相同生命周期 |
uni_modules/lizhao-video-feed/example/uniappx/index.uvue |
uni-app 页面脚本
import { openVideoFeed, createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
export default {
data() { return { feedId: 'page-feed', sessionId: '', feedReady: false, feedOpening: false, feedDisposed: false } },
methods: {
openFeed() {
if (this.feedDisposed || this.feedOpening || this.sessionId !== '') return
this.feedOpening = true // 阻止 created 异步到达前重复点击打开。
openVideoFeed({
feedId: this.feedId,
items: [{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' }, poster: 'https://example.com/one.jpg' }],
options: { mode: 'video', autoplay: true, active: true },
onEvent: (event) => {
if (event.type === 'created') {
this.sessionId = event.sessionId
if (this.feedDisposed) { this.releaseFeed(); return } // 页面已卸载则取消刚登记的会话。
}
if (event.sessionId !== this.sessionId) return // 隔离旧会话的迟到事件。
if (event.type === 'ready') this.feedReady = true
if (event.type === 'error') console.log('播放失败', event.error?.errCode)
if (event.type === 'close') { this.feedReady = false; this.sessionId = '' }
},
success: (result) => { console.log('打开已就绪', result.ok) },
fail: (error) => { console.log('打开失败', error.errCode) },
complete: (result) => { this.feedOpening = false; console.log('打开命令结算', result.operation) }
})
},
pauseFeed() {
if (!this.feedReady) return
createVideoFeedContext({ feedId: this.feedId, sessionId: this.sessionId }).pause({
fail: (error) => { console.log('暂停失败', error.errCode) }
})
},
setFeedActive(active) {
if (!this.feedReady) return
createVideoFeedContext({ feedId: this.feedId, sessionId: this.sessionId }).setActive({ active })
},
releaseFeed() {
if (this.sessionId === '') return
// destroy 可在 ready 前取消;页面离开时只清理自己保存的这一代身份。
createVideoFeedContext({ feedId: this.feedId, sessionId: this.sessionId }).destroy({})
}
},
onShow() { this.setFeedActive(true) },
onHide() { this.setFeedActive(false) },
onUnload() { this.feedDisposed = true; this.releaseFeed() }
}
uni-app x 页面
<template>
<view><button @click="openFeed">打开视频流</button><button @click="pauseFeed">暂停当前会话</button></view>
</template>
<script setup lang="uts">
import { onShow, onHide, onUnload } from '@dcloudio/uni-app'
import { openVideoFeed, createVideoFeedContext, VideoFeedContext } from '@/uni_modules/lizhao-video-feed'
let context: VideoFeedContext | null = null
let sessionId = ''
let ready = false
let opening = false
let disposed = false
function openFeed() {
if (disposed || opening || sessionId != '') return
opening = true // created 之前也阻止重复打开。
openVideoFeed({
feedId: 'page-feed-x',
items: [{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' }, poster: 'https://example.com/one.jpg' }],
options: { mode: 'video', autoplay: true, active: true },
onEvent: (event) => {
if (event.type == 'created') {
sessionId = event.sessionId
context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
if (disposed) { context?.destroy({}); return } // ready 前可安全取消。
}
if (event.sessionId != sessionId) return
if (event.type == 'ready') ready = true
if (event.type == 'error') console.log('播放失败', event.error?.errCode)
if (event.type == 'close') { ready = false; sessionId = ''; context = null }
},
success: (result) => { console.log('打开已就绪', result.ok) },
fail: (error) => { console.log('打开失败', error.errCode) },
complete: (result) => { opening = false; console.log('打开结算', result.operation) }
})
}
function pauseFeed() { if (ready) context?.pause({ fail: (error) => { console.log('暂停失败', error.errCode) } }) }
onShow(() => { if (ready) context?.setActive({ active: true }) })
onHide(() => { if (ready) context?.setActive({ active: false }) })
onUnload(() => { disposed = true; context?.destroy({}) }) // ready 前也可取消。
</script>
模块化示例
| 模块 |
组合方式 |
详细代码 |
| 数据模块 |
准备完整 VideoFeedItem;视频、图片、短剧按实际类型分开 |
作品、图集、短剧 |
| 业务事件模块 |
在一个 onEvent 中将 loadmore、commentsrequest、action 分发到独立处理函数 |
事件分发 |
| 控制模块 |
保存 created 的身份,ready 后创建按钮操作,卸载释放 |
控制、完整流程 |
| 内嵌模块 |
固定初始属性,运行时通过 context 更新 |
uni-app x、uni-app App |
import { openVideoFeed } from '@/uni_modules/lizhao-video-feed'
// 三个处理器由业务模块传入,可使用上文的分页、评论和动作处理示例。
export function openWithModules(items, handleLoadMore, handleComments, handleAction) {
openVideoFeed({
feedId: 'modular-feed', items, options: { hasMore: true },
onEvent: (event) => {
if (event.type === 'loadmore') handleLoadMore(event)
if (event.type === 'commentsrequest') handleComments(event)
if (event.type === 'action') handleAction(event)
},
fail: (error) => { console.log('模块化打开失败', error.errCode) }
})
}
uni-app x 内嵌组件
<template>
<view>
<!-- #ifdef APP -->
<lizhao-video-feed class="feed" feed-id="inline-x" :initial-items="items" :initial-options="options" @event="handleNativeEvent" />
<!-- #endif -->
<!-- #ifdef MP-WEIXIN -->
<lizhao-video-feed class="feed" feed-id="inline-x" :initial-items="items" :initial-options="options" @event="handleWeixinEvent" />
<!-- #endif -->
</view>
</template>
<script setup lang="uts">
import { onShow, onHide, onUnload } from '@dcloudio/uni-app'
import { createVideoFeedContext, VideoFeedItem, VideoFeedOptions, VideoFeedComponentEvent, VideoFeedContext, VideoFeedEvent } from '@/uni_modules/lizhao-video-feed'
const items: VideoFeedItem[] = [{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' } }]
const options: VideoFeedOptions = { mode: 'video', active: true }
let context: VideoFeedContext | null = null
let ready = false
function receiveEvent(detail: VideoFeedEvent) {
if (detail.type == 'created') context = createVideoFeedContext({ feedId: detail.feedId, sessionId: detail.sessionId })
if (detail.type == 'ready') ready = true
if (detail.type == 'error') console.log('组件错误', detail.error?.errCode)
if (detail.type == 'close') { ready = false; context = null }
}
// App 保留原生事件封套;先从 detail 建立公开强类型快照。
// #ifdef APP
function handleNativeEvent(event: UniNativeViewEvent) {
const detail = JSON.parse<VideoFeedEvent>(JSON.stringify(event.detail) ?? '{}')
if (detail != null) receiveEvent(detail)
}
// #endif
// 微信已经由组件包装为公开类型;不要再从事件本身读取 type。
// #ifdef MP-WEIXIN
function handleWeixinEvent(event: VideoFeedComponentEvent) { receiveEvent(event.detail) }
// #endif
onShow(() => { if (ready) context?.setActive({ active: true }) })
onHide(() => { if (ready) context?.setActive({ active: false }) })
onUnload(() => { context?.destroy({}) })
// feed-id / initial-items / initial-options 只在挂载时复制;后续改列表用 context.setItems。
</script>
<style>.feed { width: 100%; height: 560px; }</style>
uni-app Android / iOS 的 nvue 内嵌组件
<template>
<view><lizhao-video-feed class="feed" feed-id="inline-app" :initial-items="items" :initial-options="options" @event="handleEvent" /></view>
</template>
<script>
import { createVideoFeedContext } from '@/uni_modules/lizhao-video-feed'
export default {
data() { return { items: [{ itemId: 'video-1', source: { url: 'https://example.com/one.mp4' } }], options: { active: true } } },
created() { this.feedContext = null; this.feedReady = false }, // 普通句柄不作为业务响应式数据使用。
methods: {
handleEvent(input) {
const detail = input.detail || input // uni-app 包装直接发送正文;兼容有 detail 的事件。
if (detail.type === 'created') this.feedContext = createVideoFeedContext({ feedId: detail.feedId, sessionId: detail.sessionId })
if (detail.type === 'ready') this.feedReady = true
if (detail.type === 'error') console.log('组件错误', detail.error?.errCode)
if (detail.type === 'close') { this.feedReady = false; this.feedContext = null }
},
activeFeed(active) { if (this.feedReady) this.feedContext?.setActive({ active }) }
},
onShow() { this.activeFeed(true) }, onHide() { this.activeFeed(false) },
onUnload() { this.feedContext?.destroy({}) }
}
</script>
<style>.feed { width: 750rpx; height: 1000rpx; }</style>
API 用途速查
| 入口 / 方法 |
业务用途 |
对应示例 |
getVideoFeedCapabilities() |
查询当前构建的平台能力 |
能力字段读取 |
openVideoFeed(options) |
打开全屏会话 |
简单打开、完整流程 |
createVideoFeedContext(identity) |
绑定已登记会话身份 |
控制 |
closeVideoFeed(identity) |
关闭全屏会话;嵌入使用 destroy |
关闭 |
会话方法
| 方法 |
作用与边界 |
示例 |
feedId |
必填;绑定的非空 feedId;只读约定,修改此快照不能重定向句柄。 |
代码 |
sessionId |
必填;绑定的非空 sessionId;只读约定,同名新会话须创建新 context。 |
代码 |
play |
清除 manualPaused 并请求播放;视频出错后可显式恢复;图集可请求轮播和音乐,纯图片单图报 9093016;active/后台/中断/暂停面板阻止时保留请求;void,异步结算。 |
控制、手动恢复 |
pause |
设置 manualPaused=true 并暂停当前项;显隐恢复和切页均不清除它;void,异步结算。 |
代码 |
seek |
跳转当前视频毫秒位置;成功等原生确认,门禁/越界/超时失败;图集返回 9093016;void,异步结算。 |
代码 |
setRate |
设置基础倍率;超出端侧能力失败,不改变暂停意图;图集返回 9093016;void,异步结算。 |
代码 |
setMuted |
设置当前视频或图集音乐静音;纯图片图集返回 9093016,预载始终静音;不绕过焦点/播放组互斥;void,异步结算。 |
代码 |
switchTo |
按 itemId 切页并递增 generation;锁定项可展示门禁但不请求受限源;void,异步结算。 |
代码 |
switchImage |
选择当前图集中的图片;相同目标幂等,选择完成结算,图片显示结果由事件报告。 |
代码 |
retryImage |
重试当前 error 图片;真实建立新加载代次后结算,不更改主动暂停意图。 |
代码 |
setItems |
原子替换列表并作废旧加载、seek、分页和评论回调;保留 manualPaused;void,异步结算。 |
代码 |
appendItems |
按观察到的版本主动追加;重复 ID 或过期拒绝整批,空数组合法;void,异步结算。 |
代码 |
updateItem |
替换条目快照,宿主用它回写互动与解锁;同源纯业务更新不打断播放;void,异步结算。 |
代码 |
setActive |
设置页面/Tab 活跃状态;非活跃暂停并取消预载,恢复不清除用户暂停;void,异步结算。 |
代码 |
setGesturesEnabled |
运行时冻结或恢复切集、单击、双击和长按手势;不改变播放意图、倍率或当前条目;void,异步结算。 |
代码 |
resolveLoadMore |
结算视频分页 success/empty/error;requestId+listRevision 一致才生效;void,异步结算。 |
代码 |
setComments |
响应评论请求或主动替换;initial 替换,more 追加,retry 重用原操作;过期失败;void,异步结算。 |
代码 |
resolveCommentSubmit |
按原 actionId/itemId/listRevision 确认评论服务结果,视图接受后异步结算。 |
代码 |
setPanel |
打开/关闭原生面板;关闭恢复布局/倍率与原暂停意图,切项自动关闭;void,异步结算。 |
代码 |
setClearScreen |
设置清屏并跨页保持;退出、暂停/继续和倍率入口仍可用;void,异步结算。 |
代码 |
enterFullscreen |
Android/iOS 同会话进入横屏全屏;面板/编辑/手势忙时 9093018,占用时 9093017;原生实际确认后结算。 |
代码 |
exitFullscreen |
退出横屏并恢复原内嵌或原全屏承载;幂等,不销毁会话;其他平台 9093016。 |
代码 |
getState |
获取结算时快照到 result.state;不访问网络,不把未就绪伪装为播放成功;void,异步结算。 |
代码 |
destroy |
释放本会话原生资源、焦点与监听,关闭全屏或清空嵌入承载;允许 ready 前调用;void,异步结算。 |
代码 |
on |
立即登记监听并异步结算,无网络/权限;允许 ready 前注册;参数非法或旧会话通过 fail 返回,不重放历史事件。 |
代码 |
off |
立即按 ID 解绑并异步结算,无网络/权限;真实会话释放后也幂等,空 ID 或未登记句柄通过 fail 返回。 |
代码 |
参数与返回值导航
| 统一约定 |
说明 |
| 默认值与必填 |
以各参数表为准;省略与显式 null 不是同一配置 |
| 异步命令 |
返回 void,使用 success/fail/complete;除 on/off/destroy 外须等 ready |
| 句柄身份 |
固定 feedId/sessionId,不控制同名后继会话;off/destroy 对原会话清理幂等 |
| 版本与异步 |
使用请求原有 requestId/listRevision;迟到响应失败,不能解除新请求 |
| 完整快照 |
updateItem 替换整条;未提供的可选字段恢复默认值 |
| 错误别名 |
VideoFeedEventFailure 按 VideoFeedFail 使用;错误码见后文 |
| 失败分类 VideoFeedPlaybackDiagnosticKind |
观察含义 |
| network / timeout / http / tls |
原生可确认的网络、超时、HTTP 或 TLS 问题 |
| format / decoder / drm / permission |
格式、解码、授权方案或访问权限问题 |
| unknown |
原因不能确定;不能根据消息猜测 |
VideoFeedHeader
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
name |
string |
是 |
非空 HTTP 字段名,不含冒号或换行,名称不区分大小写。 |
无 |
无 |
value |
string |
是 |
字段值,不含换行;不应硬编码令牌。 |
无 |
无 |
VideoFeedSource
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
url |
string |
是 |
非空 HTTPS 地址或宿主已可访问的本地路径;其他协议按能力检查。 |
无 |
无 |
mediaType |
string |
否 |
Android/iOS 支持 HTTPS HLS 点播,无后缀 HLS 须显式指定 hls,不承诺所有编码。 |
auto 按路径识别 m3u8,其余按 MP4 |
'auto' / 'mp4' / 'hls' |
sourceId |
string |
否 |
宿主的非敏感源版本标识,不能代替真实 URL/请求头身份。 |
空字符串 |
无 |
headers |
VideoFeedHeader[] |
否 |
自定义请求头列表;当前构建不支持非空值,按能力检查失败,不会静默丢弃。 |
空数组 |
无 |
VideoFeedAuthor
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
authorId |
string |
是 |
非空作者业务标识,无 |
无 |
无 |
name |
string |
是 |
显示名称,允许空字符串隐藏名称。 |
无 |
无 |
avatar |
string |
否 |
HTTPS 或本地头像资源,失败显示占位。 |
空字符串 |
无 |
followed |
boolean |
否 |
点击关注只请求宿主处理,不自动修改此值。 |
false |
true / false |
VideoFeedInteraction
VideoFeedEpisode
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
seriesId |
string |
是 |
非空剧集标识,无 |
无 |
无 |
episodeId |
string |
是 |
非空分集标识,不使用数组下标代替。 |
无 |
无 |
episodeNumber |
number |
是 |
从 1 开始的整数集序;同系列不得重复。 |
无 |
无 |
seriesTitle |
string |
否 |
剧名。 |
空字符串 |
无 |
seriesTags |
string[] |
否 |
宿主提供的剧集标签,不从媒体内容自动推断。 |
空数组 |
无 |
seriesDescription |
string |
否 |
选集面板中的可折叠简介。 |
空字符串 |
无 |
episodeTitle |
string |
否 |
分集标题。 |
空字符串 |
无 |
totalEpisodes |
number |
否 |
已知时为不小于 episodeNumber 的整数。 |
0 表示未知 |
无 |
watched |
boolean |
否 |
宿主确认的已看标记,不代表服务端历史已保存。 |
false |
true / false |
locked |
boolean |
否 |
true 且无可用试看源时仅展示封面并请求解锁。 |
false |
true / false |
trialEndMs |
number |
否 |
正整数表示从源时间轴 0 开始的试看截止毫秒。 locked=true 时仅 source 存在且本值大于 0 才允许试看;截止或越界 seek 被拦截。 宿主解锁时回写 locked=false、trialEndMs=0 及已授权 source;门禁不能替代服务端鉴权。 |
0 |
无 |
VideoFeedImage
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
imageId |
string |
是 |
图集内唯一非空字符串,最多 128 个 UTF-16 码元。 |
无 |
无 |
url |
string |
是 |
HTTPS 或当前平台已支持且已授权的本地路径。 |
无 |
无 |
VideoFeedGallery
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
images |
VideoFeedImage[] |
是 |
1 至 20 张,不能有空洞、空值或重复 imageId。 |
无 |
无 |
autoplay |
boolean |
否 |
仅初始化新图集身份的轮播意图。 |
false |
true / false |
intervalMs |
number |
否 |
1000 至 10000 的有限整数毫秒。 |
3000 |
无 |
loop |
boolean |
否 |
只控制轮播末图回首图。 |
false |
true / false |
objectFit |
string |
否 |
不继承视频的 objectFit 默认值。 |
contain |
'contain' / 'cover' |
music |
VideoFeedGalleryMusic |
否 |
配置背景音乐;与图片轮播独立,原始 JS / JSON 不接受显式 null。 |
不播放音乐 |
无 |
VideoFeedGalleryMusic
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
url |
string |
是 |
非空 HTTPS MP3 / M4A 或平台已支持且已授权的本地音频路径;不支持请求头、HLS、直播或 DRM。 |
无 |
无 |
loop |
boolean |
否 |
控制音乐自身循环,不改变图片轮播。 |
true |
true / false |
volume |
number |
否 |
0~1 的有限数,保留 0;不修改系统音量,取消静音恢复此值。 |
1 |
无 |
VideoFeedItem
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
itemId |
string |
是 |
会话列表内唯一非空标识;刷新、分页和更新均以它定位。 |
无 |
无 |
itemType |
string |
否 |
省略按 video;gallery 仅适用于普通 video 模式。 |
video |
'video' / 'gallery' |
gallery |
VideoFeedGallery |
否 |
仅 itemType=gallery 时必填;视频条目不得携带。 |
无 |
无 |
source |
VideoFeedSource |
否 |
普通视频必填;locked=true 的短剧可省略;图集禁止提供。 |
无 |
无 |
poster |
string |
否 |
封面在真实 firstframe 后隐藏,空源锁定项保留封面。 |
空字符串 |
无 |
title |
string |
否 |
作品标题。 |
空字符串 |
无 |
durationHintMs |
number |
否 |
宿主提供的展示时长毫秒,非负整数,不参与 seek/试看边界校验。 |
0 表示未知 |
无 |
itemDescription |
string |
否 |
可折叠的作品简介。 |
空字符串 |
无 |
author |
VideoFeedAuthor |
否 |
内部字段遵守 VideoFeedAuthor。 |
不展示作者 |
无 |
interaction |
VideoFeedInteraction |
否 |
整体快照由宿主通过 updateItem 回写。 |
数量 0;状态 false |
无 |
drama |
VideoFeedEpisode |
否 |
video 模式可作为短剧入口;drama 模式必填,无 |
集序 |
无 |
VideoFeedTheme
VideoFeedActionStyle
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
action |
string |
是 |
要覆盖的入口,同一配置数组中不得重复。 |
无 |
'author' / 'follow' / 'like' / 'comment' / 'favorite' / 'share' |
visible |
boolean |
否 |
是否展示此入口。 |
true |
true / false |
label |
string |
否 |
作者/关注合并为头像徽标,非空文案保留独立文字入口。 |
内置文案或数量 |
无 |
icon |
string |
否 |
HTTPS 或本地图片,失败回退内置图标。 |
内置图标 |
无 |
activeIcon |
string |
否 |
资源规则同 icon。 |
内置选中图标 |
无 |
VideoFeedEpisodeAction
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
buttonId |
string |
是 |
配置内唯一非空按钮标识,事件原样返回,不作为支付或授权凭证。 |
无 |
无 |
label |
string |
是 |
非空显示文案。 |
无 |
无 |
disabled |
boolean |
否 |
禁用时不发送动作事件。 |
false |
true / false |
emphasized |
boolean |
否 |
是否使用主题强调色,不代表业务已经成功。 |
false |
true / false |
VideoFeedUIOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
title |
string |
否 |
顶部频道或页面标题。 |
空字符串 |
无 |
safeAreaMode |
string |
否 |
auto 自动加系统安全区,manual 仅采用下列留白。 |
auto |
'auto' / 'manual' |
topInset |
number |
否 |
非负逻辑像素,叠加在已处理的顶部安全区之外。 |
0 |
无 |
bottomInset |
number |
否 |
非负逻辑像素,给宿主底部导航预留,不硬编码 tabbar 高度。 |
0 |
无 |
theme |
VideoFeedTheme |
否 |
未提供字段使用 VideoFeedTheme 默认值。 |
内置深色主题 |
无 |
actions |
VideoFeedActionStyle[] |
否 |
数组仅覆盖指定入口,不删除未列出的入口。 |
内置全部入口 |
无 |
showBack |
boolean |
否 |
普通模式显示返回;清屏时始终保留退出入口。 |
true |
true / false |
showFullscreen |
boolean |
否 |
Android/iOS 显示同会话横屏入口,退出返回创建时的承载。 |
false |
true / false |
showSearch |
boolean |
否 |
搜索只发出 action,由宿主处理。 |
false |
true / false |
showInformation |
boolean |
否 |
显示作者与作品信息。 |
true |
true / false |
showProgress |
boolean |
否 |
视频显示可拖动进度;多图作品显示被动位置提示,不提供提示条拖动。关闭后隐藏进度条、时间和位置提示。 |
true |
true / false |
showPauseControls |
boolean |
否 |
显示暂停/结束态直达播放按钮、时间、倍率、静音、横屏和中央播放按钮;设置面板和进度条分别保留原入口并由各自配置控制。 |
true |
true / false |
showTitle |
boolean |
否 |
显示顶部标题文字;关闭后保留顶栏布局和其他操作入口。 |
true |
true / false |
showMediaHint |
boolean |
否 |
显示加载、封面缺失、缓冲和播放失败提示文案;关闭后仍保留指示器、重试和状态事件。 |
true |
true / false |
clearScreen |
boolean |
否 |
清屏跨条目保持,仍保留退出、暂停/继续、倍率和取消清屏。 |
false |
true / false |
enableGestures |
boolean |
否 |
单击暂停、双击点赞、中央长按菜单;面板与拖动优先消耗手势。 |
true |
true / false |
longPressRateRegion |
string |
否 |
仅开启指定侧边 20% 视频区域的临时长按倍速,其余区域长按菜单。 同一触摸只能命中菜单或临时倍速之一;控件、面板、进度拖动不触发这两种长按。 |
none |
'none' / 'left-edge' / 'right-edge' |
longPressRate |
number |
否 |
长按临时倍率,必须在能力范围内;释放、取消手势或切页后恢复原倍率。 |
2 |
无 |
commentSubmitFeedback |
boolean |
否 |
开启发送反馈,须调用 resolveCommentSubmit 结算服务结果。 |
false |
true / false |
showImagePreview |
boolean |
否 |
当前图集图片就绪后提供大图查看。 |
true |
true / false |
commentPlayback |
string |
否 |
评论面板始终从底部上推并把视频调整到顶部,pause 暂停,shrink 按原播放意图继续。 |
pause |
'pause' / 'shrink' |
episodePlayback |
string |
否 |
选集面板采用的播放策略。 |
pause |
'pause' / 'shrink' |
panelVideoScale |
number |
否 |
面板打开时的媒体收缩强度,允许 0.4 至 0.8;评论态映射为顶部播放区高度且不做二次缩放。 |
0.65 |
无 |
episodeLayout |
string |
否 |
选集列表含封面/标题/展示时长,grid 使用紧凑集号格。 |
list |
'list' / 'grid' |
episodeActions |
VideoFeedEpisodeAction[] |
否 |
最多 2 个底部业务按钮,点击只发送 episodeaction 动作。 |
空数组 |
无 |
VideoFeedOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
mode |
string |
否 |
drama 校验每条剧集元数据并启用选集。 |
video |
'video' / 'drama' |
initialItemId |
string |
否 |
提供时必须命中列表,空列表只允许省略。 |
首条 |
无 |
initialPositionMs |
number |
否 |
非负整数毫秒,须位于当前项可播放范围。 |
0 |
无 |
autoplay |
boolean |
否 |
首次就绪尝试播放,仍受活跃状态、锁定和音频焦点约束。 |
true |
true / false |
active |
boolean |
否 |
宿主页面/Tab 是否活跃,不覆盖用户主动暂停意图。 |
true |
true / false |
muted |
boolean |
否 |
是否静音;预载播放器始终静音且不可发声。 |
false |
true / false |
rate |
number |
否 |
基础播放倍率,必须在能力范围内。 |
1 |
无 |
objectFit |
string |
否 |
画面铺满裁剪或完整包含。 |
cover |
'cover' / 'contain' |
loop |
boolean |
否 |
video 只循环当前项,与 autoNext=true 互斥。 |
video: true;drama: false |
true / false |
autoNext |
boolean |
否 |
video 末项结束一次,不自动回到首项。 |
video: false;drama: true |
true / false |
maxPlayerCount |
number |
否 |
仅允许 1 或 2,包含当前播放器与预载播放器的总上限。 |
2 |
无 |
preloadCount |
number |
否 |
仅允许 0 或 1,不能超出总上限,优先预载下一条。 |
maxPlayerCount - 1 |
无 |
playbackGroup |
string |
否 |
同组会话至多一个可发声,每个会话也始终只有一个。 |
lizhao-video-feed |
无 |
resumeAfterInterruption |
boolean |
否 |
音频中断恢复后仍需 active=true 且无用户暂停、面板暂停或门禁。 |
true |
true / false |
maxPlaybackRetries |
number |
否 |
仅允许 0、1、2、3,表示原生播放器最终失败后最多执行的额外尝试次数。 |
0 |
0 / 1 / 2 / 3 |
hasMore |
boolean |
否 |
宿主确认还有下一页时设 true,空列表也可请求第一页。 |
false |
true / false |
loadMoreThreshold |
number |
否 |
距末项剩余不超过此非负整数时触发 loadmore,一次仅一个请求。 |
2 |
无 |
requestTimeoutMs |
number |
否 |
分页/评论请求结算等待毫秒,允许 1000 至 120000,超时可重试。 |
30000 |
无 |
commandTimeoutMs |
number |
否 |
单次异步控制命令等待毫秒,允许 1000 至 120000。 |
15000 |
无 |
ui |
VideoFeedUIOptions |
否 |
初始界面布局、主题、按钮及面板策略。 |
内置布局 |
无 |
VideoFeedComponentProps
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
feedId |
string |
是 |
应用内唯一非空实例标识,不能与全屏会话重号。 |
无 |
无 |
initialItems |
VideoFeedItem[] |
是 |
初始视频快照,允许空数组;不得通过后续修改此对象改变插件数据。 |
无 |
无 |
initialOptions |
VideoFeedOptions |
否 |
初始会话配置;挂载后使用 context 修改。 |
VideoFeedOptions 默认值 |
无 |
VideoFeedCommandOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
success |
(res: VideoFeedCommandResult) => void |
否 |
成功时异步触发一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
失败时异步触发一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
success/fail 之后一次,含 ok/errCode。 |
不监听 |
无 |
VideoFeedSeekOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
positionMs |
number |
是 |
非负整数毫秒;越过已知时长或试看截止明确失败,不静默截断。 |
无 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
原生确认跳转完成后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
参数、门禁、过期或原生跳转失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
本次跳转结算后一次。 |
不监听 |
无 |
VideoFeedRateOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
rate |
number |
是 |
有限正数,必须在 getVideoFeedCapabilities 返回的倍率范围内。 |
无 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
倍率设置落实后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
参数、能力或生命周期失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedMutedOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
muted |
boolean |
是 |
true 静音、false 请求恢复当前项声音。 |
无 |
true / false |
success |
(res: VideoFeedCommandResult) => void |
否 |
静音状态落实后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
生命周期或原生设置失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedSwitchOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
itemId |
string |
是 |
现有列表中的 itemId;锁定无试看条目只显示门禁并发送 unlock 请求。 |
无 |
无 |
positionMs |
number |
否 |
非负整数起播毫秒,不得越过门禁。 |
0 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
目标条目与布局切换落实后一次,不等待 firstframe。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
条目、参数或生命周期失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedSetItemsOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
items |
VideoFeedItem[] |
是 |
允许空数组,itemId 不得重复;调用后插件保存独立快照。 |
无 |
无 |
initialItemId |
string |
否 |
空列表须省略。 |
保留当前 ID,否则首条 |
无 |
initialPositionMs |
number |
否 |
非负整数毫秒。 |
同 ID 同源保留进度,否则 0 |
无 |
hasMore |
boolean |
否 |
明确重置分页边界及错误状态,旧分页/评论请求全部作废。 |
false |
true / false |
success |
(res: VideoFeedCommandResult) => void |
否 |
新列表生效且 generation/listRevision 递增后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
列表参数或生命周期失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedImageOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
itemId |
string |
是 |
目标作品,须为当前图集。 |
无 |
无 |
imageId |
string |
是 |
目标图片的稳定标识。 |
无 |
无 |
listRevision |
number |
是 |
调用时观察到的列表版本,过期返回 9093012。 |
无 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
真实选择完成或新重试加载建立后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
参数、身份、状态或能力失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
本命令结算后一次。 |
不监听 |
无 |
VideoFeedAppendItemsOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
listRevision |
number |
是 |
调用时观察到的列表版本,版本不匹配则拒绝整批追加。 |
无 |
无 |
items |
VideoFeedItem[] |
是 |
允许空数组;批次内或与现有列表重号均拒绝整批,不静默去重。 |
无 |
无 |
hasMore |
boolean |
否 |
false 表示无后续页。 |
保留现值 |
true / false |
success |
(res: VideoFeedCommandResult) => void |
否 |
生效后一次;非空追加或 hasMore 实际变化均递增 listRevision 并清理旧请求。 仅 items=[] 且 hasMore 未变化时无操作,避免旧分页响应恢复已关闭的分页边界。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
过期、重复 ID 或生命周期失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedUpdateItemOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
listRevision |
number |
是 |
调用时观察到的列表版本,防止旧业务响应覆盖刷新数据。 |
无 |
无 |
item |
VideoFeedItem |
是 |
itemId 必须已存在;不能借更新修改条目标识。 |
无 |
无 |
positionMs |
number |
否 |
只在当前项换源时适用,非当前项提供时报参数错误。 同源互动更新不重建播放器;当前项源 URL/headers/sourceId/mediaType 或门禁变化取消旧回调并递增 generation。 非当前项换源只作废该项预载,不改变当前播放代次;之后切入时使用更新后的源。 |
保留当前进度 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
完整替换、递增 listRevision 并依上述规则立即释放旧请求锁后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
条目、版本、参数或生命周期失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedActiveOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
active |
boolean |
是 |
false 暂停当前项并取消预载,true 仅在其他播放条件满足时恢复。 |
无 |
true / false |
success |
(res: VideoFeedCommandResult) => void |
否 |
活跃状态与必要暂停落实后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
生命周期或原生切换失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedLoadMoreOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
requestId |
string |
是 |
原样传回 loadmore 事件的非空 requestId。 |
无 |
无 |
listRevision |
number |
是 |
原样传回 loadmore 事件的 listRevision;过期结算不影响新请求的锁和状态。 |
无 |
无 |
outcome |
string |
是 |
success 追加非空数据,empty 本次空页,error 本次业务加载失败。 |
无 |
'success' / 'empty' / 'error' |
items |
VideoFeedItem[] |
否 |
success 必须非空,empty/error 必须为空。 |
空数组 |
无 |
hasMore |
boolean |
是 |
成功或空页后是否还有下一页;error 时保留旧 hasMore,本字段仍须传旧值。 empty+true 释放请求锁但不立即重发,等待用户重试,避免空页自动循环。 |
无 |
true / false |
message |
string |
否 |
只显示安全的简短业务文案,不传服务端响应正文。 |
使用固定中文提示 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
分页结算被接受后一次,包括 outcome=error,不代表业务加载成功。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
过期、重复结算或数据非法时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
本次结算命令完成后一次。 |
不监听 |
无 |
VideoFeedComment
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
commentId |
string |
是 |
当前条目的评论列表内唯一非空标识。 |
无 |
无 |
author |
VideoFeedAuthor |
是 |
评论作者,关注状态遵守宿主回写规则。 |
无 |
无 |
text |
string |
是 |
评论正文,可为空字符串,不作为富文本执行。 |
无 |
无 |
createdAtMs |
number |
否 |
非负 Unix 时间戳毫秒。 |
0 表示不展示时间 |
无 |
likeCount |
number |
否 |
非负整数点赞数。 |
0 |
无 |
liked |
boolean |
否 |
宿主确认的评论点赞状态。 |
false |
true / false |
VideoFeedCommentsOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
itemId |
string |
是 |
目标当前 itemId;异步响应原样传回评论请求值,切项后响应过期。 |
无 |
无 |
listRevision |
number |
是 |
异步响应原样传回评论请求版本,主动快照使用最近观察到的版本。 |
无 |
无 |
requestId |
string |
否 |
异步请求响应必须传原 ID,仅结算一次。 |
省略表示主动替换完整快照并作废旧评论请求 |
无 |
outcome |
string |
是 |
success 返回非空评论,empty 返回空页,error 显示可重试错误。 |
无 |
'success' / 'empty' / 'error' |
items |
VideoFeedComment[] |
否 |
success 时必须非空,empty/error 时必须为空。 |
空数组 |
无 |
hasMore |
boolean |
是 |
后续是否还有评论;error 时保留上次边界。 |
无 |
true / false |
message |
string |
否 |
不得包含令牌、媒体 URL 或响应正文。 |
固定中文提示 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
目标评论面板接受结果后一次,不代表评论提交成功。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
请求过期、评论 ID 重复或数据非法时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算命令完成后一次。 |
不监听 |
无 |
VideoFeedCommentSubmitOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
actionId |
string |
是 |
原 commentsubmit action 的 actionId,仅结算该次提交。 |
无 |
无 |
itemId |
string |
是 |
本次事件的 itemId。 |
无 |
无 |
listRevision |
number |
是 |
本次事件的列表版本,正整数;换版后旧回执过期。 |
无 |
无 |
outcome |
string |
是 |
自己的服务已确认的结果。 |
无 |
'success' / 'error' |
message |
string |
否 |
最多512字符的安全提示,不放令牌、媒体地址或服务响应正文。 |
固定中文提示 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
原提交仍有效且视图接受结果后一次;不代替服务验证。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
参数非法、未开启反馈、旧身份、超时或视图拒绝时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
命令结算后一次。 |
不监听 |
无 |
VideoFeedPanelOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
panel |
string |
是 |
none 关闭,episodes 仅用于 drama 模式,menu 为倍率/清屏菜单且采用暂时暂停策略。 |
无 |
'none' / 'comments' / 'episodes' / 'menu' |
success |
(res: VideoFeedCommandResult) => void |
否 |
布局与面板状态落实后一次,不等待宿主数据。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
模式、能力、空列表或生命周期失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedClearScreenOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
clearScreen |
boolean |
是 |
true 隐藏作品信息与业务互动,false 恢复;切页继续保持此值。 |
无 |
true / false |
success |
(res: VideoFeedCommandResult) => void |
否 |
清屏状态落实后一次。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
生命周期或原生 UI 失败时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
结算后一次。 |
不监听 |
无 |
VideoFeedOnOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
listenerId |
string |
是 |
当前 context 内唯一非空注册 ID,重复注册明确失败。 |
无 |
无 |
event |
string |
是 |
all 接收全部事件;其余只接收指定事件。 |
无 |
'all' / 'created' / 'ready' / 'change' / 'statechange' / 'firstframe' / 'timeupdate' / 'ended' / 'error' / 'loadmore' / 'action' / 'episodechange' / 'trialend' / 'panelchange' / 'presentationchange' / 'commentsrequest' / 'imagechange' / 'imageload' / 'imageerror' / 'musicerror' / 'close' |
callback |
(event: VideoFeedEvent) => void |
是 |
保持存活并持续异步调用,off 或销毁后释放;返回值不参与原生业务。 |
无 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
注册成功后异步一次,不随持续事件重复调用。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
注册 ID 非法、重复或会话失效时异步一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
本次注册结算后一次,持续事件不触发 complete。 |
不监听 |
无 |
VideoFeedOffOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
listenerId |
string |
是 |
on 时使用的注册 ID;不存在时无操作,不影响其他 ID。 |
无 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
解绑完成后异步一次,不存在的 ID 也成功。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
空 ID 或无效会话句柄时异步一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
本次解绑结算后一次。 |
不监听 |
无 |
OpenVideoFeedOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
feedId |
string |
是 |
应用内未占用的非空 feedId,不允许隐式覆盖已有全屏或嵌入实例。 |
无 |
无 |
items |
VideoFeedItem[] |
是 |
初始列表,允许空数组;所有条目先校验再创建原生 UI。 |
无 |
无 |
options |
VideoFeedOptions |
否 |
会话初始配置;运行中通过 context 对应方法修改可变状态。 |
VideoFeedOptions 默认值 |
无 |
onEvent |
(event: VideoFeedEvent) => void |
否 |
创建时注册,依序收到 created/ready;需要在 ready 前取消时必须监听 created;close 后释放。 |
不监听 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
承载 ready 后一次,result.sessionId 可创建 context;不等待 firstframe。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
参数、占用、原生承载或超时失败时一次,并清理部分资源。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
open 命令结算后一次;不是界面关闭回调。 |
不监听 |
无 |
CloseVideoFeedOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
feedId |
string |
是 |
目标全屏实例 feedId;嵌入实例使用 context.destroy。 |
无 |
无 |
sessionId |
string |
是 |
open 结果或事件中取得的非空会话代次。 |
无 |
无 |
success |
(res: VideoFeedCommandResult) => void |
否 |
资源释放与宿主窗口恢复后一次,同会话重复关闭幂等。 |
不监听 |
无 |
fail |
(err: VideoFeedFail) => void |
否 |
参数错误、非全屏或 sessionId 不匹配时一次。 |
不监听 |
无 |
complete |
(res: VideoFeedCommandResult) => void |
否 |
本次关闭结算后一次。 |
不监听 |
无 |
CreateVideoFeedContextOptions
| 参数 |
类型 |
必填 |
说明 |
默认值 |
可选参数 |
feedId |
string |
是 |
已登记的非空 feedId,不能使用组件标签名代替实例标识。 |
无 |
无 |
sessionId |
string |
是 |
同一会话的 sessionId,必须从创建结果或事件取得。 |
无 |
无 |
VideoFeedCapabilities
| 字段 |
类型 |
说明 |
galleryPlayback |
boolean |
当前构建已接入静态图集;缺省表示未声明支持。 |
galleryAutoplay |
boolean |
当前构建已接入图集轮播,仍受 active/前台/面板与组互斥限制。 |
galleryMusic |
boolean |
当前构建已接入图集音乐时为 true;缺省表示未声明支持,不检测已安装基座。 |
maxGalleryImages |
number |
当前图集允许的最大图片数;不支持时为 0。 |
listPlayback |
boolean |
当前构建已接入视频列表及分页;false 时仅允许 0/1 条初始化数据。 |
dramaPlayback |
boolean |
当前构建已接入短剧、试看和选集;false 时相关操作明确失败。 |
interactionUI |
boolean |
当前构建已接入业务信息层、评论、菜单和清屏。 |
platform |
'android' \| 'ios' \| 'harmony' \| 'web' \| 'mp' \| 'other' |
当前平台;other 表示无法识别,不能 |
available |
boolean |
当前平台已接入原生驱动时为 true,不代表已安装基座包含本插件的当前版本。 |
reason |
string |
不可用或受限原因的安全中文说明,可用且无限制时为空字符串。 |
fullscreen |
boolean |
当前构建实际具有全屏原生承载。 |
landscapeFullscreen |
boolean |
Android/iOS 为 true;支持同会话横屏切换,仍受宿主支持方向与承载限制。 |
inlineView |
boolean |
当前平台提供嵌入实现,不检测当前页面类型;uni-app Android/iOS 限 nvue,Harmony 使用 Vue/embed,uni-app x 的 App 使用 native-view;微信使用原生微信组件;H5 使用标准 Web 组件。 |
networkSource |
boolean |
当前实现允许网络源,仍受宿主网络配置、鉴权和原生解码能力限制。 |
localSource |
boolean |
当前实现允许已授权的本地源,不代表取得系统目录权限。 |
mp4 |
boolean |
MP4 资源路由可用,不保证任意音视频编码。 |
hls |
boolean |
HLS 资源路由可用,不保证任意加密、分片或编码。 |
mp4Headers |
boolean |
MP4 链路可按合同传递自定义请求头;false 时带头请求明确失败。 |
hlsHeaders |
boolean |
HLS 主列表/子列表/分片链路均能按合同处理请求头时才为 true。 |
playbackRetry |
boolean |
当前平台已接入受限次数的播放失败自动重试;Android/iOS/微信为 true,失败分类仍按平台真实信息决定。 |
shrinkPanel |
boolean |
面板缩小画面并继续播放策略可用。 |
minRate |
number |
当前实现允许的最小倍率;不可用时为 0。 |
maxRate |
number |
当前实现允许的最大倍率;不可用时为 0。 |
supportedRates |
number[] |
非空表示仅允许列出的离散倍率;空数组表示 minRate/maxRate 范围内连续倍率。 |
firstFrameEvent |
boolean |
false 表示平台没有严格可显示首帧事件,不会用播放/元数据事件冒充 firstframe;App 构建省略;H5 按真实浏览器能力提供。 |
maxPlayerCount |
number |
实际播放器总上限,只能为 0、1 或 2;不可用时为 0。 |
VideoFeedEvent
| 字段 |
类型 |
说明 |
type |
'created' \| 'ready' \| 'change' \| 'statechange' \| 'firstframe' \| 'timeupdate' \| 'ended' \| 'error' \| 'loadmore' \| 'action' \| 'episodechange' \| 'trialend' \| 'panelchange' \| 'presentationchange' \| 'commentsrequest' \| 'imagechange' \| 'imageload' \| 'imageerror' \| 'musicerror' \| 'close' |
具体事件名称,无 |
feedId |
string |
会话 feedId。 |
sessionId |
string |
不可复用的会话代次;同 feedId 重新打开产生不同值,组件登记前错误为空字符串。 |
itemId |
string |
事件关联条目;空列表或无关联条目时为空字符串。 |
index |
number |
关联下标,空列表为 -1,不得用下标替代 itemId。 |
generation |
number |
事件所属播放代次,不得将旧 generation 事件应用于新项。 |
listRevision |
number |
事件产生时列表版本,分页/评论结算须原样返回。 |
timestampMs |
number |
Unix 时间戳毫秒,用于观察,不替代 generation 排序。 |
state |
VideoFeedState |
产生事件时的完整只读快照。 |
previousItemId |
string |
change/episodechange 的旧 itemId;首次选择为空字符串,其余事件省略。 |
previousImageId |
string |
imagechange 的旧 imageId,首次为空字符串;其他事件省略。 |
reason |
'initial' \| 'gesture' \| 'command' \| 'autonext' \| 'loop' \| 'items' \| 'source' \| 'active' \| 'panel' \| 'background' \| 'interruption' \| 'trial' \| 'native' \| 'back' \| 'destroy' |
状态变化或关闭原因的固定非敏感标记,其余事件省略。 |
requestId |
string |
loadmore/commentsrequest 时必填,非空且会话内唯一;其余事件省略。 |
requestKind |
'initial' \| 'more' \| 'retry' |
请求时必填,initial 替换/首取,more 追加,retry 重试上次目标。 |
lastItemId |
string |
视频 loadmore 时填列表末条 itemId,空列表为 '';其余事件省略。 |
lastCommentId |
string |
commentsrequest 时填已显示的末条 commentId,首取为 '';其余事件省略。 |
action |
VideoFeedActionRequest |
action 事件时必填;其余事件省略。 |
error |
VideoFeedFail |
error/imageerror/musicerror 时必填;字段遵守脱敏的 VideoFeedFail,其余事件省略。 |
VideoFeedActionRequest
| 字段 |
类型 |
说明 |
actionId |
string |
会话内唯一动作标识;宿主可用于去重,不是支付或接口成功凭据。 |
action |
'author' \| 'follow' \| 'like' \| 'comment' \| 'commentsubmit' \| 'commentlike' \| 'favorite' \| 'share' \| 'search' \| 'channel' \| 'drama' \| 'unlock' \| 'episodeaction' |
comment 打开评论,commentsubmit 提交文字,其他名称对应显示入口。 |
buttonId |
string |
episodeaction 时必填,原样返回配置 buttonId;其他动作省略。 |
targetItemId |
string |
动作目标 itemId;搜索/频道等会话动作可为空字符串。 |
requestedSelected |
boolean |
点赞/收藏/关注/评论点赞的期望值;其他动作省略,不代表已生效。 |
commentId |
string |
commentlike 时必填,其他动作省略。 |
text |
string |
commentsubmit 时必填且非空,其他动作省略;插件不自动加入评论列表。 |
seriesId |
string |
drama/unlock 时填写目标 seriesId,普通视频动作省略。 |
episodeId |
string |
unlock 时填写目标 episodeId,非分集动作省略。 |
VideoFeedState
| 字段 |
类型 |
说明 |
mode |
'video' \| 'drama' |
实际模式,无 |
itemType |
'video' \| 'gallery' |
当前图集明确为 gallery;视频、空列表与释放后不填图集值。 |
gallery |
VideoFeedGalleryState |
当前图集真实展示状态,旧视频省略。 |
ready |
boolean |
承载和控制器是否就绪;true 不代表媒体已经准备或出现首帧。 |
status |
'idle' \| 'loading' \| 'ready' \| 'playing' \| 'paused' \| 'buffering' \| 'ended' \| 'error' \| 'released' |
当前播放状态;空列表为 idle,资源释放完成为 released。 |
itemId |
string |
当前条目标识;空列表为空字符串。 |
index |
number |
当前下标从 0 开始;空列表为 -1。 |
itemCount |
number |
非负整数条目数。 |
generation |
number |
会话内单调递增的播放代次;初始为 0,切项/换源/刷新使其递增。 |
listRevision |
number |
已登记会话从 1 开始递增,列表替换、追加、条目替换均递增;未登记错误快照为 0。 |
positionMs |
number |
当前进度毫秒,未知或空列表为 0。 |
durationMs |
number |
媒体时长毫秒,尚未知或空列表为 0。 |
bufferedPositionMs |
number |
当前连续缓冲的末位置毫秒,未知为 0。 |
rate |
number |
宿主配置的基础倍率,不含长按临时倍率。 |
effectiveRate |
number |
视频当前实际倍率;长按结束恢复为 rate,图集为 0。 |
muted |
boolean |
当前静音设置。 |
active |
boolean |
宿主页面/Tab 活跃标记。 |
playRequested |
boolean |
当前播放意图,初值等于 autoplay;play 设 true,pause 设 false,显隐/面板不修改。 |
manualPaused |
boolean |
用户或 pause 命令的暂停意图;仅显式 play/用户继续可清除,切页保持。 |
interrupted |
boolean |
当前是否因原生音频中断或焦点丢失暂停。 |
backgrounded |
boolean |
当前是否处于后台;返回前台不清除 manualPaused。 |
panel |
'none' \| 'comments' \| 'episodes' \| 'menu' |
当前面板;none 无面板,menu 为倍率/清屏菜单并暂时暂停,关闭不清除主动暂停。 |
clearScreen |
boolean |
是否清屏;清屏不改变播放与退出能力。 |
hasMore |
boolean |
宿主最近确认的后续页标记。 |
loadMoreState |
'idle' \| 'loading' \| 'error' \| 'end' |
当前视频列表分页状态;error 后由用户重试生成新请求。 |
loadMoreRequestId |
string |
正在等待的视频列表分页请求标识,无请求时为空字符串。 |
retry |
VideoFeedRetryState |
可选;默认关闭或原生尚未报告时省略,避免改变旧状态快照。 |
presentation |
'inline' \| 'fullscreen' \| 'landscape' |
Android/iOS 报告实际承载,landscape 为横屏全屏;布局切换不改变播放代次。 |
VideoFeedGalleryState
VideoFeedGalleryMusicState
| 字段 |
类型 |
说明 |
status |
'idle' \| 'loading' \| 'ready' \| 'playing' \| 'paused' \| 'ended' \| 'error' |
当前音轨真实状态,独立于图片显示状态。 |
positionMs |
number |
最近确认的播放进度毫秒,尚未确认时为 0。 |
durationMs |
number |
最近确认的音轨时长毫秒,未知时为 0。 |
VideoFeedRetryState
| 字段 |
类型 |
说明 |
phase |
'waiting' \| 'attempting' \| 'recovered' \| 'exhausted' \| 'cancelled' |
等待、尝试、恢复、耗尽或取消之一。 |
attempt |
number |
本轮已经执行的插件额外尝试次数,非负整数。 |
maxAttempts |
number |
本轮允许的插件额外尝试上限,范围 1 至 3。 |
retryAtMs |
number |
waiting 时为计划执行的 Unix 毫秒时间,其他阶段或未知时为 0。 |
VideoFeedCommandResult
| 字段 |
类型 |
说明 |
ok |
boolean |
命令落实为 true,失败、取消或超时为 false。 |
errSubject |
string |
固定 lizhao-video-feed。 |
errCode |
number |
成功为 0,失败为 VideoFeedErrorCode 中的一个值。 |
errMsg |
string |
固定可读中文结算说明,不含媒体地址和鉴权内容。 |
feedId |
string |
目标 feedId,创建前参数非法时可为空字符串。 |
sessionId |
string |
目标会话代次,创建前失败时为空字符串。 |
commandId |
string |
会话内唯一命令标识,用于关联本次结算,不用于重放命令。 |
operation |
string |
对应的公开方法名。 |
state |
VideoFeedState \| null |
结算时的目标会话快照;会话不可用或创建失败时为 null。 |
VideoFeedFail
| 字段 |
类型 |
说明 |
errSubject |
string |
固定为 lizhao-video-feed;用于定位错误所属插件。 |
errMsg |
string |
可读的脱敏错误说明,不含媒体地址或鉴权内容。 |
errCode |
VideoFeedErrorCode |
上述固定错误码之一,无 |
operation |
string |
发生错误的方法名或事件名,未知时为空字符串。 |
feedId |
string |
目标 feedId,尚未获得有效标识时为空字符串。 |
sessionId |
string |
目标会话代次,创建前失败时为空字符串。 |
diagnostic |
VideoFeedPlaybackDiagnostic |
仅播放失败且原生提供结构化诊断时存在,普通参数/业务错误保持缺省。 |
VideoFeedPlaybackDiagnostic
VideoFeedComponentEvent
| 字段 |
类型 |
说明 |
detail |
VideoFeedEvent |
uni-app x 微信的事件正文;App 解析原生 detail 后使用相同字段,传统 uni-app 直接接收正文。 |
错误码说明
| 错误码 |
含义 |
说明 |
| 9093001 |
平台不支持 |
使用 App 平台,先查能力 |
| 9093002 |
参数非法 |
检查类型、唯一 ID、枚举、范围及组件初始属性 |
| 9093003 |
标识或全屏占用 |
等原实例 close,或使用不同内嵌 feedId |
| 9093004 |
会话过期 |
使用本次 created / success 提供的身份 |
| 9093005 |
当前操作尚不可用 |
等承载就绪,图片重试需等待当前失败且页面可见 |
| 9093006 |
媒体、请求头或播放恢复能力不支持 |
使用支持的 MP4 / HLS 路由,或关闭当前平台未开放的配置 |
| 9093007 |
原生承载不可用 |
检查匹配基座和宿主页面 |
| 9093008 |
视频或图集音乐播放失败 |
检查资源可达性与系统解码支持;图集音乐通过 musicerror 报告 |
| 9093009 |
跳转失败 |
根据真实时长重试或更换媒体 |
| 9093010 |
条目不存在 |
使用当前列表中的 itemId |
| 9093011 |
试看或锁定拦截 |
通过宿主业务授权后完整回写 |
| 9093012 |
请求 / 列表版本过期 |
丢弃旧响应,按最新事件重新请求 |
| 9093013 |
取消 |
页面关闭或切代次后停止旧流程 |
| 9093014 |
超时 |
检查原生环境或业务请求;命令超时后开始关闭,等待 close 确认释放完成后再重新打开 |
| 9093015 |
分页业务失败 |
显示可重试状态 |
| 9093016 |
当前能力未开放 |
按当前能力和平台范围接入 |
| 9093017 |
其他会话占用全屏 |
先退出或关闭已占用的会话 |
| 9093018 |
面板、编辑或手势操作未结束 |
结束操作后重试切换 |
| 9093019 |
图片加载或显示失败 |
检查地址、授权、格式和尺寸后重试当前图片 |
示例与平台接入
| 演示模块 |
uni-app |
uni-app x |
| App 功能菜单 |
uni_modules/lizhao-video-feed/example/uniapp/index.vue |
uni_modules/lizhao-video-feed/example/uniappx/index.uvue |
| 短视频、图集、短剧、互动、分页 |
uni_modules/lizhao-video-feed/example/uniapp/feed.vue |
uni_modules/lizhao-video-feed/example/uniappx/feed.uvue |
| App 内嵌 |
Android/iOS:uni_modules/lizhao-video-feed/example/uniapp/inline.nvue;Harmony:uni_modules/lizhao-video-feed/example/uniapp/inlineHarmony.vue |
uni_modules/lizhao-video-feed/example/uniappx/inline.uvue |
| 微信功能菜单 |
uni_modules/lizhao-video-feed/example/uniapp/weixin.vue |
uni_modules/lizhao-video-feed/example/uniappx/weixin.uvue |
| 微信内嵌与控制 |
uni_modules/lizhao-video-feed/example/uniapp/weixin-inline.vue |
uni_modules/lizhao-video-feed/example/uniappx/weixin-inline.uvue |
| 接入步骤 |
操作 |
结果 |
| 1 |
在插件市场选择使用 HBuilderX 导入,保留完整插件目录与名称 |
从 @/uni_modules/lizhao-video-feed 导入公开 API |
| 2 |
将下列对应宿主的页面配置合并到已有 pages.json |
示例能被导航到;保留自己的其他页面 |
| 3 |
App 使用包含当前原生代码与依赖的安装包或自定义基座;微信重新编译代码 |
避免旧原生包缺少能力 |
| 4 |
进入示例菜单,填写自己的视频地址后选择功能 |
评论、分页、互动和解锁采用本地演示回写 |
App 页面注册
| 配置 |
填写位置 |
适用范围 |
| 下方 JSONC |
合并到项目 pages.json,路径不写扩展名 |
uni-app 的 Android/iOS 内嵌为 nvue,Harmony 为 Vue/embed;uni-app x 为 uvue |
{
"pages": [
// uni-app:功能菜单和全屏 API 演示。
{ "path": "uni_modules/lizhao-video-feed/example/uniapp/index", "style": { "navigationBarTitleText": "原生播放" } },
{ "path": "uni_modules/lizhao-video-feed/example/uniapp/feed", "style": { "navigationBarTitleText": "视频流与短剧" } },
// #ifdef APP-PLUS
{ "path": "uni_modules/lizhao-video-feed/example/uniapp/inline", "style": { "navigationBarTitleText": "页面内播放" } },
// #endif
// #ifdef APP-HARMONY
{ "path": "uni_modules/lizhao-video-feed/example/uniapp/inlineHarmony", "style": { "navigationBarTitleText": "页面内播放" } }
// #endif
]
}
{
"pages": [
// uni-app x:标准组件按平台选择原生承载,不额外配置 easycom。
{ "path": "uni_modules/lizhao-video-feed/example/uniappx/index", "style": { "navigationBarTitleText": "原生播放" } },
{ "path": "uni_modules/lizhao-video-feed/example/uniappx/feed", "style": { "navigationBarTitleText": "视频流与短剧" } },
{ "path": "uni_modules/lizhao-video-feed/example/uniappx/inline", "style": { "navigationBarTitleText": "页面内播放" } }
]
}
微信页面与原生组件注册
| 配置 |
说明 |
| 插件全屏页面 |
全屏 API 必须登记 pages/weixin-player/weixin-player;全屏与内嵌共用同一组件注册 |
| 原生组件 |
将 usingComponents 合并到已有 globalStyle;不要覆盖原配置 |
| 图片、音频、视频与 HLS |
按实际媒体接口配置合法域名;图集网络图片需配置 request 合法域名,音乐来源需满足微信音频要求;使用 downloadFile 时也配置下载域名 |
{
"pages": [
// uni-app Vue 2 / Vue 3。
{ "path": "uni_modules/lizhao-video-feed/example/uniapp/weixin", "style": { "navigationBarTitleText": "短视频与短剧" } },
{ "path": "uni_modules/lizhao-video-feed/example/uniapp/weixin-inline", "style": { "navigationBarTitleText": "嵌入视频流" } },
{ "path": "uni_modules/lizhao-video-feed/pages/weixin-player/weixin-player", "style": { "navigationStyle": "custom", "disableScroll": true, "backgroundColor": "#000000" } }
],
"globalStyle": {
"usingComponents": {
"lizhao-video-feed-native": "/uni_modules/lizhao-video-feed/wxcomponents/lizhao-video-feed-native/index"
}
}
}
{
"pages": [
// uni-app x:只改变演示页面路径,全屏页面和原生组件路径相同。
{ "path": "uni_modules/lizhao-video-feed/example/uniappx/weixin", "style": { "navigationBarTitleText": "短视频与短剧" } },
{ "path": "uni_modules/lizhao-video-feed/example/uniappx/weixin-inline", "style": { "navigationBarTitleText": "嵌入视频流" } },
{ "path": "uni_modules/lizhao-video-feed/pages/weixin-player/weixin-player", "style": { "navigationStyle": "custom", "disableScroll": true, "backgroundColor": "#000000" } }
],
"globalStyle": {
"usingComponents": {
"lizhao-video-feed-native": "/uni_modules/lizhao-video-feed/wxcomponents/lizhao-video-feed-native/index"
}
}
}
注意事项
平台与承载对比
| 宿主 |
Android |
iOS |
Harmony(预览) |
微信小程序 |
H5 |
| uni-app 普通 Vue 页面 |
全屏 API |
全屏 API |
全屏 API;内嵌为 Vue/embed |
全屏 API、原生微信组件 |
全屏 API、标准组件 |
| uni-app nvue 页面 |
全屏 API、原生组件 |
全屏 API、原生组件 |
使用 Vue/embed 方案 |
使用 Vue 示例 |
使用 Vue 示例 |
| uni-app x uvue 页面 |
全屏 API、native-view 组件 |
全屏 API、native-view 组件 |
全屏 API、native-view 组件 |
全屏 API、原生微信组件 |
全屏 API、标准组件 |
| 能力 / 条件 |
Android / iOS |
微信 |
Harmony / 其他 |
| 目标最低环境 |
HBuilderX 5.24;Android 6.0 / iOS 13;所用编码须由目标设备支持 |
图集要求基础库 2.20.2+ |
Harmony API 12 预览;H5 见下表;其他小程序不提供播放器 |
| 静态图集 |
支持 1~20 张 JPEG / PNG |
支持 1~20 张 JPEG / PNG |
Harmony 支持 1~20 张 JPEG / PNG;其他平台不提供 |
| 图集背景音乐 |
支持 HTTPS MP3 / M4A 或已授权的本地音频,实际编码须由设备支持 |
支持 HTTPS 或宿主可访问的本地音频,需满足微信音频与域名要求 |
Harmony 支持 HTTPS 或已授权的本地音频;其他平台不提供 |
| 图片限制 |
每张 ≤12 MiB,单边 ≤16384,总像素 ≤5000 万 |
每张 ≤12 MiB,单边 ≤4096,总像素 ≤400 万 |
Harmony 每张 ≤12 MiB,单边 ≤16384,总像素 ≤5000 万;不推断动图、SVG 或未验格式可用 |
| 微信网络图片大小 |
不适用 |
收到 >12 MiB 后拒绝,不写盘、解析或显示;网络栈可能已传输或缓冲更多字节;本地文件按实际读取限制 |
不适用 |
| MP4 来源 |
HTTPS、已有访问权的 file:// 或本地绝对路径 |
HTTPS、宿主已有 wxfile://、http://tmp/、http://usr/ 文件标识 |
Harmony 使用其支持来源;其他平台返回 9093001 |
| 图集地址跳转 |
最多跟随 5 次 HTTPS 跳转;拒绝超限、无效目标及降级;共用原加载总期限,最终须返回 2xx 图片 |
由微信网络层处理,仍需满足合法域名要求 |
Harmony 最多 5 次 HTTPS 跳转,共用 15 秒加载期限,最终须返回 HTTP 200 图片 |
| HLS 点播 |
非加密 HTTPS;主列表、子列表和分片均须可访问 |
非加密 HTTPS;配置全部合法域名 |
Harmony 不开放 HLS |
| 不支持的媒体配置 |
HTTP 明文、本地 HLS、自定义媒体请求头返回 9093006 |
同左;微信本地文件标识中的 http://tmp/、http://usr/ 不属于网络明文播放 |
不提供直播、DRM、离线缓存或无限重连 |
| 播放失败恢复 |
0~3 次;可确认的网络故障及 HTTP 408 / 500 / 502 / 503 / 504 等按真实分类恢复 |
仅官方网络信息明确断网时尝试;联网失败不猜测原因 |
Harmony 正数 maxPlaybackRetries 返回 9093006 |
| 手动恢复视频 |
当前 error 时主动调用 play;已确认进度与原配置按实际状态恢复 |
使用现有 play,受官方播放器状态约束 |
Harmony 支持原生重试按钮或 play;不增加自动重试 |
| 恢复间隔 |
第 1 / 2 / 3 次等待 1 / 2 / 4 秒 |
同左;仍受生命周期和播放条件约束 |
先查询 playbackRetry |
| 倍率 |
以 supportedRates 或 minRate/maxRate 为准 |
仅 0.5 / 0.8 / 1 / 1.25 / 1.5 / 2 |
Harmony 仅 0.5 / 0.75 / 1 / 1.25 / 1.5 / 1.75 / 2 |
| 首帧观察 |
firstframe 表示真实可显示首帧;每代最多一次 |
firstFrameEvent=false,不发送 firstframe;按真实播放状态和推进的 timeupdate 观察 |
ready 与命令成功不能代替首帧 |
| 同会话横屏 |
宿主须允许方向变化;面板、编辑、手势忙时先结束操作;图集不能横屏 |
不提供此切换能力 |
Harmony / Web 不提供 |
| 组件事件 |
uni-app 直接发送 VideoFeedEvent 正文;uni-app x App 为原生事件封套,先解析 detail |
uni-app x 微信为 VideoFeedComponentEvent;uni-app 微信直接发送正文 |
JavaScript 可用 input.detail |
input 兼容读取 |
| 内嵌属性 |
挂载时复制一次;后续修改初始属性报 9093002 并保留原会话,列表通过 context 更新 |
同一公开组件合同 |
不支持的承载报 9093001,不自动退回页面 video |
| 能力查询 |
仅声明当前代码的能力,不检测已安装基座或当前页面承载 |
不保证任意编码都可播放 |
以 available、各能力字段和真实运行结果共同判断 |
H5 接入与浏览器边界
H5 使用相同的公开 API 和标准组件。openVideoFeed 打开覆盖页面的播放器;设备横屏能力以 landscapeFullscreen 为准。内嵌示例选用下表对应页面并在 pages.json 注册。
| 项目 |
使用方法 |
| 内嵌完整示例 |
uni-app:example/uniapp/inline-web.vue;uni-app x:example/uniappx/inline-web.uvue,保留标准组件实际宽高 |
| 视频与音乐 |
HTTPS、同源相对静态路径或同源 blob;HTTP 页面可使用 HTTP,HTTPS 页面拒绝混合内容;不接受 App 私有路径或本地 file 协议 |
| HLS |
仅当浏览器原生支持且 capability.hls 为 true 时接入;清单和分片同样须可访问,不引入额外解码器 |
| 图片 |
静态 JPEG / PNG,每张 ≤12 MiB、单边 ≤4096、总像素 ≤400 万;跨域服务须允许 CORS,不跟随图片跳转 |
| 自动播放 |
有声视频和图集配乐可能被浏览器策略阻止;失败后引导用户点击播放 |
| 首帧 |
firstFrameEvent 按浏览器能力返回;没有严格视频帧回调时继续观察状态和真实进度 |
| 能力差异 |
不提供设备横屏切换、自定义媒体请求头、DRM、离线缓存或自动播放失败重连;出错后可显式 play 重试 |
| 宽屏与页面显隐 |
支持窄屏和宽屏尺寸;Tab、路由或容器隐藏时调用 setActive(false),销毁组件或会话时释放媒体 |
事件与业务边界
| 状态 / 操作 |
开发者需要处理的事 |
| created |
会话已经登记,保存 feedId/sessionId;此时可监听或销毁,控制需等 ready |
| ready / success |
每会话一次;承载可控,空列表也会 ready;不代表视频首帧或图集已显示 |
| timeupdate / statechange |
timeupdate 只表示位置、时长和缓冲推进,播放状态变化看 statechange;暂停确认前最多补发一条终态 timeupdate |
| 初始化失败 |
API 登记前仅 fail/complete;登记后失败释放并 close;组件登记前只发 error,不产生 created/ready/close,修正属性后重新挂载 |
| 组件登记前错误快照 |
sessionId/itemId 为空,index=-1,generation/listRevision=0,ready=false、status=error、mode=video,数量/时间为 0、倍率为 1;不建立可控制会话 |
| imagechange / imageload / imageerror |
分别表示选图、真实显示完成、加载或显示失败;图集不伪造视频 firstframe/timeupdate/ended |
| musicerror |
音轨播放失败,错误码 9093008;不会改变图片状态,音乐状态通过 statechange 观察 |
| ended / trialend |
ended 为自然播放结束;trialend 每代最多一次,锁定无源项不伪造视频结束或首帧 |
| close |
资源及待结算命令处理完成后一次;释放持续监听,同名重开会产生新 sessionId |
| ready 前取消 |
打开先 fail(9093013)/complete,随后释放、结算关闭命令、发送 close |
| 列表版本变化 |
setItems/appendItems/updateItem 作废旧分页和评论请求;迟到响应报 9093012,不解除新请求;仍打开的同项评论可产生新请求 |
| 分页结果 |
success 必须非空,empty/error 必须空;empty+hasMore=true 等用户重试,不立即无限请求 |
| 图集配置变化 |
autoplay 只初始化新图集身份;运行中用 play/pause 控制轮播意图;图片列表、命令与迟到回调按真实身份隔离 |
| 图集媒体边界 |
不支持图片或音乐自定义请求头;图片缩放在大图查看层使用;当前作品为图集时,会话顶层 positionMs/durationMs/bufferedPositionMs 与 effectiveRate 为 0,音轨时间单独读取;纯图片单图 play 返回 9093016,有音乐的单图可请求播放音轨;图集起始进度须为 0 |
| 横屏切入图集 |
先退出视频横屏再切换到图集,否则返回 9093016 |
| 微信试看 |
截止依赖真实 timeupdate,不承诺逐帧精度,不代替内容授权;隐藏、暂停、取消、换源或卸载使相应旧回调失效 |
| 互斥与恢复 |
同组被抢占的视频可通过 play 或 setActive(true) 重新争取;图集轮播须显式 play,音乐遵守会话播放条件;主动 pause 不因前后台或关闭面板被清除 |
| 关注、点赞、评论、购买和解锁 |
action 是业务请求,非服务成功;自己的服务确认后回写完整快照,源授权、签名和订单在服务端处理 |
| 异常隔离 |
success/fail/complete 的异常不应阻止其他回调或清理;业务代码也应处理自己的请求失败 |
| 演示数据 |
示例中的本地 Mock 不代替内容、评论、支付或授权服务;插件不调用抖音接口,不提供抖音素材 |
使用中常见问题
| 现象 |
处理办法 |
| 打开成功但没画面 |
继续观察首帧/真实播放或 imageload/error;提供可访问 poster,尤其邻项封面和锁定项 |
| 切页、隐藏后仍有声音 |
正确发送页面/Tab 的 setActive(false);预载应静音,同组互斥;保留异常时的完整日志 |
| 点赞数字没有自动增加 |
服务成功后用 updateItem 回写完整互动快照 |
| 评论、按钮或选集上操作误翻页 |
面板、输入、按钮与进度各有手势区域;在目标设备复查嵌入尺寸与触摸,避免外层再覆盖整页手势 |
| Android 报 AbstractMethodError |
使用包含当前原生代码的安装包或自定义基座;不手动覆盖其他版本 AAR、不新增无依据的依赖排除项;仍失败时保留崩溃堆栈 |
| 只更新页面资源后能力缺失 |
Kotlin / Swift / ETS / UTS、依赖、Manifest 或原生配置变化须使用对应新原生包;文档与普通页面资源变化无需因此重打 |
| 网络慢或空页失败 |
播放按有限恢复能力处理,分页按原 requestId/listRevision 结算;未知错误不猜测为网络或解码失败 |
| 路径或权限失败 |
使用宿主已有授权来源;本插件不自动申请相册或文件目录权限;微信配置真实合法域名,不以关闭检查替代接入 |
| 需要保存收费内容权限 |
将访问控制、过期签名和订单权限放在自己的服务;locked 仅是播放门禁与界面配置 |
| 准备上线 |
在自己的目标机型核对全屏、内嵌、键盘、安全区、实际音频、手势、前后台和媒体编码 |
作者系列 UTS 插件
以下为作者已发布的 UTS 插件,可按能力方向查找。
| 插件 |
能力方向 |
插件市场 |
lizhao-alipay-kit |
支付宝授权登录、App 支付与脱敏诊断 |
查看插件 |
lizhao-app-keepalive |
应用保活、唤醒、自愈与报告 |
查看插件 |
lizhao-apple-iap |
苹果内购、交易恢复、订阅管理与服务端验签参考 |
查看插件 |
lizhao-apple-login |
苹果授权登录、凭证状态与撤销监听 |
查看插件 |
lizhao-bg-audio |
背景音频播放、队列、倍速与事件 |
查看插件 |
lizhao-ble |
BLE 扫描、连接、读写、通知与自动重连 |
查看插件 |
lizhao-call-kit |
电话、短信、通讯录原生能力 |
查看插件 |
lizhao-camera-pro |
原生相机、拍照录像、水印与媒体保存 |
查看插件 |
lizhao-cast-screen |
DLNA 投屏、AirPlay 路由入口 |
查看插件 |
lizhao-choose-file |
原生文件选择、上传、进度与取消 |
查看插件 |
lizhao-device-id |
设备标识、隐私策略与诊断 |
查看插件 |
lizhao-dingtalk |
钉钉授权登录、内容分享与回执诊断 |
查看插件 |
lizhao-doc-corrector |
文档扫描、矫正、增强与识别 |
查看插件 |
lizhao-douyin-kit |
抖音授权登录、内容分享与回执诊断 |
查看插件 |
lizhao-emu-detect |
模拟器环境检测、风险评分与证据 |
查看插件 |
lizhao-float-window |
悬浮窗、画中画、权限与诊断 |
查看插件 |
lizhao-gallery-pro |
相册媒体分页、筛选、缩略图与导出 |
查看插件 |
lizhao-google-login |
Google 授权登录、会话管理与脱敏诊断 |
查看插件 |
lizhao-hce-card |
NFC 虚拟卡、APDU 交互与 NDEF 标签模拟 |
查看插件 |
lizhao-health |
健康数据授权、查询、统计与写入 |
查看插件 |
lizhao-http-server |
本地 HTTP 服务、文件传输与实时通信 |
查看插件 |
lizhao-icon-pro |
SVG 图标组件、多主题与缓存 |
查看插件 |
lizhao-id-photo |
证件照制作、尺寸换算、换底色与模板换装 |
查看插件 |
lizhao-img-eraser |
图片去水印、局部修复与原生编辑器 |
查看插件 |
lizhao-live-activity |
实时活动、系统胶囊与普通通知降级 |
查看插件 |
lizhao-live-photo |
实况照片选取、展示预览与原件处理 |
查看插件 |
lizhao-map |
高德地图、定位、地点搜索、路线规划与导航 |
查看插件 |
lizhao-meta |
Facebook 登录分享、应用事件与深链 |
查看插件 |
lizhao-nfc-pro |
NFC 标签读写、NDEF、IsoDep 与诊断 |
查看插件 |
lizhao-notify-pro |
本地通知、点击动作、进度与定时提醒 |
查看插件 |
lizhao-novel-reader |
原生小说阅读、仿真翻页与段落评论 |
查看插件 |
lizhao-office-view |
Office 与 PDF 文件预览、进度与缓存管理 |
查看插件 |
lizhao-pdf-pro |
PDF 阅读、签批、真实写回与页面处理 |
查看插件 |
lizhao-play-billing |
Google Play 商品购买、订阅、恢复与确认消耗 |
查看插件 |
lizhao-qq-share |
QQ 授权码登录、QQ 与 QQ 空间分享 |
查看插件 |
lizhao-qrcode |
二维码生成、Logo 与样式配置、批量生成及导出 |
查看插件 |
lizhao-scan-pro |
原生扫码、连续扫码、相册识别 |
查看插件 |
lizhao-serial-port |
路径串口、USB 串口、多会话收发与诊断 |
查看插件 |
lizhao-share-plus |
系统分享、远程文件下载后分享 |
查看插件 |
lizhao-smart-tts |
系统 TTS、云端合成、听书方案 |
查看插件 |
lizhao-sqlite-pro |
原生 SQLite、迁移、备份与诊断 |
查看插件 |
lizhao-sse-pro |
SSE、Line、JSONL 与 Raw 流式请求 |
查看插件 |
lizhao-tcp-pro |
TCP 客户端、服务端、多连接与诊断 |
查看插件 |
lizhao-usb-storage |
U 盘、移动硬盘文件浏览、读写与批量复制 |
查看插件 |
lizhao-video-editor |
视频裁剪、压缩、取帧与 FFmpeg/FFprobe |
查看插件 |
lizhao-video-feed |
短视频上下滑、短剧选集与分页加载 |
查看插件 |
lizhao-video-player |
原生视频播放器、清晰度与播放交互 |
查看插件 |
lizhao-video-thumb |
视频封面、批量取帧与 Base64 返回 |
查看插件 |
lizhao-vpn-pro |
企业 VPN、IKEv2、安全接入与脱敏诊断 |
查看插件 |
lizhao-wechat-kit |
微信登录、分享、支付、小程序与客服 |
查看插件 |
lizhao-wecom |
企业微信授权登录、内容分享与脱敏诊断 |
查看插件 |
lizhao-xhs-share |
小红书图文视频分享与回执诊断 |
查看插件 |