更新记录

1.0.0（2026-10-16）

• 新增 Android bilibili / 爱奇艺双风格控制层，支持竖屏与横屏布局、加载提示、结束重播、选集面板和截图分享面板；爱奇艺风格提供 LIZHAO 品牌加载动画与水印，premium-dark 可作为兼容别名使用。
• 新增适配 uni-app nvue 与 uni-app x uvue 的原生视频播放器组件；Android 使用 GSYVideoPlayer，iOS 使用系统 AVPlayer，两端使用相同的组件标签、playerId 和基础播放 API。
• 新增本地应用资源与 HTTP(S) 视频播放，支持自动播放、播放、暂停、恢复、停止、进度跳转、倍速、横屏全屏和锁屏，并提供播放状态、进度、错误事件与上下文控制 API。
• 新增播放列表、选集切换、下一集、自动连播及真实清晰度切源，适用于课程和剧集播放。
• 新增 Android 滑动进度、亮度与音量调节、双击播放／暂停、长按临时倍速及首次手势引导。
• 新增 Android 图片与视频启动广告，支持倒计时、延迟跳过、静音和详情事件；提供可选暂停广告卡，广告结束后接续正片。
• 新增 Android VIP／试看配置、试看倒计时、到期暂停及试看范围外跳转拦截，以及分享、商品、会员、更多工具和弹幕设置等业务面板。
• 新增 Android 视频帧截图，可按配置包含控制层，返回缓存文件路径、尺寸和进度；截图分享面板通过事件交由应用处理保存、评论和分享。
• 新增投屏、小窗、下载、录屏、后台音频、字幕和举报等 Android 业务入口事件；实际业务能力由接入应用实现。

平台兼容性

uni-app(5.26)

uni-app x(5.26)

lizhao-video-player

为 Android / iOS 应用提供可嵌入页面的原生视频播放器，支持 uni-app 与 uni-app x。Android 使用 GSYVideoPlayer，iOS 使用系统 AVPlayer；两端保留相同的组件标签、playerId 和基础播放 API。

iOS 当前版本优先保证本地／HTTP(S) 视频的显示、自动播放、播放控制、进度、倍速、列表／清晰度切换、横屏和锁屏。Android 专属的手势引导、启动广告、VIP/试看、业务面板和截图不会在 iOS 上伪造成功；调用这些扩展时会返回明确错误或 error 事件。

功能特色与适用场景

• 两种观看风格（Android）：粉色轻量控制层与绿色沉浸控制层，进度、面板、选中态和手势反馈保持一致；运行中可切换。iOS 使用基础 AVPlayer 控制层，不切换 Android 主题。
• 清晰的操作区域：Android 绿色风格在竖屏使用单行播控，横屏将细进度与操作栏分开，选集和截图分享展开时视频缩至左侧；粉色风格保留分行播控。iOS 控件避让刘海和底部安全区，锁定后保留“解锁”。面板内容较多时可滚动查看。
• 统一的原生控件：Android 原生双风格共用圆头、圆角矢量图标，图形大小与线条粗细一致；小窗和截图的标签独立排在图标下方，随系统字体自动增高。横屏控件随实际刘海和系统安全区更新位置。
• 完整观看流程：播放、暂停恢复、进度拖动、倍速、横屏全屏、锁屏、加载提示、错误事件和结束重播。
• 剧集与课程：可滚动选集、下一集、自动连播，以及按真实地址切换清晰度。
• 自然手势（Android）：左右滑动进度、左侧上下滑动亮度、右侧上下滑动音量、双击播放暂停、长按临时倍速，首次使用有引导。
• 可选广告（Android）：图片和视频贴片、倒计时、延迟跳过、静音与详情事件；广告关闭后接续正片。

适合短片、课程、剧集和企业视频展示。Android 风格只描述观看界面，不包含第三方品牌素材、内容服务或账号能力；iOS 以基础播放为主。

下载导入与基础使用

通过插件市场或 HBuilderX 导入 lizhao-video-player。uni-app 使用 nvue 页面承载组件，uni-app x 使用 uvue 页面；为播放器设置明确的宽高。

