更新记录

5.2.0（2026-09-24）

新增功能（iOS 端）

• AirPlay 视频投屏全面升级：选择 Mac/Apple TV 后画面与声音一同送到外接设备（URL 播放源，旧版仅音频跟随），投屏期间手机可收起，断开后本地从断点续播
• 新增原生全屏投屏控制页：封面/标题/选集信息、快退15秒/暂停/快进15秒、进度条拖动、定时关闭、倍速、选集、换设备、断开投屏均可在手机端操作
• 新增播放页迷你投屏面板：从控制页返回后播放器区域常驻迷你控制器（三键/功能条/进度条），点“展开”一键回到全屏控制页

体验优化

• 投屏交互时序对齐腾讯视频：选设备 → 接收端接受 → 关闭系统选择器 → 自动进入投屏控制页；切换设备关闭选择器不会误跳页
• 投屏期间进度与播放状态持续同步，不受本地播放器让位影响
• 选集弹层统一为竖屏底部半屏：有标题每行 3 集、纯序号每行 6 集，集数多自动滚动
• 投屏页背景与 Android 端统一为深色渐变；AirPlay 无法调节音量时胶囊提示引导用户在接收端调节
• 连接稳定性增强：10 秒连接超时兜底、路由短暂抖动不误判断开，连接被拒后可立即重新发起投屏

问题修复（iOS 端）

• 修复选择投屏设备后外接设备“只有声音没有画面”的问题（投屏通道改为系统 AVPlayer 视频外投）
• 修复系统选择器未关闭时控制页过早出现、或关闭后不进入控制页的时序问题
• 修复投屏控制页进度条与时间不更新、自动采帧封面不显示的问题

5.1.6（2026-09-20）

问题修复（iOS 端）

• 修复 iOS 端小窗/画中画内快进、快退后声音出现数秒延迟的问题：小窗跳转现于播放态执行，与播放页快进快退体验一致（网络不佳时的缓冲等待属正常现象，双端表现相同）

5.1.5（2026-09-18）

问题修复（Android 端）

• 修复 Android 端小窗播放后回到详情页时，播放器偶现黑屏或无法正常播放的问题
• 修复 Android 端“小窗切画中画后再返回播放页”时，浮窗显示但画面不显示的问题
• 修复 Android 端从画中画/小窗返回后画面可能不续播的问题
• 新增小窗、画中画全链路诊断日志，方便接入方快速定位问题

平台兼容性

uni-app(3.99)

阿里云播放器SDK（ApsaraVideo Player）

uni-app 版阿里云播放器组件：基于 ApsaraVideo Player SDK 封装的 UTS 插件（组件 + 模块混合形态），Android / iOS 双端能力对齐。 内置企业级控制栏与手势交互，提供小窗播放、投屏、后台播放、纯音频、倍速、定时关闭、下载等开箱即用的播放能力。 仅支持 App 端（Android + iOS），H5 / 小程序请使用阿里云官方 Web 播放器。

核心接入方式：

1. 在模板中放置 <ali-player-view> 组件（承载视频渲染 + 内置控制栏）
2. 通过 Props 设置播放源（src / vid + playAuth / vid + STS）和参数
3. 通过 ref 调用组件方法（prepare()、play()、seekTo() 等）
4. 事件通过组件的 @ready / @play / @ended 等回调接收（双端事件负载统一使用 detail 键包裹，业务层通过 e.detail || e 提取）
5. 竖屏返回按钮通过 @back 事件通知 Vue 层（通常执行 uni.navigateBack()）

目录

• 简介
• 功能概览
• 平台支持
• 安装方式
• 集成配置
  • Android 配置
  • iOS 配置
• 快速开始
  • 基础播放示例
  • VidAuth 播放
  • VidSts 播放
  • Props 属性
  • 组件方法
  • Module API
  • 事件列表
• 进阶用法
  • 熄屏/锁屏播放
  • 纯音频模式
  • 小窗播放（统一入口）
  • 后台播放与媒体通知栏（Android）
  • 投屏（Android DLNA / iOS AirPlay）
  • 「更多」抽屉与 UI 定制
  • 倍速播放
  • 定时关闭
  • 视频下载
  • 截图
  • 直播播放
  • 切换播放源
  • 获取播放信息
• License 配置（SDK 7.0.0+）
• 常见问题
• 更新日志

功能概览

平台支持

本插件通过 // #ifdef APP-PLUS 条件编译自动屏蔽非 App 端，不影响其他平台构建。

安装方式

方式一：从 uni-app 插件市场安装（推荐）

