更新记录

1.0.2（2026-07-25）

fix bug

1.0.1（2026-07-25）

release

1.0.0（2026-07-25）

release

平台兼容性

uni-app(5.12)

uni-app x(5.12)

ai-player

ai-player 是一个适用于 uni-app x 的跨平台视频播放器 UTS 组件，支持 Android、iOS 和 HarmonyOS。组件基于 uni-app x 原生 <video> 能力封装，提供小窗播放、全屏播放、播放/暂停、进度拖动、15 秒快进快退、清晰度切换、倍速切换、全屏锁定、水印和标题展示等常用播放器能力。

插件特点

• 支持 uni-app x App 端：Android、iOS、HarmonyOS
• 使用 UTS 组件方式接入，无需额外集成 Android AAR 或 iOS Framework
• 支持单视频地址和多清晰度视频源
• 支持小窗和横屏全屏播放
• 支持自定义标题、水印、进度条颜色、封面图
• 支持播放状态、进度、错误、清晰度、倍速、锁定、全屏变化等事件
• 支持通过组件实例方法或命令属性控制播放器

平台要求

• HBuilderX 4.61 或更高版本
• uni-app x 项目
• Android 5.0 或更高版本
• iOS 12.0 或更高版本
• HarmonyOS NEXT API 12 或更高版本

安装说明

将插件目录放入项目的 uni_modules 目录：

uni_modules/ai-player

在页面中可直接使用 ai-player 组件。若页面没有自动识别组件，可以手动引入组件文件。

基础用法

<template>
  <view class="page">
    <ai-player
      ref="playerRef"
      class="player"
      src="https://example.com/video.mp4"
      title="视频标题"
      progress-color="#ff7817"
      @ready="onReady"
      @play="onPlay"
      @pause="onPause"
      @timeupdate=""
      @error="onError"
    />
  </view>
</template>

<script setup lang="uts">
import AiPlayer from '@/uni_modules/ai-player/utssdk/index.vue'
import {
  PlayerTimeUpdateDetail,
  PlayerErrorDetail
} from '@/uni_modules/ai-player'

type AiPlayerExpose = {
  play: () => void
  pause: () => void
}

const playerRef = ref<AiPlayerExpose | null>(null)

function onReady() {
  console.log('播放器已就绪')
}

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

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

function (detail: PlayerTimeUpdateDetail) {
  console.log('当前播放时间：' + detail.time.toString())
}

function onError(detail: PlayerErrorDetail) {
  console.log('播放错误：' + detail.message)
}
</script>

<style>
.page {
  flex: 1;
}

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

多清晰度用法

<ai-player
  ref="playerRef"
  class="player"
  cif="https://example.com/video-cif.mp4"
  hd="https://example.com/video-hd.mp4"
  sd="https://example.com/video-sd.mp4"
  initial-quality="高清"
  title="视频标题"
  watermark-logo="/static/player/sample-watermark.png"
  progress-color="#ff7817"
  @qualitychange="onQualityChange"
  @ratechange=""
/>

内置清晰度名称：

组件属性

外部命令

通过 command 和 commandVersion 可以在不使用组件实例的情况下控制播放器。每次需要执行命令时，更新 command 并让 commandVersion 递增。

事件说明

实例方法

type AiPlayerExpose = {
  initPlayer: (options: PlayerOptions) => void
  play: () => void
  pause: () => void
  stop: () => void
  seek: (seconds: number) => void
  seekBackward: (seconds?: number) => void
  seekForward: (seconds?: number) => void
  setPlaybackRate: (rate: number) => void
  switchQuality: (label: string) => void
  requestFullScreen: (direction?: number) => void
  exitFullScreen: () => void
  setLocked: (locked: boolean) => void
  toggleLock: () => void
  backPressed: () => void
}

常用调用示例：

playerRef.value?.play()
playerRef.value?.pause()
playerRef.value?.seek(30)
playerRef.value?.seekBackward(15)
playerRef.value?.seekForward(15)
playerRef.value?.setPlaybackRate(1.5)
playerRef.value?.switchQuality('超清')
playerRef.value?.requestFullScreen(90)
playerRef.value?.exitFullScreen()

initPlayer 配置

除了通过组件属性传入视频源，也可以调用 initPlayer(options) 初始化播放器。

playerRef.value?.initPlayer({
  title: '视频标题',
  logoUrlString: '/static/player/sample-watermark.png',
  progressColor: '#ff7817',
  autoplay: true,
  initialQuality: '高清',
  initialRate: 1.0,
  isHiddenRateBtn: false,
  isHiddenRefinitionBtn: false,
  sources: [
    { label: '普通', url: 'https://example.com/video-cif.mp4' },
    { label: '高清', url: 'https://example.com/video-hd.mp4' },
    { label: '超清', url: 'https://example.com/video-sd.mp4' }
  ]
} as PlayerOptions)

sources 为推荐的视频源格式。如果需要兼容旧版参数，也可以使用：

playerRef.value?.initPlayer({
  video: {
    cif: 'https://example.com/video-cif.mp4',
    hd: 'https://example.com/video-hd.mp4',
    sd: 'https://example.com/video-sd.mp4'
  }
} as PlayerOptions)

注意事项

• 插件面向 uni-app x App 端，不支持 Web、小程序和普通 uni-app Vue2 页面。
• iOS 和 HarmonyOS 构建时建议项目路径使用英文目录，避免部分构建工具对中文路径兼容不稳定。
• 清晰度切换会尽量保持当前播放进度和倍速。
• 全屏锁定后会隐藏其他控制按钮，仅保留解锁入口。
• 视频地址需要确保 App 端可访问；如使用 HTTP 地址，请确认项目网络安全配置允许访问。

类型说明

插件导出了常用 UTS 类型，可按需从 @/uni_modules/ai-player 引入：

import {
  PlayerSource,
  PlayerOptions,
  PlayerTimeUpdateDetail,
  PlayerErrorDetail,
  PlayerQualityChangeDetail,
  PlayerRateChangeDetail,
  PlayerSeekChangeDetail,
  PlayerLockChangeDetail
} from '@/uni_modules/ai-player'