ps-tcplayer

基于腾讯云视频播放器(TCPlayer)封装的Vue组件库，同时支持Vue2和Vue3，提供丰富的功能扩展和便捷的API。

特性

• 🔄 同时兼容Vue2和Vue3，基于vue-demi实现
• 🎞️ 完整支持腾讯云视频播放器原生功能
• 🧩 提供丰富的扩展组件（倍速播放、清晰度切换、记忆播放等）
• 📱 响应式设计，适配各种屏幕尺寸
• 🛠️ 简单易用的API，灵活的配置选项
• 🌟 支持SDK形式引入，可在Vue、原生JS等环境使用

安装

npm install ps-tcplayer --save
# 或
yarn add ps-tcplayer
# 或
pnpm add ps-tcplayer

使用方法

Vue2 项目使用说明

在 Vue2 项目中使用本组件库需要安装 @vue/composition-api 与 vue-demi：

Vue2.7 不需要安装 @vue/composition-api

# 安装 @vue/composition-api 依赖
npm install @vue/composition-api vue-demi --save

然后在项目的入口文件（通常是 main.js）中添加：

// Vue2 项目入口文件 (main.js)
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import { tcplayer } from 'ps-tcplayer'

// 在使用任何 vue-demi 相关功能之前，必须先安装 VueCompositionAPI
Vue.use(VueCompositionAPI)

// 之后再安装 tcplayer 组件
Vue.use(tcplayer)

new Vue({
  // ...
}).$mount('#app')

如果使用的是局部注册方式，确保已安装 @vue/composition-api：

// Vue2 组件文件
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import { tcplayer } from 'ps-tcplayer'

// 确保在整个项目中至少调用过一次 Vue.use(VueCompositionAPI)
Vue.use(VueCompositionAPI)

export default {
  components: {
    PsTcPlayer: tcplayer
  },
  // ...
}

全局注册

// Vue 2
import Vue from 'vue'
import { tcplayer } from 'ps-tcplayer'

Vue.use(tcplayer)

// Vue 3
import { createApp } from 'vue'
import { tcplayer } from 'ps-tcplayer'
import App from './App.vue'

const app = createApp(App)
app.use(tcplayer)
app.mount('#app')

局部注册

import { tcplayer } from 'ps-tcplayer'

export default {
  components: {
    PsTcPlayer: tcplayer
  }
}

SDK形式使用

ps-tcplayer提供了SDK模式，可以在各种环境中使用，包括原生JS、Vue2、Vue3等。

引入SDK

SDK提供两种版本:

• 标准版: 需要外部提供Vue和vue-demi
• 独立版(Standalone): 所有依赖打包在内，适合无Vue环境

通过NPM使用

// 在Vue项目中安装(标准版)
npm install ps-tcplayer vue vue-demi

// 在Vue2项目中还需要
npm install @vue/composition-api

// 标准版(需要Vue环境)
import PsTcPlayer from 'ps-tcplayer/dist/sdk/ps-tcplayer.js'

// 独立版(适合无Vue环境)
import PsTcPlayer from 'ps-tcplayer/dist/sdk-standalone/ps-tcplayer.standalone.js'

// 检查环境
console.log(`当前Vue版本: ${PsTcPlayer.version}`)
console.log(`是否Vue2: ${PsTcPlayer.isVue2}`)
console.log(`是否Vue3: ${PsTcPlayer.isVue3}`)

// 初始化播放器
const playerId = PsTcPlayer.init('#player-container', {
  tconfig: {
    m3u8: 'https://example.com/video.m3u8',
    autoplay: false,
    poster: 'https://example.com/poster.jpg'
  },
  showNext: true,
  bulletScreen: true,
  bulletContent: '欢迎使用'
})

// 销毁播放器
PsTcPlayer.destroy(playerId)

通过CDN引入(依赖模式)

<!-- 引入Vue -->
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<!-- 引入vue-demi -->
<script src="https://unpkg.com/vue-demi/lib/index.iife.js"></script>
<!-- 引入播放器SDK -->
<script src="https://unpkg.com/ps-tcplayer/dist/sdk/ps-tcplayer.js"></script>

