使用插件

VePlayer 中的功能，无论是简单的按钮，还是复杂的播放逻辑，均以插件的形式实现。这种插件化的设计可以提高代码的可维护性和灵活性。VePlayer 内置了一些常用的功能插件，同时也提供业务功能插件。对于内置插件，您可以获取插件实例、禁用插件或配置插件；对于业务功能插件，您需要自行注册并进行相应的配置。

本文详细介绍插件的功能和使用方法。

使用说明

获取插件实例

调用 getPlugin 并传入插件名称，即可获取插件实例。获取插件实例后，您可再调用插件的 API。示例代码如下：

const playerSdkIns = new VePlayer({
  ...
})

// 获取 pip 插件实例
const pipInstance = playerSdkIns.player.getPlugin('pip') 
// const pipInstance = playerSdkIns.player.plugins.pip

// 调用 pip 插件的 API 切换画中画
pipInstance.switchPIP()

注册插件

对于业务功能插件，您需要在初始化 VePlayer 实例时，设置 plugins 参数并传入插件名称注册插件。内置插件无需注册。示例代码如下：

import DemoPlugin from 'demoplugin'

const playerSdkIns = new VePlayer({
  ...,
  plugins: [DemoPlugin],
})

您也可以在初始化完成之后调用 registerPlugin 注册插件。

import DemoPlugin from 'demoplugin'

const playerSdkIns = new VePlayer({
  ...
})
playerSdkIns.player.registerPlugin(DemoPlugin)

禁用插件

对于内置插件，如需禁用，可采用以下方式：

• 在初始化 VePlayer 实例时，设置 ignores 参数，传入插件名称（不区分大小写），即可禁用指定插件。以禁用倍速调节插件和画中画插件为例：

  ignores: ['playbackRate', 'pip']
  

• 对于部分插件，您也可以通过插件的配置项实现禁用。详见含 UI 的内置插件。

配置插件

VePlayer 支持传入各个插件名称，配置插件的具体逻辑。例如配置播放进度条插件：

progress: {
   isDragingSeek: true, // 是否在拖拽的过程中更新 currentTime
   closeMoveSeek: true, // 是否关闭滑块 seek 能力
}

内置插件

VePlayer 内置了一些功能插件，不需要您额外引入，默认显示或者在特定条件下显示。

含 UI 的内置插件

controls: false,

// 或
controls: {
  disable: true,
}

progress: false,

// 或
progress: {
  disable: true,
}

fullscreen: false

// 或
fullscreen: {
  disable: true
}

volume: false,
// 或
// volume: {
//   disable: true,
// }

sdkDefinitionPlugin: {
  isShowIcon: false,
}

time: false,
// 或
// time: {
//   disable: true,
// }

start: false,
// 或
// start: {
//   disable: true,
// }

pip: false,
// 或
// pip: {
//   disable: true,
// }

autoplay: true,
autoplayMuted: true,

enableContextmenu: true,
closeVideoStopPropagation: true,

miniprogress: false, // 默认值
// 或
// miniprogress: {
//   disable: true,
// }

screenShot: false, // 默认值
// 或
// screenShot: {
//   disable: true,
// }

rotate: false, // 默认值
// 或
// rotate: {
//   disable: true,
// }

download: false, // 默认值
// 或
// download: {
//   disable: true,
// }

mini: false, // 默认值
// 或
// miniscreen: {
//   disable: true,
// }

dynamicBg: {disable: false}

// 不配置 dynamicBg 或
dynamicBg: {disable: true}

配置项 position

插件配置项 position 可用于指定 UI 插件的 DOM 挂载位置。以下为定义的位置：

默认布局

flex 布局

配置项 mode

Controls 插件配置项 mode 可用于指定控制栏布局方式。以下为三种布局方式的效果图：

normal

flex

bottom

配置项 index

插件配置项 index 是一个数字，用于指定 UI 插件在父节点上插入的位置，数字越小，越靠前。如果 index 相同，则按照注册顺序插入。index 可以通过配置覆盖来达到调整插件顺序的目的。

不含 UI 的内置插件

业务功能插件

VePlayer 提供的业务功能插件，需要您自行引入 plugins 配置项才可使用。

外挂字幕

VePlayer 支持 WebVTT (Web Video Text Tracks) 格式的字幕文件。您需要在实例化播放器时通过 plugins 参数注册外挂字幕插件，再通过 Subtitle 参数设置字幕列表。外挂字幕的配置参数介绍详见 ISubtitleConfig。示例代码如下：

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://xx.mp4",
  width: 600,
  height: 400,
  // 注册外挂字幕插件
  plugins: [VePlayer.Subtitle],
  // 配置外挂字幕插件
  Subtitle: {
    isDefaultOpen: true,
    list: [
      {
        "url": "https://字幕1.vtt",
        "text": "中英",
        "isDefault": true
      },
      {
        "url": "https://字幕2.vtt",
        "text": "中日",
        "isDefault": false
      }
    ]
  },
});

记忆播放

VePlayer 支持记忆播放功能，可以在您上次观看视频离开后的时间点继续播放。您需要在实例化播放器时通过 plugins 参数注册记忆播放插件，再传入 MemoryPlay 配置项，为视频配置唯一的 memoryId。记忆播放的配置参数介绍详见 IMemoryPlayConfig。示例代码如下：

const playerSdk = new VePlayer({
    id: 'mse',
    url: "https://xx.mp4",
    width: 600,
    height: 400,
    // 注册记忆播放插件
    plugins: [VePlayer.MemoryPlay],
    // 配置记忆播放插件
    MemoryPlay: {
        memoryId: 'example_memory_id'
    },
});

