ps-tcplayer/README.md

Tencent Cloud Player component with Vue2/Vue3 compatibility

# ps-tcplayer

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

## 特性

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

## 安装

```bash
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`

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

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

```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`：

```js
// 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
  },
  // ...
}
```

### 全局注册

```js
// 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')
```

### 局部注册

```js
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使用

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

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

```js
// 标准版(需要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引入(依赖模式)

```html
<!-- 引入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环境)

```html
<!-- 无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` | 扩展组件集合 |

### 基础用法

```html
<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 | 腾讯云播放器原生配置，详见[腾讯云播放器文档](https://cloud.tencent.com/document/product/881/20207) |
| `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访问：

```js
import { TcPlayerComponent } from 'ps-tcplayer'
```

### 可用组件列表

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

### 直接使用组件示例

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

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

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

### 自定义组件配置

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

#### 基本配置方式

```js
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` | 倒计时功能 | 根据配置启用 |

#### 完整配置示例

```js
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. 系统默认配置优先级最低

#### 禁用所有插件

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

```js
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：

```html
<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风格：

```html
<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>
```

## 开发与构建

```bash
# 安装依赖
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