<div id="player-container" style="width: 800px; height: 450px;"></div>

<script>
  // 初始化播放器
  const playerId = PsTcPlayer.init('#player-container', {
    tconfig: {
      m3u8: 'https://example.com/video.m3u8',
      autoplay: false
    }
  })
  
  // 使用完后销毁
  // PsTcPlayer.destroy(playerId)
</script>

通过CDN引入(无Vue环境)

<!-- 无Vue环境，使用独立版 -->
<script src="https://unpkg.com/ps-tcplayer/dist/sdk-standalone/ps-tcplayer.standalone.js"></script>

<div id="player-container" style="width: 800px; height: 450px;"></div>

<script>
  // 初始化播放器 - 无需引入Vue和vue-demi
  const playerId = PsTcPlayer.init('#player-container', {
    tconfig: {
      m3u8: 'https://example.com/video.m3u8',
      autoplay: false
    }
  })
</script>

SDK API

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | init | selector: string, config: Object | string | 初始化播放器，返回实例ID | | destroy | instanceId: string | boolean | 销毁播放器实例 | | getInstance | instanceId: string | Object | 获取播放器实例 | | getAllInstances | - | string[] | 获取所有播放器实例ID |

静态属性

| 属性 | 类型 | 说明 | | --- | --- | --- | | version | string | 当前Vue版本 | | isVue2 | boolean | 是否Vue2环境 | | isVue3 | boolean | 是否Vue3环境 | | TcPlayerComponent | Object | 扩展组件集合 |

基础用法

<template>
  <div style="width: 800px; height: 450px;">
    <ps-tc-player :config="playerConfig" />
  </div>
</template>

<script>
export default {
  data() {
    return {
      playerConfig: {
        // 腾讯云播放器配置
        tconfig: {
          m3u8: 'https://example.com/video.m3u8', // 视频地址
          autoplay: false,                       // 自动播放
          poster: 'https://example.com/poster.jpg', // 视频封面
          plugins: {
            ContinuePlay: { auto: true },        // 启用记忆播放
            ContextMenu: { open: true }          // 启用右键菜单
          }
        },
        // 扩展功能配置
        showNext: true,                         // 显示下一个视频按钮
        showPre: true,                          // 显示上一个视频按钮
        htime: 0,                               // 记忆播放时间点(秒)
        bulletScreen: true,                     // 启用跑马灯
        bulletContent: '欢迎使用'                // 跑马灯内容
      }
    }
  },
  methods: {
    // 功能回调方法
    onnext() {
      console.log('播放下一个视频')
    },
    onpre() {
      console.log('播放上一个视频')
    }
  }
}
</script>

配置选项

主要配置

| 属性 | 类型 | 说明 | | --- | --- | --- | | tconfig | Object | 腾讯云播放器原生配置，详见腾讯云播放器文档 | | onnext | Function | 下一个视频回调函数 | | onpre | Function | 上一个视频回调函数 | | showNext | Boolean | 是否显示下一个按钮 | | showPre | Boolean | 是否显示上一个按钮 | | htime | Number | 记忆播放时间点(秒) | | bulletScreen | Boolean | 是否启用跑马灯 | | bulletContent | String | 跑马灯内容 | | star | Boolean | 是否启用评分功能 | | upStar | Function | 评分回调函数 |

播放器事件

组件会自动监听并转发以下播放器事件：

• onready: 播放器准备就绪
• onerror: 发生错误
• ontimeupdate: 播放进度更新
• onpause: 暂停播放
• onplay: 开始播放
• onended: 播放结束
• onwaiting: 缓冲等待
• onsnapshoted: 截图完成

扩展组件

ps-tcplayer提供了以下扩展组件，可以通过TcPlayerComponent访问：

import { TcPlayerComponent } from 'ps-tcplayer'

可用组件列表

