更新记录

1.0.0（2026-10-22）

• 首次发布：uni-app x 标准模式 阿里云播放器 AliPlayerKit

平台兼容性

uni-app x(4.27)

其他

zy-aliplayer-x

阿里云播放器（AliPlayer SDK 7.18.0）uni-app x 组件，仅支持 App-Android 平台。

组件内置原生播放内核 + uvue 简易控制条（播放/暂停、进度条、时间、倍速、静音、循环、重播、全屏、加载提示），支持直连 URL、vid + playAuth（VidAuth）、vid + STS 三类视频源。全屏时锁定横屏，退出全屏恢复原方向。

环境要求

• HBuilderX ^4.31、uni-app x ^4.27
• Android 最低支持 API 23（minSdkVersion 原生依赖为 21）
• 必须使用自定义基座运行（插件含原生依赖）
• 不支持 Android 模拟器（播放器 SDK 官方限制）
• 播放器 SDK 7.x 为收费版本（2025-02-14 起 7.0.0+ 收费），需在阿里云视频点播控制台开通并获取 License

宿主工程集成（必做）

1. License 配置

前置条件：已在点播控制台申请 License，拿到 License Key 和 License 文件（*.crt）。播放器 SDK 7.6.0 及以上必须配置 License 文件，否则鉴权失败。

1. 将证书文件放到插件目录 uni_modules/zy-aliplayer-x/utssdk/app-android/assets/cert/release.crt
2. 编辑插件清单 uni_modules/zy-aliplayer-x/utssdk/app-android/AndroidManifest.xml，在 <application> 下已内置以下配置，只需把 TODO 替换为你的 License Key：

<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/release.crt" />
</application>

说明：

• <meta-data> 必须位于 <application> 节点下，name 必须完全一致；打包时插件清单会合并进宿主 App 清单
• licensefile 的值是相对 assets 目录的路径；插件 utssdk/app-android/assets 会合并进 APK 的 assets
• 国际站（全球，不含中国内地及港澳台）用户启用清单中已注释的 SEA 配置：licensekey_SEA、licensefile_SEA、com.aliyun.alivc_env=SEA，证书放同一 cert 目录下的 assets/cert/SEARelease.crt
• License Key 与包名一一绑定，换包名需重新申请 License
• 注意：uni_modules 更新会覆盖插件清单和插件 assets 目录，更新后需重新放入证书、填写 License Key
• 插件清单与 assets 资源需提交云端打包（或打自定义基座）后才生效

2. 混淆规则

若宿主开启混淆，需在 proguard-rules.pro 中保留：

-keep class com.aliyun.** { *; }
-keep class com.alivc.** { *; }
-keep class com.cicada.** { *; }
-keep class com.media.** { *; }
-keep class com.device.** { *; }

3. 全屏铺满说明

全屏由三部分组成，三者齐备才能铺满整个屏幕：

1. 组件覆盖层：CSS position: fixed 铺满页面容器
2. 横屏：原生 Activity.setRequestedOrientation 锁定横屏（进入前记录方向，退出恢复；组件销毁自动恢复），不会重建 Activity
3. 系统栏隐藏：进入全屏时组件自动调用 $setPageStyle({ hideStatusBar: true, hideBottomNavigationIndicator: true }) 隐藏状态栏与底部导航条，退出时恢复（HBuilderX 4.31+，仅 Android）

原生标题栏无法动态隐藏（Android 不支持 $setPageStyle 改 navigationStyle），因此要让播放器真正铺满全屏，播放页需在 pages.json 配置：

{ "path": "pages/xxx/xxx", "style": { "navigationStyle": "custom" } }

然后在页面内自行绘制标题栏（本插件演示页即为该做法，含 var(--status-bar-height) 状态栏占位与返回按钮）。

快速开始

<template>
  <view class="wrap">
    <zy-aliplayer-x
      ref="playerRef"
      class="player"
      :src="src"
      :autoPlay="true"
      @prepared="onprepared"
      @timeupdate=""
      @error="onerror" />
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const playerRef = ref<any>(null)
const src = ref<string>("https://example.com/video.mp4")

function onprepared(duration: number) {
  console.log("prepared", duration)
}
function (currentTime: number, duration: number, buffered: number) {}
function onerror(code: number, message: string) {
  console.log("error", code, message)
}
</script>

<style>
.wrap { width: 100%; height: 240px; }
.player { width: 100%; height: 100%; }
</style>

Props

Events

方法（通过模板 ref 调用）

play pause toggle stop replay seek(position, accurate?) setSpeed setVolume setLoop setMute setScaleMode(mode) setMirrorMode(mode) setRotateMode(deg) selectTrack(index) getTrackCount() getTrackInfo(index) getCurrentTrackIndex() snapshot() setDebugLog(enabled) enterFullscreen() exitFullscreen() toggleFullscreen() isFullscreen() handleBackPressed() getState() getDuration() getCurrentPosition() getBufferedPosition() getCurrentSpeed() getVideoSize() setDataSource(options)

• setScaleMode：0 等比完整显示 / 1 等比填充裁剪 / 2 拉伸填充
• setMirrorMode：0 无 / 1 水平 / 2 垂直
• setRotateMode：0 / 90 / 180 / 270
• seek(position, accurate)：position 毫秒，accurate 是否精确定位
• handleBackPressed()：全屏时返回 true 并退出全屏，页面可绑定返回键调用

setDataSource 切换视频源

playerRef.value?.setDataSource({ src: "https://example.com/2.mp4", autoPlay: true })
playerRef.value?.setDataSource({ vid: "xxx", playAuth: "yyy", region: "cn-shanghai", autoPlay: true })

限制说明

• 仅 App-Android；Web/小程序/其他端不支持（页面可用 条件编译 #ifdef APP-ANDROID 包裹）
• 全屏 = CSS fixed 覆盖层 + 原生锁横屏 + $setPageStyle 隐藏状态栏/底部导航条；若页面保留原生标题栏，则标题栏区域无法覆盖（需 navigationStyle: "custom"）
• 控制条为组件内置简易实现，不含清晰度/音轨选择、上下集等高级 UI；相关能力可通过方法 + tracklistchange 事件自行扩展

错误码（插件级）

9030001 播放器初始化失败 / 9030002 视频源无效 / 9030003 播放失败 / 9030004 暂停失败 / 9030005 进度跳转失败 / 9030006 截图失败 / 9030007 轨道切换失败 / 9030008 播放器已销毁 / 9030009 入参无效 / 9030010 当前平台不支持