播放器默认使用浏览器的 localStorage API 存储播放时间，即默认情况下不能实现跨端跨平台共享存储记忆的播放时间点。如果您需要通过服务共享播放时间点，实现方式如下：

1. 传入 getTime 和 saveTime 两个函数。

2. getTime 要求入参为 memoryId，返回为时间的同步或异步函数。

3. saveTime 要求入参数可接受 memoryId 和时间的函数。

示例代码如下：

const playerSdk = new VePlayer({
    id: 'mse',
    url: "https://xx.mp4",
    width: 600,
    height: 400,
    plugins: [VePlayer.MemoryPlay],
    MemoryPlay: {
        memoryId: 'example_memory_id',
        getTime: async (id) => {
            // ...异步处理
            // const time = await getTimeApi(id);
            return time;
        },
        saveTime: async (id, time) => {
            // 调用接口存储时间
        }
    },
});

在页面被隐藏、播放器被销毁或者页面卸载时，VePlayer 会存储播放时间点。

视频镜像

VePlayer 支持水平方向的视频镜像。您需要在实例化播放器时通过 plugins 参数注册视频镜像插件，即可实现镜像功能。示例代码如下：

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://xx.mp4",
  height: 400,
  // 注册视频镜像插件
  plugins: [VePlayer.MirrorPlugin],
});

播放列表

VePlayer 支持播放列表，即在给定一个视频列表后，按顺序自动播放列表中的视频。VePlayer 提供播放列表相关的 UI 以及“打开/隐藏播放列表”和“播放下一个视频”两个按钮。具体效果如下：

如需使用播放列表功能，您可在初始化播放器实例时设置 plugins 参数注册播放列表插件实例，再通过 playListPlugin 参数对播放列表功能进行初始化配置。播放列表配置项详见 IPlayListConfig。示例代码如下：

const playerSdkIns = new VePlayer({
  id: 'video',
  width: 800,
  height: 600,
  // 注册播放列表插件
  plugins: [VePlayer.playListPlugin],
  // 配置播放列表插件
  playListPlugin: {
    list: [
      {
        url: 'xx.demo.com/1.mp4',
        poster: 'xx.demo.com/1.jpg',
        vid: '67ghsadd8a78s9df8',
        title: 'Remember to bring a little simple everyday',
      },
      {
        playAuthToken: 'demovideoplayAuthToken',
        poster: 'xx.demo.com/2.jpg',
        vid: '67ghsadd8a78s213df8',
        title: 'The night came quietly, with the heat and light',
      },
      {
        url: 'xx.demo.com/3.mp4',
        poster: 'xx.demo.com/3.jpg',
        vid: '67ghsaddhh78s9df8',
        title: 'Watching a beautiful fireworks at night will make you feel good',
      },
      {
        url: 'xx.demo.com/4.mp4',
        poster: 'xx.demo.com/4.jpg',
        vid: '67ghiodd8a78s9df8',
        title: 'Gentle and lazy sea breeze',
      },
    ],
  },
});

此外，播放列表插件提供 API 和事件。

API

下表列出播放列表插件支持的 API。

您可先调用 getPlugin 获取播放列表插件实例，再调用 API。以下示例展示了如何播放列表中的下一个视频：

// 播放下一个视频
playerSdkIns.getPlugin('playListPlugin').next();

事件

下表列出播放列表插件支持的事件。

以下示例展示了如何监听播放项变更：

playerSdkIns.on('play_list_item_change', data =>
  console.log('play_list_item_change, current item: ', data),
);

动态水印

VePlayer 支持动态水印，可将自定义的文案动态地覆盖在播放器上，以便在版权视频发生录屏等泄漏时根据添加的水印追踪泄漏源。您需要在实例化播放器时通过 plugins 参数注册动态水印插件，再通过 dynamicwatermark 配置动态水印。示例代码如下：

var playerSdk = new VePlayer({
  id: 'mse',
  url: "https://voddemo-play.volcvod.com/dem0.mp4",
  width: 640,
  height: 360,
  codec: 'h264',
  // 注册动态水印插件
  plugins: [ VePlayer.DynamicWatermarkPlugin ],
  // 配置动态水印插件
  dynamicwatermark: {
    enable: true, //【必填】 true-打开，false-关闭，默认值为false
    content: '火山引擎播放SDK', // 【必填】水印文案，String 类型，一行展示不折行，默认值为空
    // 以下参数为可选项
    // displayType: 1, // 水印展示形式，Number类型，0-固定位置，1-全屏滚动（播放容器），2-随机闪烁，默认值为1
    // opacity: 0.3, // 不透明度，Number类型，设置范围：[0~1]。默认值 0.3
    // tickerSpeed: 'MODERATE',// 移动/闪烁速度，String类型，"MODERATE"-适中, "FAST"-较快,  "SLOW"-较慢，displayType为0时不设置tickerSpeed则不闪烁
    // fontSize: 12,// 水印字体大小，Number或String类型，单位为px，String类型需携带单位，默认值12
    // fontColor: '#FFFFFF',// 水印颜色，String类型，默认值为"#FFFFFF"
    // top: undefined,  // 水印相对于播放容器顶部起始位置，Number类型，单位为px，默认值0
    // left: undefined, // 水印相对于播放容器左边起始位置，Number类型，单位为px，默认值0
    // right: undefined, // 水印相对于播放容器右边起始位置，Number类型，单位为px
    // bottom: undefined, // 水印相对于播放容器底部起始位置，Number类型，单位为px
  },
  vodLogOpts: {
    vtype: 'MP4',
    tag: '普通视频',
    line_app_id: 348293,
    line_user_id: 'veplayer_web_demo'
  }
});

动态水印效果如下：