• PlayerNextComponent: 下一个视频控制
• PlayPrevComponent: 上一个视频控制
• MemoryPlayComponent: 记忆播放功能
• QualityComponent: 清晰度切换
• RateComponent: 倍速播放
• BulletScreenComponent: 跑马灯功能
• CountdownComponent: 倒计时功能
• SnapshotComponent: 视频截图
• StarRatingComponent: 视频评分

直接使用组件示例

// 获取播放器实例后使用扩展组件
const player = this.$refs.playerRef.$player

// 初始化倍速播放组件
const rateComponent = new TcPlayerComponent.RateComponent(player)

// 设置播放速率
rateComponent.setRate(2.0)

自定义组件配置

通过配置可以自定义扩展组件。优化后的插件系统支持更灵活的配置方式，并正确区分了腾讯云播放器原生插件和我们的自定义插件：

基本配置方式

const playerConfig = {
  tconfig: {
    m3u8: 'https://example.com/video.m3u8',
    // 腾讯云播放器原生插件配置
    plugins: {
      ContinuePlay: {
        auto: true  // 记忆播放
      },
      ContextMenu: {
        open: true  // 右键菜单
      },
      ProgressMarker: false  // 进度标记
    },
    // 自定义插件配置
    customPlugins: {
      // 布尔值配置：控制插件是否启用
      QualityComponent: true,          // 启用分辨率切换
      RateComponent: false,            // 禁用倍速播放
      SnapshotComponent: true,         // 启用截图功能
      
      // 对象配置：详细控制插件行为
      BulletScreenComponent: {
        enabled: true,
        args: ['自定义弹幕内容', { fontSize: '24px', color: 'red' }, 'random']
      }
    }
  },
  
  // 或者也可以直接在根级配置自定义插件
  plugins: {
    QualityComponent: true,
    RateComponent: false
  }
}

两种配置位置

自定义插件支持两种配置位置：

1. config.tconfig.customPlugins - 推荐方式，结构更清晰
2. config.plugins - 简化方式，向下兼容

默认插件列表

优化后的插件系统包含以下默认插件，除非明确禁用，否则都会默认启用：

| 插件名称 | 说明 | 默认状态 | | --- | --- | --- | | MemoryPlayComponent | 记忆播放功能 | 默认启用 | | QualityComponent | 分辨率切换 | 默认启用 | | RateComponent | 倍速播放 | 默认启用 | | SnapshotComponent | 视频截图 | 默认启用 | | BulletScreenComponent | 跑马灯功能 | 默认启用 | | PlayerNextComponent | 下一个视频控制 | 根据配置启用 | | PlayPrevComponent | 上一个视频控制 | 根据配置启用 | | CountdownComponent | 倒计时功能 | 根据配置启用 |

完整配置示例

const playerConfig = {
  tconfig: {
    m3u8: 'https://example.com/video.m3u8',
    
    // 腾讯云播放器原生插件配置
    plugins: {
      ContinuePlay: {
        auto: true
      },
      ContextMenu: {
        levelSwitch: {
          open: true,
          switchingText: '正在为您切换到',
          switchedText: '已为您切换到',
          switchErrorText: '切换失败'
        }
      },
      ProgressMarker: false
    },
    
    // 自定义插件配置
    customPlugins: {
      // 分辨率配置
      QualityComponent: {
        enabled: true,
        args: [null, 'HD', '高清']
      },
      
      // 倍速播放配置
      RateComponent: {
        enabled: true
      },
      
      // 截图功能配置
      SnapshotComponent: {
        enabled: true
      },
      
      // 跑马灯配置
      BulletScreenComponent: {
        enabled: true,
        args: ['学习成就梦想', { fontSize: '16px', color: '#fff' }, 'random']
      },
      
      // 下一个视频按钮
      PlayerNextComponent: {
        enabled: false  // 禁用下一个视频按钮
      },
      
      // 上一个视频按钮
      PlayPrevComponent: {
        enabled: false  // 禁用上一个视频按钮
      },
      
      // 倒计时功能
      CountdownComponent: {
        enabled: false  // 禁用倒计时
      }
    }
  },
  
  // 传统配置方式仍然支持
  showNext: true,
  bulletScreen: true,
  bulletContent: '欢迎使用',
  htime: 120  // 记忆播放时间点
}