1. 前往 DCloud 插件市场 搜索「阿里云播放器SDK」
2. 点击「使用 HBuilderX 导入插件」，自动复制到项目 uni_modules/lord-aliyun-player/
3. 完成 集成配置 后制作自定义基座

方式二：手动拷贝

本插件为标准 component-uts 格式 UTS 插件，导入项目 uni_modules/ 后开箱即用。

uni_modules/lord-aliyun-player/
├── utssdk/
│   ├── interface.uts          # 类型定义与 Module API 契约
│   ├── app-android/           # Android 平台实现（含 License 证书与配置）
│   └── app-ios/               # iOS 平台实现（含 License 证书与配置）
├── changelog.md               # 更新日志（面向使用者）
├── package.json
└── readme.md                  # 本文档（插件详情页正文）

集成配置

⚠️ 原生插件必须通过「自定义基座」或「正式打包」才能运行，不支持标准基座。

Android 配置

使用 UTS 插件格式（本插件）无需手动配置 build.gradle：

插件内部的 utssdk/app-android/config.json 已自动声明阿里云播放器 SDK 的 Maven 依赖（AliyunPlayer:7.14.0-full）与阿里云 Maven 仓库，HBuilderX 云打包时自动处理。

License 配置同样已内置：AndroidManifest.xml 的 licensekey / licensefile 两条 meta-data 与证书文件（assets/cert/AliVideoCert.crt）均已就位，详见 License 配置。

使用者仅需按需补充以下两处配置：

1. AndroidManifest.xml 添加权限

<!-- 网络相关（必须） -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<!-- 本地缓存/截图（需要访问外部存储时加） -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
    android:maxSdkVersion="28" />

<!-- 后台播放（如使用前台 Service） -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

<!-- 熄屏播放保活（PARTIAL_WAKE_LOCK，不点亮屏幕） -->
<uses-permission android:name="android.permission.WAKE_LOCK" />

2. 开启 PiP（画中画）支持

在 manifest.json → App原生配置 → AndroidManifest.xml 配置 中，为主 Activity 添加：

<activity
    android:name="io.dcloud.PandoraEntry"
    android:supportsPictureInPicture="true"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation|keyboardHidden|keyboard|navigation|fontScale|locale|uiMode|colorMode"
    android:exported="true"
    android:hardwareAccelerated="true"
    android:launchMode="singleTask"
    android:windowSoftInputMode="adjustResize" />

3. 解决 META-INF 重复冲突（cling-core 与 cling-support）

插件同时依赖了 cling-core 和 cling-support 两个库，而这两个库内部都打包了同一个 META-INF/beans.xml 文件，云打包时会报重复资源冲突导致打包失败。

在 manifest.json → App原生配置 → Android打包配置 中添加 packagingOptions 排除重复文件：

"app-plus": {
    "distribute": {
        "android": {
            "packagingOptions": [
                "exclude 'META-INF/beans.xml'",
                "exclude 'META-INF/DEPENDENCIES'",
                "exclude 'META-INF/LICENSE'",
                "exclude 'META-INF/NOTICE'"
            ]
        }
    }
}

此配置仅在云打包时生效，不影响本地开发调试。排除的四个 META-INF 文件均为第三方库的元数据文件，排除后不影响运行时功能。

iOS 配置

使用 UTS 插件格式（本插件）无需手动编辑 Podfile：

插件内部的 utssdk/app-ios/config.json 已自动声明 CocoaPods 依赖（AliPlayerSDK_iOS 7.16.0）、deploymentTarget（13.0）与所需系统 frameworks / libraries，HBuilderX 云打包时自动处理。

License 配置同样已内置：Info.plist 的 AlivcLicenseKey / AlivcLicenseFile 与证书文件（Resources/AliVideoCert.crt）均已就位，详见 License 配置。

使用者仅需按需补充以下配置：

1. 后台播放/PiP 与 HTTP 访问（manifest.json）

在 manifest.json → App 原生配置 → iOS Info.plist 配置 节点中添加以下内容（HBuilderX 云打包自动合并进原生工程，无需在 Xcode 中操作）：

<!-- 允许 HTTP（如视频地址是 HTTP） -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

<!-- 熄屏/锁屏后台播放 + PiP（画中画）必须添加 -->
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

不配置此项，iOS 熄屏后播放会被系统中止，PiP 也无法进入后台浮窗。

快速开始

基础播放示例

