更新记录

1.1.0（2026-10-03）

• 新增 iOS 13.0 及以上原生短视频流与短剧播放，支持 uni-app 全屏 / nvue 组件和 uni-app x 全屏 / native-view 组件。
• 新增 iOS 播放失败后的重试入口，可通过播放按钮或 context.play({}) 重新加载当前内容。
• 修复 iOS 主动暂停或不可见会话恢复时提前抢占同组播放的问题。
• 修复 iOS 评论键盘弹出时输入与发送区域可能被遮挡，以及快速关闭评论面板时动画进度不一致的问题。

1.0.0（2026-10-03）

• 新增 Android 原生短视频流，支持 HTTPS MP4 和已有访问权限的本地 MP4，全屏打开与上下滑动切换。
• 新增相邻视频封面预取与跟手翻页，支持首帧出现前滑动、从互动区发起滑动，以及拖动取消后的回弹。
• 新增暂停、继续、进度跳转、倍速、静音、循环播放和首帧事件，提供统一的会话控制与错误反馈。
• 新增作者信息、关注、点赞、收藏、分享和搜索交互，业务处理完成后可回写展示状态。
• 新增评论面板，支持加载、分页、重试和发送评论请求，打开时视频缩至顶部，点击视频可收起面板。
• 新增长按菜单、临时倍速和清屏模式，支持主题色、图标、顶部操作栏与安全区配置。
• 新增短剧播放，支持指定集起播、列表或宫格选集、自动连播、剧集标签与简介、已看状态和自定义业务按钮。
• 新增短剧锁定与试看控制，支持试看截止暂停、解锁请求和授权后的剧集回写；内容授权与支付由接入项目处理。
• 新增列表替换、追加和分页加载，支持失败重试、过期响应隔离，以及最多两个播放器的相邻预载。
• 新增页面内嵌播放，提供 uni-app Android nvue 组件和 uni-app x 标准 native-view 组件。
• 新增页面显隐控制、同组播放互斥、创建取消与关闭释放，支持宿主保存和恢复观看位置。
• 新增 uni-app / uni-app x 完整示例，提供短视频与短剧共 16 个场景入口，以及评论、分页、互动回写和观看历史演示。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

其他

lizhao-video-feed · 原生短视频流与短剧播放器

介绍

让你的 App 快速拥有沉浸式短视频流与短剧播放体验。

lizhao-video-feed 面向 uni-app / uni-app x 提供原生全屏视频流和页面内播放器。用户可上下滑动切换作品，查看作者与互动信息，打开评论和短剧选集，并使用倍速、清屏、试看与自动连播。

播放、手势和业务面板由原生视图承载，无需在页面中拼装 video 或 swiper。视频、作者、评论、点赞、收藏、分享、解锁和分页数据由接入项目提供；插件通过事件发出请求，并在业务确认后更新界面。

1.1.0 支持 Android 6.0 及以上与 iOS 13.0 及以上。iOS 为首发支持版本，接入后请在目标设备验证全屏、页面内嵌与所用媒体编码；Harmony 当前仍为预览实现。

功能特色

适合哪些场景

下载与导入

1. 在插件市场选择“使用 HBuilderX 导入插件”，导入到自己的 uni-app 或 uni-app x 项目。
2. 保留完整的 uni_modules/lizhao-video-feed 目录和插件名称。
3. 在页面脚本中从插件根目录导入：

import { openVideoFeed, closeVideoFeed, createVideoFeedContext, getVideoFeedCapabilities } from '@/uni_modules/lizhao-video-feed'

新增本插件后需要重新制作 Android 自定义基座、iOS 基座 / IPA 或 Harmony HAP。只更新页面资源无法加入原生播放器和依赖。Android 原生依赖为 Media3 1.9.0；不要手动复制其他版本的 AAR 覆盖它。

示例中的互动、评论、分页与解锁为本地 Mock；视频地址由你提供。示例不会调用抖音接口，不包含抖音素材，也不提供内容或支付服务。

注册示例页面

示例文件不会自动成为应用页面。先把对应宿主的条目合并到项目 pages.json 的 pages 数组，保留项目已有页面；path 不写文件扩展名。uni-app 使用：