<template>
  <!-- 同名 player-id 用于后续 API 控制；按实际内容设置 src。 -->
  <lizhao-video-player
    player-id="lessonVideo"
    src="https://example.com/lesson.mp4"
    title="课程第一讲"
    theme="bilibili"
    :autoplay="false"
    style="width: 750rpx; height: 422rpx;"
    @error="onPlayerError"
  />
</template>

<script>
export default {
  methods: {
    onPlayerError(event) {
      // 原生组件事件在部分环境包在 detail 中。
      const result = event.detail || event
      console.log('视频播放失败', result)
    }
  }
}
</script>

示例中的地址是占位地址，使用时替换为可播放的实际视频。完整可点击示例见插件的 example/uniapp/videoPlayer.nvue 和 example/uniappx/index.uvue。

查看风格与全屏控件

uni-app 的原生双风格体验入口为 uni_modules/lizhao-video-player/example/uniapp/videoPlayer.nvue。页面直接提供 bilibili / 爱奇艺风格切换，保留原播放、暂停、选集和全屏 API 调用：

1. 选择风格后点击“全屏”，再点击画面显示操作栏。
2. 查看右侧“小窗”和“截图”：图标与文字上下分开，点击仍执行原来的事件和截图操作。
3. 将手机左右横屏切换，并在放大系统字体后复看；返回、锁屏、侧栏和底部操作应保持可见可点。

uni-app x 的 example/uniappx/index.uvue 当前使用标准播放器入口，适合基础播放与公开 API 体验；原生双风格的视觉对照请使用上面的 nvue 示例。

更新本插件的 Android 原生源码后，请重新运行原生联编或更新一次匹配源码的原生包。只热更新页面资源不会更新旧包里的图标和安全区实现。

选择风格与观看配置

<!-- Android 修改 theme 可实时切换控制层，保留当前播放进度；iOS 忽略该主题配置。 -->
<lizhao-video-player
  player-id="lessonVideo"
  :src="videoUrl"
  :theme="playerTheme"
  :enable-gestures="true"
  :long-press-rate="2"
  :show-gesture-guide="true"
  gesture-guide-key="lesson-player"
  style="width: 750rpx; height: 422rpx;"
/>

Android 引导会避开广告、锁屏和打开的面板；确认后保存本地记录，也可从更多设置重新查看。左右滑动只有松手时才提交进度，取消手势不会跳转。iOS 不显示该引导。

Android iqiyi（包含兼容别名 premium-dark）使用 LIZHAO 品牌加载动画、绿色选中态、线形图标和按压反馈。加载动画跟随真实准备／缓冲状态；横屏选集与截图分享采用右半屏抽屉，关闭后恢复视频画幅，倍速和画质则覆盖在原画面上。选集数量、VIP 角标、画质及广告都来自传入配置，不额外生成内容或权益。

选集与清晰度

将剧集与清晰度地址传给组件即可切换选集和下一集。提供多种清晰度时，每一项都需要对应的真实播放地址；iOS 支持基础切源，不提供 Android 业务面板。

<!-- playlist 可使用下面定义的 episodes。 -->
<lizhao-video-player
  player-id="lessonVideo"
  :playlist="episodes"
  :auto-next="true"
  :loop-playlist="false"
  style="width: 750rpx; height: 422rpx;"
/>

// episodeIndex 是显示集数；API 的 episodeIndex 是从 0 开始的列表索引。
const episodes = [
  {
    id: 'lesson-1', title: '第一讲 · 开始', episodeIndex: 1,
    src: 'https://example.com/lesson-1.mp4',
    qualities: [
      { id: 'hd', label: '高清', src: 'https://example.com/lesson-1-hd.mp4', isDefault: true },
      { id: 'sd', label: '流畅', src: 'https://example.com/lesson-1-sd.mp4' }
    ]
  },
  { id: 'lesson-2', title: '第二讲 · 实践', episodeIndex: 2, src: 'https://example.com/lesson-2.mp4' }
]

选集触发 episodechange；清晰度切换触发 qualitychange。空播放列表时 Android “下一集”透出 tooltap，接入方可决定后续内容。试看片段可通过 vipOptions 及每集的 isVip / trialSeconds 配置，不包含支付流程；iOS 不执行 VIP/试看限制。

可选图片与视频广告（Android）