<template>
  <view class="container">
    <!-- 播放器视图组件（仅 APP 端渲染） -->
    <!-- #ifdef APP-PLUS -->
    <ali-player-view
      ref="player"
      :src="videoUrl"
      :autoplay="true"
      :show-controls="true"
      :auto-hide-controls="true"
      @ready="onReady"
      @play="onPlay"
      @pause="onPause"
      @ended=""
      @error="onError"
      @timeupdate=""
      @fullscreenchange=""
      @pipchange="onPipChange"
      @back="onPlayerBack"
    />
    <!-- #endif -->
  </view>
</template>

<script>
export default {
  data() {
    return {
      videoUrl: 'https://example.com/video.mp4'
    }
  },
  methods: {
    // 准备完成，可获取时长等信息
    onReady(e) {
      console.log('播放器准备完成，时长:', e.duration)
    },

    onPlay() {
      console.log('开始播放')
    },

    onPause() {
      console.log('暂停播放')
    },

    () {
      console.log('播放完成')
    },

    onError(e) {
      console.error('播放错误:', e.code, e.message)
      uni.showToast({ title: '播放失败', icon: 'none' })
    },

    (e) {
      // e.currentTime 和 e.duration 为 Long 类型（毫秒）
      console.log('播放进度:', e.currentTime, '/', e.duration)
    },

    (e) {
      console.log('全屏状态:', e.fullScreen === 1 ? '全屏' : '竖屏')
    },

    onPipChange(e) {
      console.log('PiP 状态:', e.isInPip === 1 ? '已进入' : '已退出')
    },

    // 竖屏时点击返回按钮触发，通常执行页面返回
    onPlayerBack() {
      uni.navigateBack()
    },

    // 通过 ref 调用组件方法
    togglePlay() {
      this.$refs.player.togglePlayPause()
    },

    seekTo(positionMs) {
      this.$refs.player.seekTo(positionMs)
    },

    enterPip() {
      this.$refs.player.enterPip()
    },

    toggleFullScreen() {
      this.$refs.player.toggleFullScreen()
    }
  }
}
</script>

<style>
.container {
  flex: 1;
  background-color: #000;
}
</style>

VidAuth 播放示例

<template>
  <!-- #ifdef APP-PLUS -->
  <ali-player-view
    ref="player"
    vid="your-video-id"
    play-auth="your-play-auth-token"
    region="cn-shanghai"
    :autoplay="true"
    @ready="onReady"
    @back="onPlayerBack"
  />
  <!-- #endif -->
</template>

VidSts 播放示例

<template>
  <!-- #ifdef APP-PLUS -->
  <ali-player-view
    ref="player"
    vid="your-video-id"
    access-key-id="STS_KEY_ID"
    access-key-secret="STS_KEY_SECRET"
    security-token="STS_TOKEN"
    region="cn-shanghai"
    :autoplay="true"
    @ready="onReady"
    @back="onPlayerBack"
  />
  <!-- #endif -->
</template>

Props 属性

选集数据标准结构（EpisodeItem）

episodes 数组每项为一个 EpisodeItem 对象（类型定义见 utssdk/interface.uts）：

[
  {
    "title": "第1集 开篇",
    "url": "https://example.com/ep1.mp4",
    "vid": "",
    "coverUrl": "https://example.com/ep1.jpg",
    "duration": 1260,
    "extra": { "materialId": "10001" }
  },
  { "title": "第2集 进阶" }
]

设计原则：插件仅消费 title 渲染选集面板，不自动换源——播放模式（URL / VidAuth / VidSts）由业务层决定。 用户点选后插件派发 episodeselect 事件（携带 index 与完整 episode 条目），由调用者取源切集并回灌 episodeIndex 保持高亮同步；播完自动连播同理只需回灌 episodeIndex。

// 典型接入：点选后取 episode.url 换源，并回灌 episodeIndex
onEpisodeSelect(e) {
  const { index, episode } = e.detail || e;
  this.currentEpisode = index;          // 回灌 :episodeIndex
  this.src = episode.url;              // 或按 episode.vid 走 VidAuth/VidSts 换源
}

组件方法（通过 ref 调用）

平台列：双端 = Android + iOS 均支持；Android / iOS = 仅对应平台生效。标注 @deprecated 的方法仍可用，但建议改用统一入口。

Module API（跨页面调用）

除上述 ref 方法外，插件另导出一套同步 Module API（共 70 个）。二者底层驱动同一个原生 View，选用原则：

• 优先用 ref 方法：同页面内调用，无需关心 playerId
• 用 Module API：调用方与播放器组件不在同一页面时（如独立投屏页、全局音频控制器），此时拿不到 ref

import { play, pause, setAudioOnly, getCurrentPosition } from '@/uni_modules/lord-aliyun-player'