{
  "pages": [
    { "path": "uni_modules/lizhao-video-feed/example/uniapp/index", "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
    { "path": "uni_modules/lizhao-video-feed/example/uniapp/feed", "style": { "navigationBarTitleText": "视频流与短剧" } }
  ]
}

APP-PLUS 分支对应 Android / iOS 的 nvue 页面，APP-HARMONY 分支对应 Harmony 的 Vue / embed 页面。uni-app x 使用下面的页面清单；插件会自动选择对应宿主的组件实现，无需额外配置 easycom：

{
  "pages": [
    { "path": "uni_modules/lizhao-video-feed/example/uniappx/index", "style": { "navigationBarTitleText": "原生播放" } },
    { "path": "uni_modules/lizhao-video-feed/example/uniappx/inline", "style": { "navigationBarTitleText": "页面内播放" } },
    { "path": "uni_modules/lizhao-video-feed/example/uniappx/feed", "style": { "navigationBarTitleText": "视频流与短剧" } }
  ]
}

使用包含本插件的对应 App 原生包，导航到上述 index 页面，填写 HTTPS MP4 地址后打开示例。Web / 小程序不使用这些 App 播放示例。

5 分钟跑通：打开短视频流

将 https://example.com/... 替换为自己有权播放的真实 MP4 地址，放入按钮处理函数：

openVideoFeed({
  feedId: 'home-feed',
  items: [
    { itemId: 'v1', source: { url: 'https://example.com/one.mp4' }, poster: 'https://example.com/one.jpg',
      author: { authorId: 'u1', name: '作品作者' }, itemDescription: '第一条作品' },
    { itemId: 'v2', source: { url: 'https://example.com/two.mp4' }, poster: 'https://example.com/two.jpg', title: '第二条作品' }
  ],
  options: { mode: 'video', loop: true, maxPlayerCount: 2, preloadCount: 1 },
  onEvent: (event) => {
    if (event.type == 'created') {
      // 保存 feedId/sessionId；旧页面不能用旧身份控制新会话。
      console.log('视频会话已创建')
    }
    if (event.type == 'firstframe') console.log('真实首帧已显示')
    if (event.type == 'error') console.log('播放错误：' + event.error?.errCode)
  },
  success: (_res) => { console.log('原生界面已就绪') },
  fail: (error) => { console.log('打开失败：' + error.errCode) },
  complete: (res) => { console.log('打开结算：' + res.ok) }
})

created 表示会话已登记，此时可监听或取消；ready / success 表示原生承载可控制；firstframe 才表示真实画面出现。items: [] 合法，只有空态和 ready，不会伪造首帧。

从基础到进阶：按业务模块使用

以下示例假定已经取得当前会话的 feedId 与 sessionId。业务数据请求应保留事件中的请求身份，结果只回写给仍然有效的当前会话。

模块一：播放控制与页面生命周期

const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
context.pause({ success: (_res) => { console.log('暂停已确认') } })
context.seek({ positionMs: 3000, fail: (error) => { console.log('跳转失败：' + error.errCode) } })
context.setRate({ rate: 1.25 })
context.play({})
// 页面/Tab 隐藏时暂停；它不会清除用户点下的暂停状态。
context.setActive({ active: false })
context.setActive({ active: true })
// 页面卸载时释放此身份；重复调用不会销毁新会话。
context.destroy({})

• 控制命令必须传对象，可用 {}。除监听、解绑、销毁外，命令要求 ready。
• seek 单位毫秒，成功回调等待原生跳转确认；超过已知时长或试看边界明确失败，不偷偷截断。
• rate 是基础倍率；按住指定侧边的临时倍率结束后恢复基础倍率。Harmony 支持 0.5 / 0.75 / 1 / 1.25 / 1.5 / 1.75 / 2 七档。
• 主动 pause 会跨切页保留；前后台恢复、关闭评论面板不会自动取消主动暂停。
• 默认 playbackGroup: 'lizhao-video-feed'。同组只有一个会话能够输出音轨；被其他会话抢占后，显式 play 或 setActive(true) 才重新争取播放。预载不播放、不抢组。
• 每条命令 success / fail 互斥一次，随后 complete 一次。回调抛出异常不会阻止其他回调或资源清理。

全屏可用 closeVideoFeed({ feedId, sessionId }) 关闭；嵌入组件使用 context.destroy({}) 或卸载组件。

模块二：列表更新与分页

业务列表中 itemId 必须唯一且稳定。switchTo 按 ID 定位；setItems 原子替换；appendItems 用于宿主主动追加；异步分页结果必须使用 resolveLoadMore。

// 在 openVideoFeed.options 中配置 hasMore: true。
// 放入 onEvent 的 loadmore 分支；items 为服务端返回的新条目。
if (event.type == 'loadmore') {
  const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
  context.resolveLoadMore({
    requestId: event.requestId!,
    listRevision: event.listRevision,
    outcome: 'success',
    items: nextItems,
    hasMore: false,
    fail: (error) => { console.log('分页响应未被接受：' + error.errCode) }
  })
}

requestId + listRevision 必须原样传回。刷新、追加或更新条目会增加版本并作废旧请求；迟到结果返回 9093012，不能解除新请求的加载状态。批次内或与已有列表重号会整批失败，旧列表不变。

context.switchTo({ itemId: 'v2', positionMs: 0 })
context.setItems({ items: newItems, hasMore: true })
context.appendItems({ listRevision: latestState.listRevision, items: moreItems })
context.updateItem({ listRevision: latestState.listRevision, item: completeItem })

updateItem.item 是完整替换快照；未提供的可选字段恢复默认值。纯互动更新不重建当前播放器；当前源 URL、媒体身份或门禁变化会建立新播放代次。不要用 durationHintMs 判断可跳转范围，它只用于列表展示。

模块三：互动与评论

右侧作者、关注、点赞、评论、收藏、分享，以及搜索和剧集入口通过 action 通知宿主。requestedSelected 表示用户期望状态，不表示服务端已保存成功。

if (event.type == 'action' && event.action?.action == 'like') {
  // 先调用自己的业务服务。成功后携带完整条目回写。
  const context = createVideoFeedContext({ feedId: event.feedId, sessionId: event.sessionId })
  context.updateItem({ listRevision: event.listRevision, item: savedItem })
}

评论面板打开后发送 commentsrequest，携带 itemId、requestId、listRevision、requestKind 和 lastCommentId。首次请求替换列表；more 追加；retry 重试上次操作。

context.setComments({
  itemId: event.itemId,
  listRevision: event.listRevision,
  requestId: event.requestId!,
  outcome: 'success',
  items: [{ commentId: 'c1', author: { authorId: 'u2', name: '观众' }, text: '评论内容' }],
  hasMore: false
})

• 异步请求响应必须带 requestId；宿主确认评论提交或点赞后，可省略它主动回写完整评论快照。
• commentsubmit 只返回文字请求，插件不会擅自发布；commentlike 也需要宿主处理。
• 当前视频变化、列表版本变化或面板关闭后，旧评论响应不能写入其他视频。
• 点击评论后，白色评论层会从底部平滑上推，视频同步调整到顶部播放区；面板直接铺满屏幕余下空间，不会在底部留下黑色空白。
• 评论面板打开时，点击上方视频区域可直接收起面板；评论列表、输入框和面板按钮仍独立响应，不会误触播放或切页。
• ui.commentPlayback: 'shrink' 保持原播放意图，pause 暂停；两种策略使用同一套上下分区视觉。panelVideoScale 继续接受 0.4～0.8，用于映射顶部播放区高度，不会再对视频做二次缩放。
• 评论标题与输入区固定，评论列表独立滚动；评论滚动、输入和进度拖动不会当作视频翻页。

模块四：短剧、选集与试看

openVideoFeed({
  feedId: 'series-feed',
  items: [
    { itemId: 'e1', source: { url: 'https://example.com/episode1.mp4' }, poster: 'https://example.com/episode1.jpg',
      title: '镜中重逢', durationHintMs: 90000,
      drama: { seriesId: 's1', episodeId: 'e1', episodeNumber: 1, totalEpisodes: 6, seriesTitle: '剧集名称',
        seriesTags: ['都市逆袭', '高能反转'], seriesDescription: '用于选集顶部展示的作品简介。', watched: true } },
    { itemId: 'e2', source: { url: 'https://example.com/episode2.mp4' }, poster: 'https://example.com/episode2.jpg',
      title: '迟到五年的信', durationHintMs: 86000,
      drama: { seriesId: 's1', episodeId: 'e2', episodeNumber: 2, locked: true, trialEndMs: 8000 } },
    { itemId: 'e3', poster: 'https://example.com/episode3.jpg', title: '照片里的秘密',
      drama: { seriesId: 's1', episodeId: 'e3', episodeNumber: 3, locked: true } }
  ],
  options: { mode: 'drama', initialItemId: 'e1', autoNext: true, loop: false,
    ui: { episodeLayout: 'list', episodePlayback: 'shrink', episodeActions: [
      { buttonId: 'favorite-series', label: '收藏短剧' },
      { buttonId: 'unlock-card', label: '解锁短剧卡', emphasized: true }
    ] } }
})

• 短剧每项必须包含 drama。选集默认列表，可切为 grid；标题、标签、简介、时长提示与已看状态由宿主提供。
• 列表模式使用深色作品信息区、选集标签、竖版封面、两行标题和辅助状态行；当前集使用主题强调色，底部最多展示两个 episodeActions。内置示例提供 6 集人物短剧 Mock 数据验证长标题、试看、锁定和业务按钮。
• HTTPS 剧集建议为每一集提供 poster，推荐接近 3:4 的竖版图且单图不超过 2MiB。Android 本地 MP4 未传 poster 时可使用有界首帧兜底；iOS 与 Harmony 应显式传封面，保证三端首屏一致。
• locked: true 且无正数 trialEndMs 时不请求源，可省略 source，只显示解锁入口。
• 正数 trialEndMs 表示本集可看的前缀区间，达到边界发送 trialend 并暂停；拖动或 seek 不能越过它。锁定媒体不进行相邻预载。
• 用户请求解锁发送 action.action: 'unlock'。宿主完成授权后，通过 updateItem 传回完整条目、locked: false、trialEndMs: 0 和有效源。本插件不校验订单、不提供支付，也不能代替服务端媒体鉴权。
• autoNext 在自然结束后切下一条；最后一条保留结束状态。loop 与 autoNext 不能同时为 true。
• 观看历史由宿主持久化 itemId + positionMs，重新打开时传 initialItemId + initialPositionMs。完整示例包含本地恢复流程。

模块五：界面、手势与清屏

options: {
  ui: {
    title: '推荐', showBack: true, showSearch: true,
    theme: { backgroundColor: '#000000', accentColor: '#FF375F', fontSize: 14, iconSize: 28 },
    actions: [{ action: 'share', visible: true, label: '转发' }],
    longPressRateRegion: 'right-edge', longPressRate: 2,
    commentPlayback: 'shrink', episodePlayback: 'pause', panelVideoScale: 0.65
  }
}

单击视频切换播放意图，双击发送点赞请求，中央长按打开倍率/清屏菜单。可选左侧或右侧 20% 区域临时倍速；控件区域不触发长按倍率。松开、取消、切项、打开面板和进入后台都会恢复基础倍率。

Android 上下拖动时，当前视频与目标上一条或下一条封面使用同一位移轨道连续跟手；手势不等待当前视频首帧，列表和封面就绪后即可拖动。未达到切换条件时一起回弹，切换成功后新页面在原位接管，并在宿主确认切换后准备目标视频，不会先露出整块黑色区域再出现视频。回弹中再次按下可从当前位置继续拖动。翻页手势识别后不再触发同一次触摸的单击、双击或长按操作。

右侧点赞、评论、收藏、分享等互动区，作品信息区和中央播放按钮均支持从原位置开始上下拖动：短按仍执行原按钮动作，明确纵向拖动后取消该次点击并转交整页分页。顶部返回/搜索和底部播放/进度控制保持独立，不会被分页手势接管。

• 相邻封面在列表绑定时开始预取，不等待当前视频的 firstframe；优先使用条目的 poster。HTTPS 视频建议始终提供 HTTPS poster，以保证首次打开和弱网快速滑动时已有可显示封面；插件不会为了取封面重复下载远程视频。
• Android 本地绝对路径或 file:// MP4 未传 poster 时，会在后台提取首帧并缩放到最大边约 1024；封面缓存最多 4 项，提帧最多 1 个运行任务和 3 个等待任务，不增加播放器数量。
• Android 8.1 及以上可直接按目标尺寸提取；Android 8.0 及以下只为最大边不超过 1024 的本地视频兜底。更大的旧系统本地视频请显式提供 poster。
• 首条、末条越界拖动没有真实相邻项，因此只回弹当前页，不伪造循环封面。maxPlayerCount: 2 的上限保持不变。

context.setClearScreen({ clearScreen: true }) 隐藏作品信息和业务互动，仍保留退出、暂停/继续与退出清屏入口。context.setPanel({ panel: 'comments' }) 可主动控制面板，每个会话最多一个。

默认自动处理安全区；Android 全屏顶栏在状态栏安全区后保留 20dp 视觉间距。宿主自己布局状态栏或底部导航时，可设 safeAreaMode: 'manual'，提供 topInset / bottomInset。插件不绘制宿主底部 TabBar。

模块六：页面内嵌入

<lizhao-video-feed
  style="width: 100%; height: 500px"
  feed-id="page-feed"
  :initial-items="items"
  :initial-options="options"
  @event="onFeedEvent"
/>

组件只有三个初始化属性和一个事件出口：

挂载后修改初始化属性会报告 9093002，不会隐式重建。取得 created 的身份后使用 createVideoFeedContext 更新列表和播放；组件卸载自动释放。

uni-app Android / iOS 在 nvue 页面使用兼容模式组件；普通 Vue 页面请使用全屏 API。Harmony 的 uni-app Vue 页面使用同名组件，内部通过 embed 绑定 ArkUI 原生视图。inlineView: true 表示当前平台提供上述承载，不表示 Android/iOS 普通 Vue 页面能够使用 nvue 组件。

uni-app x 使用标准 native-view 组件；插件会根据 uni-app 或 uni-app x 宿主自动选择对应实现，业务页面继续统一使用 <lizhao-video-feed>，无需额外配置 easycom。

为组件设置明确高度或占满有界父容器。宿主页面/Tab 隐藏时仍需调用 setActive(false)；仅改变 CSS 可见性不能代替业务显隐通知。

API 速查

完整参数、返回值、回调和逐字段参考覆盖全部 44 个公开类型。getState 通过结果的 state 返回独立快照；修改快照不影响原生实例。

常用配置默认值

平台与承载方式

1.1.0 支持 Android 6.0 及以上与 iOS 13.0 及以上；发布前请在自己的目标机型确认全屏播放、页面内嵌与所用媒体编码。Harmony 当前为预览实现。Android 使用 Media3，iOS 使用 AVPlayer，Harmony 使用 AVPlayer 与 XComponent。

• 目标最低环境：HBuilderX 5.24、Android 6.0、iOS 13、Harmony API 12；使用最低版本前请先在目标系统试运行。具体媒体编码以系统解码能力为准。
• 当前媒体范围为 HTTPS MP4，以及宿主已有访问权的 file:// 或绝对路径。本插件不自动申请相册或文件目录权限。
• HLS、HTTP 明文地址和自定义媒体请求头当前不开放，明确返回 9093006，不会静默丢弃请求头。
• Web / 小程序没有原生播放器实现，全屏 API 返回 9093001。不要将 App 组件直接用于这些平台。
• getVideoFeedCapabilities() 查询当前平台的实现声明，不检测已安装基座版本或当前页面类型；原生实现存在不代表任意视频格式都能解码。

错误码

错误主题固定为 lizhao-video-feed，错误不包含媒体地址、请求头或原生异常正文。

常见问题

打开成功为什么仍没有画面？ success 只表示原生承载 ready。监听 firstframe / error 判断媒体结果；空列表没有首帧。

刷到下一条时旧视频会继续响吗？ 切项先暂停旧项，旧代次回调被隔离；预载始终静音且不播放。同组会话也互斥。页面或 Tab 隐藏时请正确调用 setActive(false)。

为什么点赞后数字不立即增加？ 插件只发送业务请求。你的服务保存成功后调用 updateItem 回写完整快照，失败时原状态保留。

评论或选集会导致上滑误切页吗？ 面板、输入、滚动列表、按钮和进度控件有独立手势区域。面板打开时不执行视频翻页。

怎么处理网络慢、空页或分页失败？ 在对应事件中完成业务请求，原样回传请求 ID 和列表版本。空页且还有后续数据时等待用户重试；错误或超时同样不会自动无限循环。

可以防止收费视频被下载吗？ 本插件只提供播放门禁与界面流程。源访问控制、过期签名、订单权限和 DRM 由服务端及相应媒体方案负责，不能把客户端 locked 字段当成内容授权凭据。

更新哪些内容要重新打基座？ 页面样式、业务 JS、普通资源或文档通常只需更新页面资源；UTS 原生逻辑、Kotlin / Swift / ETS、依赖、Manifest 与平台配置变化必须使用匹配的原生包。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列 UTS 插件

以下为已确认公开市场页的作者系列 UTS 插件，当前插件也列在首行；它们可按业务需要组合使用，lizhao-video-feed 不强制依赖其中任何一个。