配置优先级

1. tconfig.customPlugins 或 plugins 中的具体配置优先级最高
2. 传统的配置属性（如 bulletScreen, showNext 等）作为后备
3. 系统默认配置优先级最低

禁用所有插件

如果需要禁用所有默认插件，可以这样配置：

const playerConfig = {
  tconfig: {
    m3u8: 'https://example.com/video.m3u8',
    customPlugins: {
      MemoryPlayComponent: false,
      QualityComponent: false,
      RateComponent: false,
      SnapshotComponent: false,
      BulletScreenComponent: false,
      PlayerNextComponent: false,
      PlayPrevComponent: false,
      CountdownComponent: false
    }
  }
}

重要提醒

⚠️ 注意：请不要将自定义插件配置（如 QualityComponent、RateComponent 等）放在 tconfig.plugins 中，这会导致腾讯云播放器尝试加载不存在的原生插件而报错。

• ✅ 正确：使用 tconfig.customPlugins 或 plugins 配置自定义插件
• ❌ 错误：将自定义插件配置放在 tconfig.plugins 中

在组合式API中使用

ps-tcplayer完全支持Vue3组合式API：

<template>
  <div style="width: 800px; height: 450px;">
    <ps-tc-player :config="playerConfig" @ready="onPlayerReady" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { tcplayer } from 'ps-tcplayer'

const playerConfig = ref({
  tconfig: {
    m3u8: 'https://example.com/video.m3u8',
    autoplay: false
  },
  showNext: true,
  bulletScreen: true,
  bulletContent: '欢迎使用'
})

const onPlayerReady = (player) => {
  console.log('播放器已准备就绪', player)
  // 可以在这里访问播放器实例进行操作
}
</script>

Vue2中的组合式API用法

在Vue2项目中，借助@vue/composition-api，也可以使用类似的组合式API风格：

<template>
  <div style="width: 800px; height: 450px;">
    <ps-tc-player :config="playerConfig" @ready="onPlayerReady" />
  </div>
</template>

<script>
import Vue from 'vue'
import VueCompositionAPI, { ref, onMounted } from '@vue/composition-api'
import { tcplayer } from 'ps-tcplayer'

// 确保已安装VueCompositionAPI
Vue.use(VueCompositionAPI)

export default {
  components: {
    PsTcPlayer: tcplayer
  },
  setup() {
    const playerConfig = ref({
      tconfig: {
        m3u8: 'https://example.com/video.m3u8',
        autoplay: false
      },
      showNext: true,
      bulletScreen: true,
      bulletContent: '欢迎使用Vue2组合式API'
    })

    const onPlayerReady = (player) => {
      console.log('播放器已准备就绪', player)
      // 可以在这里访问播放器实例进行操作
    }

    onMounted(() => {
      console.log('组件已挂载')
    })

    return {
      playerConfig,
      onPlayerReady
    }
  }
}
</script>

开发与构建

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build

兼容性说明

• Vue 2.6.0+（需要安装 @vue/composition-api >= 1.0.0-rc.1）
• Vue 3.0.0+
• 基于vue-demi实现跨版本兼容（vue-demi >= 0.13.0）

vue-demi 版本说明

ps-tcplayer 依赖 vue-demi 实现Vue2和Vue3的跨版本兼容。vue-demi 会根据项目中安装的Vue版本自动适配API：

• 在 Vue2 项目中：将使用 @vue/composition-api 提供的API
• 在 Vue3 项目中：将直接使用Vue3原生的组合式API

如果在Vue2项目中使用时遇到报错，请检查：

1. 是否已安装 @vue/composition-api
2. 是否在使用组件前调用了 Vue.use(VueCompositionAPI)
3. 依赖版本是否兼容（建议使用最新版本）

许可证

ISC