// 入参统一为单个 options 对象，playerId 缺省 'default'（需与组件的 player-id 属性一致）
play({ playerId: 'main-player' })
setAudioOnly({ playerId: 'main-player', enabled: true })

// 出参统一 { code, message?, ...data }，code === 0 为成功
const res = getCurrentPosition({ playerId: 'main-player' })
if (res.code === 0) {
  console.log('当前位置', res.position)
}

// 日志降噪（全局生效，与 playerId 无关）：release 环境建议 'warn' 或 'off'
import { setPlayerLogLevel } from '@/uni_modules/lord-aliyun-player'
setPlayerLogLevel({ level: 'warn' })

调用前提：绝大多数 API 需播放器 View 已挂载（组件已渲染），View 不存在时返回 { code: -1, message: 'View not found for playerId: xxx' }。完整函数清单、参数与返回结构见 utssdk/interface.uts。

事件列表

平台列：双端 = Android + iOS 均派发；Android = 仅 Android 派发（iOS 不派发，调用方不应在 iOS 上依赖）。 注意：为保证双端序列化一致，布尔字段统一以 Int（1/0）传递，判断时用 e.xxx === 1 或直接真值判断。

back 事件说明：内置控制栏的返回按钮行为根据横竖屏自动区分：

• 横屏（全屏）：点击返回 → 退出全屏回到竖屏
• 竖屏：点击返回 → 触发 back 事件，由 Vue 层决定行为（通常 uni.navigateBack()）

进阶用法

熄屏/锁屏播放

// 开始播放后调用，申请保活锁
this.$refs.player.enableKeepPlayingOnScreenOff()

// 暂停 / 完成 / 出错时释放
this.$refs.player.disableKeepPlayingOnScreenOff()

组件内已在 play() 时自动调用 enableKeepPlayingOnScreenOff，在播放完成/出错时自动释放，通常无需手动调用。

纯音频模式（听视频）

// 开启纯音频模式（仅播放音频不渲染画面）
this.$refs.player.setAudioOnlyMode(true)

// 关闭纯音频模式
this.$refs.player.setAudioOnlyMode(false)

监听纯音频模式变化：

<ali-player-view @audioonlychange="onAudioOnlyChange" />

<script>
methods: {
  onAudioOnlyChange(e) {
    console.log('纯音频模式:', e.isAudioOnly ? '已开启' : '已关闭')
  }
}
</script>

小窗播放（统一入口）

系统要求：Android 8.0+（API 26）/ iOS 15+。 Android 为腾讯视频式分层浮窗（已授悬浮窗权限时系统画中画，未授权时应用内浮窗，App 不退后台），iOS 为系统画中画；离开 App 自动起窗双端体验一致，接入方无需处理悬浮窗权限编排。

// 进入小窗（返回 Boolean 表示是否成功）
const ok = this.$refs.player.enterSmallWindow()

// 退出小窗（自动识别当前小窗类型）
this.$refs.player.exitSmallWindow()

// 查询是否处于小窗
const inSmall = this.$refs.player.isInSmallWindow()

统一监听 smallwindowchange（跨平台一致，mode 区分底层实现）：

<ali-player-view
  ref="player"
  @smallwindowchange="onSmallWindowChange"
/>

<script>
methods: {
  onSmallWindowChange(e) {
    // e.active === 1 表示已进入小窗（mode: 'pip'=系统画中画 / 'float'=应用内浮窗；iOS 恒为 'pip'）
    console.log('小窗状态:', e.active === 1 ? '已进入' : '已退出')
  }
}
</script>

离开 App 自动进小窗（默认开启）：

// 关闭“离开 App 自动进小窗”（默认开启）
this.$refs.player.setAutoSmallWindowOnLeave(false)

画中画旧 API：enterPip() / exitPip() / isInPipMode() 已标记 @deprecated，仍可用但建议迁移到 enterSmallWindow() 系列。Android 如需指定宽高比可用 enterPipWithRatio(w, h)。

后台播放与媒体通知栏（Android）

以下能力仅 Android 生效。iOS 后台音频由系统 UIBackgroundModes: audio + AVAudioSession 自动承载（见「熄屏/锁屏播放」）。

默认行为（无需额外调用）：App 退到后台时继续播放，并自动切为纯音频 + 显示媒体通知栏（锁屏 MediaSession 控制），回到前台自动恢复视频。可按需覆盖默认开关：

