thunder-hw-player-ui

Thunder Player SDK 的 Vue 3 UI 层 - 可复用的视频播放器组件。

特性

• 🎬 完整的视频播放器 UI 及控制组件
• 📊 带拖拽和预览功能的进度条
• 🔄 播放控制（播放、暂停、全屏）
• 🔁 循环模式（顺序、单曲、列表循环）
• 📝 播放列表管理（添加、删除、排序）
• ⚡ 播放速度控制（0.5x - 3x）
• 🔊 音量控制，支持百分比显示和鼠标滚轮调节
• 🖼️ 画中画(PiP)支持
• 📸 截屏功能，支持复制到剪贴板
• ⌨️ 完整的键盘快捷键支持
• 🎨 可自定义样式
• 📱 响应式设计

安装

npm install thunder-hw-player-ui thunder-hw-player

快速开始

基础用法

<template>
  <ThunderPlayerUILibmedia
    :config="playerConfig"
    @ready="onReady"
    @playing="onPlaying"
    @paused="onPaused"
    @ended="onEnded"
    @error="onError"
    ref="playerRef"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ThunderPlayerUILibmedia } from 'thunder-hw-player-ui'
import 'thunder-hw-player-ui/style.css'

const playerConfig = {
  appid: 'your-app-id',
  sk: 'your-sk',
  authUrl: 'https://your-auth-server.com/auth',
  enableDebug: true
}

const playerRef = ref(null)

const onReady = () => {
  console.log('播放器就绪')
  // 播放视频
  playerRef.value?.playUrl('https://example.com/video.ts')
}

const onPlaying = () => {
  console.log('开始播放')
}

const onPaused = () => {
  console.log('已暂停')
}

const onEnded = () => {
  console.log('播放结束')
}

const onError = (error: string) => {
  console.error('播放器错误:', error)
}
</script>

带播放列表

<template>
  <div>
    <!-- 模式切换 -->
    <div class="mode-toggle">
      <button @click="setMode('single')">单曲模式</button>
      <button @click="setMode('playlist')">列表模式</button>
    </div>

    <!-- 播放器 -->
    <ThunderPlayerUILibmedia
      :config="playerConfig"
      @ready="onReady"
      @ended="onEnded"
      ref="playerRef"
    />

    <!-- 播放列表控制（列表模式下） -->
    <div v-if="mode === 'playlist'" class="playlist-controls">
      <input v-model="newVideoUrl" placeholder="输入视频 URL" />
      <button @click="addVideo">添加到列表</button>

      <ul class="playlist">
        <li v-for="(video, index) in playlist" :key="index">
          <span @click="selectVideo(index)">{{ video.name }}</span>
          <button @click="removeVideo(index)">删除</button>
        </li>
      </ul>

      <div class="playback-controls">
        <button @click="playPrevious">上一首</button>
        <button @click="playNext">下一首</button>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ThunderPlayerUILibmedia } from 'thunder-hw-player-ui'
import 'thunder-hw-player-ui/style.css'

const mode = ref<'single' | 'playlist'>('single')
const playlist = ref<Array<{ url: string; name: string }>>([])
const currentIndex = ref(-1)
const newVideoUrl = ref('')
const playerRef = ref(null)

const playerConfig = {
  appid: 'your-app-id',
  sk: 'your-sk',
  authUrl: 'https://your-auth-server.com/auth'
}

const setMode = (newMode: 'single' | 'playlist') => {
  mode.value = newMode
  currentIndex.value = -1
}

const addVideo = () => {
  if (newVideoUrl.value) {
    playlist.value.push({
      url: newVideoUrl.value,
      name: `视频 ${playlist.value.length + 1}`
    })
    newVideoUrl.value = ''
  }
}

const selectVideo = (index: number) => {
  currentIndex.value = index
  playerRef.value?.playUrl(playlist.value[index].url)
}

const removeVideo = (index: number) => {
  playlist.value.splice(index, 1)
  if (currentIndex.value === index) {
    currentIndex.value = -1
  }
}

const playPrevious = () => {
  if (currentIndex.value > 0) {
    selectVideo(currentIndex.value - 1)
  }
}

const playNext = () => {
  if (currentIndex.value < playlist.value.length - 1) {
    selectVideo(currentIndex.value + 1)
  }
}

const onEnded = () => {
  // 列表模式下自动播放下一个
  if (mode.value === 'playlist') {
    playNext()
  }
}
</script>

组件

ThunderPlayerUILibmedia

功能完整的播放器组件，包含所有控制和功能。

Props:

| 属性 | 类型 | 默认值 | 说明 | |------|------|---------|-------------| | config | PlayerConfig | 必需 | SDK 配置（appid, sk, authUrl） | | canvasWidth | number | 1280 | Canvas 宽度 | | canvasHeight | number | 720 | Canvas 高度 |

Events:

