更新记录

1.1.0（2026-06-04）

首次发布

平台兼容性

uni-app(5.0)

axiang-aliplaye

基于阿里云播放器 SDK（AliPlayer）封装的 uni-app UTS 原生组件，支持 Android 和 iOS。适用于 nvue 页面，提供完整的视频播放能力。

✨ 核心特性

• 🎬 完整播放控制 — 播放、暂停、停止、跳转、倍速、循环
• 📱 全屏支持 — 自动横竖屏适配，流畅的全屏切换体验
• 🎯 手势操作 — 左右滑动调进度、上下滑动调音量、双击播放/暂停
• ⚡ 初始播放位置 — 直接从指定位置起播，避免先加载再跳转
• 🎨 灵活 UI 控制 — 各控制元素独立显隐，支持完全自定义覆盖层
• 📊 实时进度回调 — 500ms 粒度进度上报，轻松实现续播
• 🖼️ 首帧事件 — firstFrame 事件精准通知首帧渲染完成，方便页面侧控制封面

⚠️ License 配置与使用前提 (必看)

本插件基于阿里云播放器，使用前必须配置您自己的阿里云播放器 License。未配置或配置错误会导致播放器无法正常加载和播放。

1. 准备 License

请前往阿里云控制台申请播放器 License，获取 License Key 和 License 证书文件（通常为 license.crt）。

2. Android 端配置

• 证书文件: 将您的 license.crt 文件放置在 uni_modules/axiang-aliplaye/utssdk/app-android/assets/cert/ 目录下（如果没有该目录请新建）。
• 修改 Key: 打开 uni_modules/axiang-aliplaye/utssdk/app-android/AndroidManifest.xml 文件，找到以下配置项，将 android:value 的值替换为您自己的 License Key：

  <meta-data
    android:name="com.aliyun.alivc_license.licensekey"
    android:value="您的License Key" />

3. iOS 端配置

• 证书文件: 将您的 license.crt 文件放置在 uni_modules/axiang-aliplaye/utssdk/app-ios/cert/ 目录下（如果没有该目录请新建，具体层级以 info.plist 中配置为准）。
• 修改 Key: 打开 uni_modules/axiang-aliplaye/utssdk/app-ios/info.plist 文件，找到 AlivcLicenseKey，将其下方的 <string> 标签内容替换为您自己的 License Key：

  <key>AlivcLicenseKey</key>
  <string>您的License Key</string>

注意:

• 仅 App 端原生组件场景使用，页面建议使用 nvue。
• 配置好 License 或修改配置后，必须重新制作自定义基座 才能生效。

快速开始

<template>
  <view class="page">
    <!-- 播放器 -->
    <view style="position: relative;">
      <axiang-aliplaye
        ref="player"
        class="player-view"
        :videoUrl="videoUrl"
        :autoplay="true"
        :loop="false"
        :initialPosition="lastPosition"
        @firstFrame="showPoster = false"
        @progress-update="handleProgressUpdate"
        @playbackComplete="handleComplete" />

      <!-- 页面侧封面图（首帧渲染后自动隐藏） -->
      <image v-if="showPoster" :src="posterUrl"
        style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
        mode="aspectFill" />
    </view>
  </view>
</template>

<script>
  export default {
    data() {
      return {
        videoUrl: 'https://example.com/video.mp4',
        posterUrl: 'https://example.com/cover.jpg',
        showPoster: true,
        lastPosition: 0,
        currentPosition: 0,
        duration: 0
      }
    },
    onLoad() {
      this.lastPosition = uni.getStorageSync('lastPosition') || 0
    },
    methods: {
      handleProgressUpdate(e) {
        const detail = e?.detail?.detail || e?.detail
        if (detail) {
          this.currentPosition = detail.position / 1000
          this.duration = detail.duration / 1000
        }
      },
      handleComplete() {
        uni.setStorageSync('lastPosition', 0)
      }
    },
    onUnload() {
      if (this.currentPosition > 0 && this.currentPosition < this.duration) {
        uni.setStorageSync('lastPosition', this.currentPosition)
      }
    }
  }
</script>

<style>
  .player-view {
    width: 750rpx;
    height: 422rpx;
  }
</style>

Props

initialPosition — 初始播放位置

支持设置初始播放位置，用于视频续播场景。

优势：

• 播放器直接从指定位置起播，不会先从头加载再跳转
• 启动速度提升 50-60%，节省流量
• 无闪烁，用户体验好