// 媒体通知栏 + 锁屏 MediaSession 控制开关（默认开启）
// 开启后进入小窗/后台且正在播放/暂停时显示通知栏（播放·暂停 / 快退 / 快进 / 关闭），关闭时立即移除
this.$refs.player.setMediaNotificationEnabled(true)

// App 退到后台是否继续播放（默认 true）
// 设为 false 恢复旧行为：退到后台自动暂停、回到前台自动恢复
this.$refs.player.setKeepPlayingInBackground(true)

// 后台自动切纯音频开关（腾讯视频式，默认开启）
// 正在播放视频时退到后台（非小窗）自动切纯音频并显示通知栏，回前台自动恢复视频
this.$refs.player.setBackgroundAudioEnabled(true)

需在 AndroidManifest.xml 声明 FOREGROUND_SERVICE、WAKE_LOCK 等权限（见 Android 配置）。手势调音量自动取消静音会派发 mutedchange 事件；音频焦点变化（如来电、其他 App 抢占）会派发 audiofocuschange 事件。注：这两个事件本身是双端的（iOS 由 AVAudioSession 打断通知驱动），仅上述后台/通知栏开关 API 为 Android 专属。

投屏（Android DLNA / iOS AirPlay）

组件对外提供统一的投屏 API，底层按平台自动路由：

投屏源限制： Android DLNA 需向电视下发可直接播放的媒体地址，因此仅 URL 播放源（http/https 直链） 支持投屏；投屏地址由组件自动取当前播放 URL，无需额外传入。VidAuth/VidSts 的真实播放地址由 AliPlayer SDK 内部解析、应用层无公开 API 获取，故 Android 不支持投屏（点击提示“当前播放源不支持投屏”）。iOS 同样仅 URL 源可实现视频+音频外投；VidAuth/VidSts/加密源下 AirPlay 仅音频路由到外接设备，视频画面留在手机。

iOS 实现原理：阿里云 AVPPlayer 自有渲染管线不参与系统 AirPlay 视频外投通道，组件在投屏会话建立时自动用同一可播 URL 交给系统 AVPlayer（allowsExternalPlayback）接管播放，断开时把最后进度交回本地续播；真实开始/断开仍由用户经系统选择器操作、由路由回调更新状态，无法程序化强制断开。

基本用法

// 打开投屏入口（Android 弹设备列表；iOS 弹系统 AirPlay 选择器）
this.$refs.player.showDlnaDeviceList()

// 查询是否正在投屏
const casting = this.$refs.player.isDlnaCasting()

// 投屏中的远端控制（AirPlay 场景映射为本地播放器操作）
this.$refs.player.pauseDlnaCasting()
this.$refs.player.resumeDlnaCasting()
this.$refs.player.seekDlnaCasting(60000) // 跳到 60s
this.$refs.player.setDlnaVolume(50)       // 音量 0-100

投屏页（组件默认实现，双端对齐）

点击控制栏投屏按钮即打开原生全屏投屏页（零配置，深色渐变背景双端一致）：

• Android：设备搜索 / 设备列表 / “找不到投屏设备？”提示；已在投屏中时打开投屏控制页（遥控/切换/断开）；
• iOS：设备选择页（AirPlay 行卡片 + 排查提示）→ 点 AirPlay 行返回播放页并弹系统选择器 → 接收设备接受后关闭选择器 → 自动进入全屏投屏控制页（封面/标题、快退15秒/暂停/快进15秒、进度拖动、定时关闭/倍速/选集/换设备/断开）；控制页点返回后播放器区域出现迷你投屏面板，点“展开”回全屏控制页；选集为竖屏底部半屏弹层（有标题每行 3 集/纯序号每行 6 集，可滚动）。

iOS 投屏时序对齐腾讯视频：连接超时从“关闭选择器”起算（10s 兜底）；切换设备关闭选择器不会误跳页；断开=在确认弹窗或选择器中选 iPhone 扬声器；AirPlay 音量由接收端控制（系统限制，手机调音量时胶囊提示）。

监听投屏状态与进度

推荐统一监听 castingstatechange（状态机驱动，跨平台语义一致），旧事件 castingstart/castingstop/castingerror 并行保留做兼容：

<ali-player-view
  ref="player"
  @castingstatechange="onCastingStateChange"
  @castprogress="onCastProgress"
/>

<script>
methods: {
  onCastingStateChange(e) {
    // e.state 对应 CastState：0=Idle 4=Casting 5=Paused 6=Stopped -1=Error
    console.log('投屏状态:', e.stateName, '设备:', e.deviceName)
    if (e.state === -1) {
      console.error('投屏出错:', e.code, e.message) // code 对应 CastingErrorCode
    }
  },
  onCastProgress(e) {
    // 投屏播放进度（毫秒）
    console.log('投屏进度:', e.currentTime, '/', e.duration)
  }
}
</script>