广告默认关闭。Android 显式配置 startupAd 后播放贴片，倒计时从资源准备好开始；正常结束、跳过或加载失败后恢复原来的正片播放意图。iOS 不展示启动广告，动态开启时会发出 9020001 的 error 事件并继续播放正片。详情点击只发事件，由应用决定是否打开落地页。

<!-- 图片使用 type: 'image'；视频使用 type: 'video'。 -->
<lizhao-video-player
  player-id="lessonVideo"
  :src="videoUrl"
  :startup-ad="ad"
  @adtap="onAdEvent"
  style="width: 750rpx; height: 422rpx;"
/>

// 由你的应用提供广告资源；本插件不请求广告平台投放。
const ad = {
  enabled: true,
  type: 'video',
  src: 'https://example.com/preview-ad.mp4',
  duration: 8,
  canSkip: true,
  skipAfter: 3,
  skipText: '跳过广告',
  brandText: '广告',
  detailUrl: 'https://example.com/product'
}

function onAdEvent(event) {
  const result = event.detail || event
  console.log('广告事件', result.details)
}

图片不展示无效的静音按钮。暂停广告卡为可选扩展入口，使用 showAdCard 或 setAdCardVisible 控制；默认不显示。广告不是下载、支付、跟踪或商业广告 SDK。

API 控制与自定义扩展

import { createVideoPlayerContext, playVideoPlayer, pauseVideoPlayer, showVideoPlayerPanel } from '@/uni_modules/lizhao-video-player'

// 组件 ready 后操作同一个 player-id。
playVideoPlayer('lessonVideo')
pauseVideoPlayer('lessonVideo')
showVideoPlayerPanel('lessonVideo', 'episode')

// 使用上下文读取进度或控制跳转；无需导入插件内部源码。
const player = createVideoPlayerContext('lessonVideo', null)
player.seek({ position: 30, fail: error => console.log('跳转失败', error) })

投屏、小窗、分享、下载队列、录屏、真实弹幕流和字幕服务需要应用接入对应能力，入口事件不代表已完成这些操作。购物、会员和录屏等业务入口默认关闭，可按需显式开启。清晰度和倍速仅展示实际提供或内核支持的选项。

Android 绿色风格的截图分享

横屏点击截图按钮，会截取当前活动播放器的真实视频帧并展示预览；失败或超时可在预览区域重试。showPanel({ type: 'share' }) 也可打开面板，尚无截图时点击预览区域开始截取。切换片源或离开组件后，过期的截图回调不会重新打开面板。

保存、评论和分享按钮通过 sharetap 的 details 返回 type / label / path / currentTime。path 是 App 缓存文件绝对路径，接入方应及时使用，并负责相册授权、实际保存或第三方分享及其结果提示。

这些动作仅在取得有效截图路径后发出。生成缓存截图不代表已经保存到系统相册或发送给其他应用。原有 takeSnapshot／takeVideoPlayerSnapshot API 仍按原契约返回缓存截图，不会强制打开分享面板。

API

createVideoPlayerContext(playerId, ins?)

说明 创建播放器上下文。页面只允许从插件根目录导入。

参数

方法

便捷控制 API

这些函数适合 nvue / uni-app x 页面直接调用，内部会根据 playerId 找到已注册的 <lizhao-video-player> 实例。示例页会同时传 player-id="mainVideo" 和 :playerId="playerContextId"，避免不同运行态的 kebab-case / camelCase 映射差异。

错误码

事件与常用属性

事件返回 playerId / name / state / currentTime / duration / timestamp / details。监听 ready 后可调用上下文；用 statechange、timeupdate 更新应用自己的展示，用 error 处理播放错误。

支持平台与注意事项

Android 使用包含插件原生依赖的自定义基座；iOS 使用 AVPlayer 原生组件。更新对应平台原生代码后，需要重新制作对应平台安装包或自定义基座；仅热更新页面资源不能替换已编译的原生组件。

每个实例使用不同的 playerId。页面离开时调用 release；全屏返回应先交给播放器退出全屏。视频格式的可播放性取决于对应平台的 AVPlayer／GSY 解码能力及资源可访问性。不要把示例中共用一份样片的多个地址当作真实多清晰度资源。

当前内核的画面缩放配置由播放器共享；同屏使用多个实例时，建议统一 objectFit，不要依赖多个实例同时使用不同缩放方式。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。