| 事件 | 参数 | 说明 | |-------|---------|-------------| | ready | - | 播放器就绪 | | playing | - | 开始播放 | | paused | - | 已暂停 | | ended | - | 播放结束（用于播放列表自动播放） | | error | string | 发生错误 | | timeupdate | number | 当前时间（毫秒） |

暴露的方法:

| 方法 | 参数 | 说明 | |--------|------------|-------------| | playUrl | url: string | 播放视频 URL | | play | - | 恢复播放 | | pause | - | 暂停播放 | | stop | - | 停止播放 | | seekTo | time: number | 跳转到时间（毫秒） | | setPlaybackSpeed | speed: number | 设置播放速度 | | setVolume | volume: number | 设置音量（0-100） | | takeScreenshot | - | 截屏并复制到剪贴板 | | togglePiP | - | 切换画中画模式 | | toggleFullscreen | - | 切换全屏模式 |

键盘快捷键

| 按键 | 功能 | |-----|------| | 空格 | 播放/暂停 | | ← | 后退 5 秒 | | → | 前进 5 秒 | | ↑ | 音量增加 | | ↓ | 音量减少 | | F | 切换全屏 | | P | 切换画中画 | | M | 静音/取消静音 | | S | 截屏 | | L | 切换循环模式 | | I | 显示媒体信息 | | H 或 ? | 显示快捷键帮助 |

循环模式

播放器支持三种循环模式：

1. 顺序播放: 播放一次后停止
2. 单曲循环: 重复播放当前视频
3. 列表循环: 重复播放整个播放列表

点击循环按钮或按 L 键可切换循环模式。

功能说明

播放列表管理

// 添加视频到播放列表
playlist.value.push({ url: 'video.ts', name: '视频 1' })

// 播放指定视频
playerRef.value?.playUrl(playlist.value[index].url)

// 播放结束时自动播放下一个
const onEnded = () => {
  if (currentIndex.value < playlist.value.length - 1) {
    currentIndex.value++
    playerRef.value?.playUrl(playlist.value[currentIndex.value].url)
  }
}

截屏

// 截屏并复制到剪贴板
playerRef.value?.takeScreenshot()

或在播放器获得焦点时按 S 键。

画中画

// 切换画中画模式
playerRef.value?.togglePiP()

或在播放器获得焦点时按 P 键。

音量控制

• 点击并拖动音量滑块
• 在播放器区域使用鼠标滚轮
• 按 ↑/↓ 箭头键
• 显示百分比提示

播放速度

可选速度：0.5x、0.75x、1x、1.25x、1.5x、2x、3x

点击速度按钮循环切换速度。

样式自定义

所有组件使用带 tp- 前缀的作用域 CSS。你可以通过覆盖这些类来自定义样式：

.tp-player-container {
  /* 自定义播放器容器样式 */
  background: #000;
}

.tp-progress-fill {
  /* 自定义进度条填充 */
  background: linear-gradient(90deg, #4CAF50 0%, #8BC34A 100%);
}

.tp-control-btn {
  /* 自定义控制按钮样式 */
  color: #fff;
  background: rgba(255, 255, 255, 0.1);
}

.tp-control-btn:hover {
  background: rgba(255, 255, 255, 0.2);
}

配置

PlayerConfig

interface PlayerConfig {
  appid: string          // 你的应用 ID
  sk: string            // 你的密钥
  authUrl?: string      // 认证服务器 URL（可选）
  enableDebug?: boolean // 启用调试日志（默认：false）
}

浏览器支持

• Chrome（最近 2 个版本）
• Firefox（最近 2 个版本）
• Safari（最近 2 个版本）
• Edge（最近 2 个版本）

要求：

• WebAssembly 支持
• Canvas API
• Web Audio API
• Picture-in-Picture API（画中画功能）
• Clipboard API（截屏功能）

故障排除

播放器无法初始化

确保你的配置中包含有效的 appid、sk 和 authUrl。

视频无法播放

1. 检查视频 URL 是否可访问
2. 验证 CORS 头设置是否正确
3. 检查浏览器控制台是否有错误
4. 在配置中启用 enableDebug: true 查看详细日志

截屏功能不工作

Clipboard API 需要 HTTPS 或 localhost。确保生产环境的应用通过 HTTPS 提供服务。

画中画功能不工作

Picture-in-Picture 需要用户手势（点击）才能激活。某些浏览器可能不支持 Canvas 元素的画中画。

卓版本说明

v1.1.2 - 包大小优化

• 包大小从 45MB 减少到 196KB
• SDK 作为 peerDependency，需单独安装

v1.1.0 - 功能完善

• 添加播放列表管理
• 添加循环模式控制
• 添加键盘快捷键支持
• 添加截屏、画中画功能
• 添加音量滚轮控制

许可证

ISC

相关链接

• npm 包
• Thunder Player SDK

技术支持

如需技术支持、集成帮助或 Demo 访问，请联系 Thunder Player 团队。