跨平台对齐说明（iOS ↔ Android）

• castprogress 进度回传：Android 由 DLNA 设备真实回传播放位置；iOS 投屏期由组件独立进度通道（500ms）读取接管播放器位置派发，本地播放器暂停让位不影响进度走时。两端事件负载 { currentTime, duration } 一致。
• 投屏日志桥接 JS 控制台：投屏关键日志会桥接到前端 console，便于排查。Android 前缀 [DlnaCasting]、iOS 前缀 [AirPlayCasting]；带错误标签（Android [DLNA-ERROR] / iOS [AIRPLAY-ERROR]）的日志走 console.error，其余走 console.log。
• iOS AirPlay 自动重连（路由恢复）：当用户经系统控制中心断开后再次接入同一 AirPlay 路由时，组件通过 AVAudioSession.routeChangeNotification 检测到路由恢复，会自动将投屏会话从 Error/Stopped 状态转回 Casting 并重新派发 castingstart/castingstatechange，无需应用层额外处理。

“更多”抽屉与 UI 定制

控制栏右上角“更多”按钮弹出底部抽屉，内置五个条目：分享、收藏、倍速播放、定时关闭、下载。 条目与顺序通过 moreActions 配置，主题色与全部文案均可定制，适配不同产品风格与多语言场景。

条目配置（moreActions）

<!-- 只保留倍速与定时关闭，隐藏分享/收藏/下载 -->
<ali-player-view :moreActions="['speed', 'timer']" />

<!-- 传空数组隐藏控制栏“更多”按钮 -->
<ali-player-view :moreActions="[]" />

条目行为分两类：

<template>
  <ali-player-view :favorited="isFav" @moreaction="onMoreAction" />
</template>
<script>
export default {
  data() { return { isFav: false } },
  methods: {
    onMoreAction(e) {
      const { action } = e.detail || e
      if (action === 'favorite') {
        // 调业务收藏接口，成功后回写 favorited 完成图标回显
        this.isFav = !this.isFav
      } else if (action === 'share') {
        uni.share({ /* ... */ })
      }
    }
  }
}
</script>

主题色（themeColor）

<ali-player-view themeColor="#FF6B00" />

一处配置全局生效：控制栏进度条、投屏/纯音频激活态、抽屉高亮、选集当前集高亮同源换色。 支持 #RRGGBB / #AARRGGBB，非法值忽略并保留默认蓝色（#00A8F6）。

文案定制（texts）

全部内置 UI 文案可通过 texts 覆盖（未覆盖项用默认中文），双端 key 同名同义，类型定义见 interface.uts 的 PlayerTextsConfig：

<ali-player-view :texts="{
  share: 'Share',
  favorite: 'Favorite',
  favorited: 'Favorited',
  speed: 'Speed',
  sleepTimer: 'Sleep Timer',
  download: 'Download',
  cancel: 'Cancel',
  loading: 'Loading...',
  speedChangedToast: 'Switched to {rate}'
}" />

占位符（{count}/{minutes}/{rate}/{message}）由原生侧运行时替换，覆盖文案时请保留占位符。

倍速播放

内置倍速弹层：预设档位宫格 + 自定义滑杆（0.5~4.0 无级调节），横屏竖屏均可用。

<!-- 自定义预设档位（顺序即宫格展示顺序） -->
<ali-player-view :speedPresets="[2.0, 1.5, 1.0, 0.5]" @ratechange="" />

// 也可不走弹层，直接设速 / 主动唤起弹层
this.$refs.player.setSpeed(1.5)
this.$refs.player.showSpeedSelectSheet()

(e) {
  const { rate } = e.detail || e   // 所有设速路径（弹层/滑杆/API）均派发
}

定时关闭

内置“定时关闭”弹层：不开启 / 播完当前 / 倒计时档位（默认 30/60 分钟，可配置）。 到点自动暂停播放并派发 sleeptimerfinish。

<!-- 自定义倒计时档位（“不开启/播完当前”固定项不受影响） -->
<ali-player-view :sleepTimerPresets="[15, 30, 60, 90]"
  @sleeptimerchange="Change" @sleeptimerfinish="Finish" />

// 不走弹层，直接设置 / 主动唤起弹层
this.$refs.player.setSleepTimer('countdown', 30)  // 30 分钟后停止
this.$refs.player.setSleepTimer('current', 0)     // 播完当前停止
this.$refs.player.setSleepTimer('off', 0)         // 取消
this.$refs.player.showSleepTimerSheet()

