更新记录

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。

功能特色

功能 实现效果 使用示例
短视频流 上下滑动切换作品、循环或连续播放 简单打开、播放配置
图文混排 图片左右翻页、大图缩放、多图提示、自动轮播与可选背景音乐 图集配置、图集配乐、切图与重试
短剧 选集、续看、试看、锁定和业务解锁 短剧配置、解锁回写
播放控制 播放、暂停、进度、静音、倍率与横屏;可分别隐藏暂停态控制、进度条和提示文案 控制方法、界面开关、横屏
互动与评论 作者、关注、点赞、收藏、评论发送反馈和业务回写 作品数据、互动、评论
列表与分页 刷新、主动追加、异步分页和失败重试 列表更新、分页
HLS 与播放恢复 非加密 HTTPS HLS 点播、有限自动恢复与出错后主动重试 媒体源、恢复配置、手动恢复
内嵌与界面配置 页面内播放、主题、按钮、手势、清屏和面板策略 界面配置、内嵌组件

适合哪些场景

场景 推荐能力 接入方式与边界
推荐流、社区作品 短视频与图片混排、互动、分页 全屏 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

从基础到进阶

层级 目标 阅读入口
简单示例 最少参数打开视频流 基础功能配置示例
高级示例 作品、图集、播放、界面和短剧配置 高级示例
进阶示例 列表、异步业务、控制、监听和状态读取 进阶示例
完整示例 从打开到页面显隐、关闭与释放 uni-app、uni-app x
模块化示例 将独立能力组合到自己的页面 模块组合
示例约定 用法
资源 将 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 返回。 代码

参数与返回值导航

类别 对象 代码用途
输入 VideoFeedHeader 配置或调用
输入 VideoFeedSource 配置或调用
输入 VideoFeedAuthor 配置或调用
输入 VideoFeedInteraction 配置或调用
输入 VideoFeedEpisode 配置或调用
输入 VideoFeedImage 配置或调用
输入 VideoFeedGallery 配置或调用
输入 VideoFeedGalleryMusic 图集配乐
输入 VideoFeedItem 配置或调用
输入 VideoFeedTheme 配置或调用
输入 VideoFeedActionStyle 配置或调用
输入 VideoFeedEpisodeAction 配置或调用
输入 VideoFeedUIOptions 配置或调用
输入 VideoFeedOptions 配置或调用
输入 VideoFeedComponentProps 配置或调用
输入 VideoFeedCommandOptions 配置或调用
输入 VideoFeedSeekOptions 配置或调用
输入 VideoFeedRateOptions 配置或调用
输入 VideoFeedMutedOptions 配置或调用
输入 VideoFeedSwitchOptions 配置或调用
输入 VideoFeedSetItemsOptions 配置或调用
输入 VideoFeedImageOptions 配置或调用
输入 VideoFeedAppendItemsOptions 配置或调用
输入 VideoFeedUpdateItemOptions 配置或调用
输入 VideoFeedActiveOptions 配置或调用
输入 VideoFeedLoadMoreOptions 配置或调用
输入 VideoFeedComment 配置或调用
输入 VideoFeedCommentsOptions 配置或调用
输入 VideoFeedPanelOptions 配置或调用
输入 VideoFeedClearScreenOptions 配置或调用
输入 VideoFeedOnOptions 配置或调用
输入 VideoFeedOffOptions 配置或调用
输入 OpenVideoFeedOptions 配置或调用
输入 CloseVideoFeedOptions 配置或调用
输入 CreateVideoFeedContextOptions 配置或调用
输出 VideoFeedCapabilities 读取与处理
输出 VideoFeedEvent 读取与处理
输出 VideoFeedActionRequest 读取与处理
输出 VideoFeedState 读取与处理
输出 VideoFeedGalleryState 读取与处理
输出 VideoFeedGalleryMusicState 读取与处理
输出 VideoFeedRetryState 读取与处理
输出 VideoFeedCommandResult 读取与处理
输出 VideoFeedFail 读取与处理
输出 VideoFeedPlaybackDiagnostic 读取与处理
输出 VideoFeedComponentEvent 读取与处理
统一约定 说明
默认值与必填 以各参数表为准;省略与显式 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

参数 类型 必填 说明 默认值 可选参数
likeCount number 否 宿主确认的点赞数。 0 无
commentCount number 否 宿主确认的评论数。 0 无
favoriteCount number 否 宿主确认的收藏数。 0 无
shareCount number 否 宿主确认的分享数。 0 无
liked boolean 否 当前用户是否已点赞。 false true / false
favorited boolean 否 当前用户是否已收藏。 false true / false

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

参数 类型 必填 说明 默认值 可选参数
backgroundColor string 否 背景颜色,使用 #RRGGBB 或 #RRGGBBAA。 #000000 无
textColor string 否 主文字与普通图标颜色。 #FFFFFF 无
secondaryTextColor string 否 说明文字颜色。 #D6D6D6 无
accentColor string 否 选中和强调颜色。 #FF375F 无
iconSize number 否 侧栏主动作显式覆盖允许 20 至 48,其他工具图标保持原默认。 主动作 36;作者 50;关注 24 无
fontSize number 否 信息文字尺寸,允许 10 至 24。 14 无

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

字段 类型 说明
imageId string 当前目标图身份,选择后立即更新。
imageIndex number 从 0 开始的目标下标与图集总张数。
imageCount number 当前图集的图片总数;有效图集为 1~20 张。
imageStatus 'loading' \| 'ready' \| 'error' ready 仅表示当前图已真实显示。
galleryRevision number 有序图片 ID/URL 列表代次,从 1 开始。
imageGeneration number 会话内单调递增的图片展示/重试代次。
autoplay boolean 图集当前配置,不覆盖已建立的轮播意图。
intervalMs number 当前轮播间隔,单位毫秒;未请求轮播时也可读取配置。
loop boolean 末图后是否回首图的轮播配置,不代表正在运行。
slideshowRequested boolean 当前图集的轮播意图与真实计时状态。
slideshowRunning boolean 当前轮播计时是否实际运行;触摸、后台或面板阻止时为 false。
completed boolean 非循环末图完整停留后的完成锁存。
music VideoFeedGalleryMusicState 可选;仅配置音乐且原生已报告时提供;纯图片、视频和释放后省略。

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

字段 类型 说明
kind VideoFeedPlaybackDiagnosticKind 固定脱敏分类,无法可靠识别时为 unknown。
sourceUrl string 当前失败媒体的脱敏来源,只保留协议、主机和路径,不含凭据、查询参数或片段。
nativeErrorCode number 原生提供可信有限整数时返回,不解释为跨平台统一错误码。
httpStatus number 仅原生可靠取得 100 至 599 的 HTTP 状态时返回。
retryable boolean 该失败分类和状态是否允许插件自动重试。
retryScheduled boolean 本次失败是否已经安排自动重试。
attempt number 本轮已经执行的插件额外尝试次数,非负整数。
maxAttempts number 本轮允许的插件额外尝试上限,范围 0 至 3。

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 小红书图文视频分享与回执诊断 查看插件

隐私、权限声明

1. 本插件需要申请的系统权限列表:

播放网络视频、音频和加载网络图片需要网络访问;本地媒体须由接入项目提供可访问的路径。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

视频、图片、音频地址与业务数据由接入项目提供,不向插件作者服务器上传。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无