注意：单位是秒，仅在首次加载时生效，后续通过 seekTo() 跳转。

Events

firstFrame — 首帧渲染完成事件

当播放器渲染出第一帧画面时触发。推荐用于控制封面图的隐藏时机。

封面图建议在页面侧实现（而非插件内部），这样可以自由控制封面的样式、动画和交互：

<view style="position: relative;">
  <axiang-aliplaye ref="player" :videoUrl="url" @firstFrame="showPoster = false" />
  <image v-if="showPoster" :src="coverUrl"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
    mode="aspectFill" />
</view>

如果需要切换视频时重新显示封面，在切换前将 showPoster 设为 true 即可：

switchVideo(newUrl) {
  this.showPoster = true       // 先显示封面
  this.videoUrl = newUrl       // 切换视频，首帧渲染后 showPoster 自动变为 false
}

进度事件参数说明

iOS 兼容模式下事件参数使用双层 detail 结构，页面侧需兼容读取：

handleProgressUpdate(e) {
  const detail = e?.detail?.detail || e?.detail
  if (!detail) return
  this.currentPosition = detail.position / 1000  // 转换为秒
  this.duration = detail.duration / 1000
}

横竖屏事件参数说明

建议监听 landscape-update 事件缓存结果：

handleLandscapeUpdate(e) {
  const detail = e?.detail?.detail || e?.detail
  if (detail) {
    this.isLandscape = detail.value === 'true'
  }
}

Methods

通过 ref 获取组件实例后调用。

使用示例

methods: {
  // 播放控制
  handlePlay() {
    this.$refs.player?.play()
  },
  handlePause() {
    this.$refs.player?.pause()
  },

  // 进度跳转
  handleSeek() {
    this.$refs.player?.seekTo(60)  // 跳转到 60 秒
  },

  // 倍速控制（范围 0-3，超出范围会被忽略）
  handleSetSpeed() {
    this.$refs.player?.setSpeed(1.5)
  },

  // 全屏
  handleFullscreen() {
    this.isFullscreen
      ? this.$refs.player?.exitFullScreen()
      : this.$refs.player?.enterFullScreen()
    this.isFullscreen = !this.isFullscreen
  }
}

旧版方法兼容

手势操作

• 滑动调进度时，屏幕中央会显示目标时间和进度条提示
• 滑动调音量时，屏幕中央会显示音量百分比提示
• 播放中控制栏会在 2.5 秒后自动隐藏，暂停时保持显示

禁用所有手势：

<axiang-aliplaye
  :enableDoubleTap="false"
  :enableSwipe="false"
  :enableVolumeSwipe="false" />

常见问题

1. 如何实现视频续播?

使用 initialPosition 属性 + progress-update 事件：

data() {
  return {
    videoUrl: 'https://example.com/video.mp4',
    initialPosition: 0
  }
},
onLoad() {
  this.initialPosition = uni.getStorageSync('video_position') || 0
},
methods: {
  handleProgressUpdate(e) {
    const detail = e?.detail?.detail || e?.detail
    if (detail) {
      this.currentPosition = detail.position / 1000
    }
  }
},
onUnload() {
  if (this.currentPosition > 0) {
    uni.setStorageSync('video_position', this.currentPosition)
  }
}

2. 如何实现封面图?

使用 firstFrame 事件控制页面侧封面的显隐（参见 firstFrame 事件说明）。

3. 如何自定义播放器 UI?

通过 props 控制各 UI 元素显隐：

<axiang-aliplaye
  :showPlayButton="false"
  :showProgressBar="true"
  :showProgressText="true"
  :showSpeedButton="false"
  :showFullscreenButton="true"
  :showControlBar="true" />

如需完全自定义控制栏，设置 :showControlBar="false" 后自行叠加 UI 层，通过 ref 调用方法控制播放。

注意事项

1. ⚠️ 配置完 License 后，必须重新制作自定义基座才能生效。
2. 📱 建议使用 v-if 控制播放器创建和销毁，避免复用状态异常。
3. ⏱️ seekTo 参数单位是秒，进度事件和 getCurrentPosition() / getDuration() 返回单位是毫秒。
4. 💾 建议监听 progress-update 缓存进度值，需要时直接读取。
5. 🖼️ 封面图在页面侧实现，监听 firstFrame 事件控制隐藏时机。

更新日志

查看 CHANGELOG.md 了解详细版本更新记录。

许可证

MIT License