视频下载

抽屉“下载”条目点击后原生自动处理，无需 JS 层参与；也可通过组件方法在自定义 UI 中主动发起。

<ali-player-view ref="player"
  @downloadprogress="" @downloadcomplete="onComplete" @downloaderror="onError" />

// 加密视频（vid 源）：先配置密钥文件，全局一次即可
this.$refs.player.setSecureDownloadKeyFile('/data/user/0/xxx/files/encryptedApp.dat')

this.$refs.player.startDownload()                  // 开始下载当前视频
this.$refs.player.stopDownload()                   // 取消下载
const busy = this.$refs.player.isDownloading()     // 查询下载中

(e)  { const { percent } = e.detail || e }        // 0-100
onComplete(e)  { const { filePath } = e.detail || e }       // 本地绝对路径
onError(e)     { const { code, message } = e.detail || e }  // 字符串错误码

限制：同一播放器同时仅支持一个下载任务；HLS 加密流（EXT-X-KEY）不支持下载； 直播流（RTMP/RTS）不支持下载。不支持时原生轻提示并派发 downloaderror。

截图

<ali-player-view ref="player" @snapshot="onSnapshot" />

<script>
methods: {
  async takeSnapshot() {
    // 触发截图，结果异步通过 snapshot 事件返回
    this.$refs.player.snapshot()
  },
  onSnapshot(e) {
    console.log('截图路径:', e.path)
    uni.saveImageToPhotosAlbum({
      filePath: e.path,
      success: () => uni.showToast({ title: '截图已保存' })
    })
  }
}
</script>

直播播放

<template>
  <!-- #ifdef APP-PLUS -->
  <ali-player-view
    ref="player"
    src="rtmp://live.example.com/live/stream"
    :autoplay="true"
    @ready="onReady"
    @error="onError"
  />
  <!-- #endif -->
</template>

支持格式：RTMP、HLS (M3U8)、FLV、RTS 超低延时直播。

切换播放源

// 方式1：通过 setUrl 方法
this.$refs.player.setUrl('https://example.com/new-video.mp4')
this.$refs.player.prepare()

// 方式2：通过修改 src prop（响应式）
this.videoUrl = 'https://example.com/new-video.mp4'

获取播放信息

// 获取当前播放位置（毫秒）
this.$refs.player.getCurrentPosition((pos) => {
  console.log('当前位置:', pos, 'ms')
})

// 获取视频总时长（毫秒）
this.$refs.player.getDuration((duration) => {
  console.log('总时长:', duration, 'ms')
})

License 配置（SDK 7.0.0+）

⚠️ 自 7.0.0 版本起，阿里云播放器 SDK 在 Android 与 iOS 两端均需要有效的 License 才能使用，否则会报 LICENSE_ERROR_INVALID 错误；且 7.6.0+ 版本必须同时配置 License 证书文件（仅配 LicenseKey 在弱网/无网环境下会鉴权失败）。

鉴权要素与双端存放规划

插件内的完整目录布局：

uni_modules/lord-aliyun-player/utssdk/
├── app-android/
│   ├── AndroidManifest.xml          ← licensekey + licensefile 两条 meta-data
│   └── assets/
│       └── cert/
│           └── AliVideoCert.crt     ← Android 证书（云打包合并到 APK assets/cert/）
└── app-ios/
    ├── Info.plist                   ← AlivcLicenseKey + AlivcLicenseFile（云打包合并进原生工程 Info.plist）
    └── Resources/
        └── AliVideoCert.crt         ← iOS 证书（云打包合并进 App main bundle）

设计说明（企业级规范）：

• 证书采用固定文件名 AliVideoCert.crt（而非阿里云下载时带日期戳的原始文件名），证书续期/权益变更时只需替换两端 .crt 文件本身，无需改动任何配置。
• Android 证书独立存放在 assets/cert/ 子目录，与控制栏图标（image/）、字体（fonts/）隔离，路径写法对齐阿里云官方文档示例（assets/cert/xxx.crt）。
• 同一张 License 同时绑定 Android PackageName 与 iOS BundleId，双端共用同一个 LicenseKey 与同一份证书文件。

1. 申请 License

前往阿里云控制台申请：接入 License

申请时需要填写 App 的 Android PackageName 和 iOS BundleId（即 uni-app 打包时使用的包名），License 与应用标识强绑定。申请成功后可获得 LicenseKey 与 *License 证书文件（AliVideoCert-.crt）**。

2. Android 端配置

① 放置证书：将下载的 .crt 重命名为 AliVideoCert.crt，放入：

utssdk/app-android/assets/cert/AliVideoCert.crt

HBuilderX 打包时会自动将 UTS 插件 utssdk/app-android/assets/ 下的文件（含子目录）合并到 APK 的 assets/ 目录。

② 配置 meta-data：插件的 utssdk/app-android/AndroidManifest.xml 中已预置（<meta-data> 必须位于 <application> 节点内）：

<meta-data
    android:name="com.aliyun.alivc_license.licensekey"
    android:value="你的LicenseKey" />
<meta-data
    android:name="com.aliyun.alivc_license.licensefile"
    android:value="assets/cert/AliVideoCert.crt" />

3. iOS 端配置

① 放置证书：将同一张证书（重命名为 AliVideoCert.crt）放入：

utssdk/app-ios/Resources/AliVideoCert.crt

按 UTS 插件规范，云打包时 Resources/ 下的文件会自动添加到应用 main bundle，无需手动操作 Xcode 工程。

② 配置 Info.plist：插件的 utssdk/app-ios/Info.plist 中已预置（云打包时自动合并进原生工程 Info.plist）：

<key>AlivcLicenseKey</key>
<string>你的LicenseKey</string>
<key>AlivcLicenseFile</key>
<string>AliVideoCert.crt</string>

AlivcLicenseFile 填相对 main bundle 的路径；证书在 Resources/ 根目录时直接填文件名即可。

4. 证书续期 / 更换 License

修改后需重新制作自定义基座才能生效。

5. 验证与排查

• 鉴权失败时播放器会派发 @error 事件（License 相关错误码 LICENSE_ERROR_*），可据此快速定位。
• Android 检查要点：<meta-data> 是否在 <application> 内、LicenseKey 与控制台一致、打包包名与申请时填写的 PackageName 一致。
• iOS 检查要点：AlivcLicenseKey 与控制台一致、BundleId 与申请时填写一致、证书已随包进入 main bundle。
• 更多排查见：License 相关常见问题。

常见问题

Q1：为什么在 HBuilderX 标准基座上运行没有效果 / 报「插件不存在」？
原生插件必须使用自定义调试基座或正式包，请在 HBuilderX 中选择「运行 → 运行到手机或模拟器 → 制作自定义调试基座」完成打包后再运行。

Q2：Android 模拟器无法播放视频？
阿里云播放器 Android SDK 不支持模拟器，请使用真机调试。

Q3：iOS 播放 HTTP 地址报网络错误？
在 manifest.json → App 原生配置 → iOS Info.plist 配置 中添加 NSAllowsArbitraryLoads: true，或将视频地址改为 HTTPS。

Q4：切换播放源（换 URL）不生效？
需先调用 stop()，再通过 setUrl() 设置新地址并 prepare()（setAutoPlay(true) 可在换源后自动起播）：

this.$refs.player.stop()
this.$refs.player.setUrl('https://new-url.mp4')
this.$refs.player.setAutoPlay(true)  // 可选：换源后自动起播
this.$refs.player.prepare()

Q5：如何监听播放进度？
通过 @timeupdate 事件，e.currentTime 即为当前播放位置（毫秒）：

onTimeUpdate(e) {
  console.log('播放进度:', e.currentTime, '/', e.duration)
}

Q6：VidAuth 播放凭证过期怎么处理？
监听 @error 事件，判断错误码为凭证过期后，重新向服务端换取 PlayAuth，再更新 playAuth prop 或调用 prepare()。

Q7：PiP 进入后视频停止了怎么办？
检查 AndroidManifest 的主 Activity 是否有 android:supportsPictureInPicture="true" 和 android:configChanges 属性。

Q8：熄屏后音频也停了？
调用 enableKeepPlayingOnScreenOff() 后，播放器会自动申请 WakeLock 保活。如仍不生效，检查是否在播放完成/出错后未重新启用。

Q9：报 LICENSE_ERROR_INVALID 或提示 License 鉴权失败？
按 License 配置 逐项检查：两端 LicenseKey 是否与控制台一致、打包包名（PackageName/BundleId）是否与申请 License 时填写的一致、证书文件是否已按规划路径放置（Android assets/cert/AliVideoCert.crt、iOS Resources/AliVideoCert.crt）、证书是否已过期。注意：修改 License 配置后必须重新制作自定义基座。

更新日志

完整版本更新记录请查看 changelog.md。

版本：v5.1.2 | 基于阿里云 ApsaraVideo Player SDK（Android / iOS）| 最低 HBuilderX：3.99