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}

不含 UI 的内置插件

业务功能插件

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

外挂字幕

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

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { Subtitle } from '@volcengine/veplayer';

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://xx.mp4",
  width: 600,
  height: 400,
  // 注册外挂字幕插件
  plugins: [VePlayer.Subtitle],
  // 如果是 npm 方式引入，使用以下代码注册插件
  // plugins: [Subtitle],
  // 配置外挂字幕插件
  Subtitle: {
    isDefaultOpen: true,
    list: [
      {
        "url": "https://字幕1.vtt",
        "text": "中英",
        "isDefault": true
      },
      {
        "url": "https://字幕2.vtt",
        "text": "中日",
        "isDefault": false
      }
    ]
  },
});

可调用 updateSubtitles 方法更新字幕，示例代码如下：

playerSdk.getPlugin('subtitle').updateSubtitles([
  { "url": "https://字幕3.vtt", "text": "中英", "isDefault": true },
  { "url": "https://字幕4.vtt", "text": "中日", "isDefault": false }
]);

VePlayer 也支持直接将字幕数据以 JavaScript 数组形式传入，这样可以减少对 WebVTT 文件的请求，又方便在字幕编辑场景中直接修改和更新字幕数据。以下是示例代码：

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { Subtitle } from '@volcengine/veplayer';

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://xx.mp4",
  width: 600,
  height: 400,
  // 注册外挂字幕插件
  plugins: [VePlayer.Subtitle],
  // 如果是 npm 方式引入，使用以下代码注册插件
  // plugins: [Subtitle],
  Subtitle: {
      isDefaultOpen: true,
      // 传入字幕数据数组
      list: [
        {
          text: '中文',
          isDefault: true,
          list: [
            {
              start: 0,
              end: 80,
              list: [
                {
                  start: 0,
                  end: 15,
                  text: ['这是主字幕', '这是副字幕'],
                },
                {
                  start: 12,
                  end: 20,
                  text: ['这是第二段主字幕', '这是第二段副字幕'],
                },
              ],
            },
          ],
        },
        {
          text: 'English',
          list: [
            {
              start: 0,
              end: 80,
              list: [
                {
                  start: 0,
                  end: 15,
                  text: ['This is the main subtitle', 'This is the sub subtitle'],
                },
                {
                  start: 12,
                  end: 20,
                  text: ['This is the second main subtitle', 'This is the second sub subtitle'],
                },
              ],
            },
          ],
        },
      ],
    },
});

记忆播放

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

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { MemoryPlay } from '@volcengine/veplayer';

const playerSdk = new VePlayer({
    id: 'mse',
    url: "https://xx.mp4",
    width: 600,
    height: 400,
    // 注册记忆播放插件
    plugins: [VePlayer.MemoryPlay],
    // 如果是 npm 方式引入，使用以下代码注册插件
    // plugins: [MemoryPlay],
    // 配置记忆播放插件
    MemoryPlay: {
        memoryId: 'example_memory_id'
    },
});

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

1. 传入 getTime 和 saveTime 两个函数。
2. getTime 要求入参为 memoryId，返回为时间的同步或异步函数。
3. saveTime 要求入参数可接受 memoryId 和时间的函数。

示例代码如下：

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { MemoryPlay } from '@volcengine/veplayer';

const playerSdk = new VePlayer({
    id: 'mse',
    url: "https://xx.mp4",
    width: 600,
    height: 400,
    plugins: [VePlayer.MemoryPlay],
    // 如果是 npm 方式引入，使用以下代码注册插件
    // plugins: [MemoryPlay],
    MemoryPlay: {
        memoryId: 'example_memory_id',
        getTime: async (id) => {
            // ...异步处理
            // const time = await getTimeApi(id);
            return time;
        },
        saveTime: async (id, time) => {
            // 调用接口存储时间
        }
    },
});

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

视频镜像

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

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { MirrorPlugin } from '@volcengine/veplayer';

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://xx.mp4",
  height: 400,
  // 注册视频镜像插件
  plugins: [VePlayer.MirrorPlugin],
  // 如果是 npm 方式引入，使用以下代码注册插件
  // plugins: [MirrorPlugin],
});

播放列表

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

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

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { PlayListPlugin } from '@volcengine/veplayer';

const playerSdkIns = new VePlayer({
  id: 'video',
  width: 800,
  height: 600,
  // 注册播放列表插件
  plugins: [VePlayer.PlayListPlugin],
  // 如果是 npm 方式引入，使用以下代码注册插件
  // plugins: [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 配置动态水印。动态水印配置参数介绍详见 IWatermarkConfig。示例代码如下：

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { DynamicWatermarkPlugin } from '@volcengine/veplayer';

const playerSdk = new VePlayer({
  id: 'mse',
  url: "https://voddemo-play.volcvod.com/dem0.mp4",
  width: 640,
  height: 360,
  codec: 'h264',
  // 注册动态水印插件
  plugins: [ VePlayer.DynamicWatermarkPlugin ],
  // 如果是 npm 方式引入，使用以下代码注册插件
  // plugins: [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'
  }
});

动态水印效果如下：

清晰度降级

VePlayer 支持在播放具备多个码率清晰度的视频时，根据网络带宽的变化自动切换到适合当前带宽的低码率清晰度的视频，以减少卡顿现象，提高播放体验。

卡顿和长时间卡顿说明

在实现清晰度降级功能之前，你需要先了解一下卡顿和长时间卡顿的概念。
卡顿指视频无法继续播放，需要等待相关流程进行。这些流程包括：

• Buffer 不足，播放器正在等待网络请求资源。
• Buffer 足够，但解码无法跟上，播放器正在等待解码完成，通常是由于码率过高或设备性能不足。

卡顿开始以 WAITING 事件触发为准，触发 PLAYING 事件后表示播放恢复。可参考以下示例代码监听这些事件：

veplayer.on(VePlayer.Events.WAITING, () => {
  console.log('开始卡顿')
  veplayer.once(VePlayer.Events.PLAYING, () => {
    console.log('卡顿结束')
  })
})

长时间卡顿是指因为网络状况不佳或视频码率过高，持续时间（从 WAITING 事件触发开始计时）过长的卡顿。默认情况下，播放器会将持续时间超过 5 秒视为一次长时间卡顿。您可通过 longWaitingTime 参数自定义修改持续时间的阈值。发生长时间卡顿时，播放器会触发清晰度降级逻辑，根据用户选择的清晰度档位，要么自动降级为低码率视频，要么提醒用户切换为低码率视频。可参考以下示例代码监听长时间卡顿事件：

// 长时间卡顿事件。播放器会在此事件触发时提醒降级或者自动降级。
veplayer.on(VePlayer.Events.LONG_WAITING, () => console.log('发生了长时间卡顿'))

实现方式

实现清晰度降级功能，您需要在实例化播放器时通过 plugins 参数注册清晰度降级插件，再通过 DefinitionDemotePlugin 参数配置清晰度降级功能。清晰度降级的配置参数介绍详见 IDefinitionDemotePlugin。此外，你还需要将某一个清晰度档位设为自动档位。当用户选择不同档位时，播放器会触发不同的清晰度降级逻辑。具体说明如下：

• 当用户选择自动档位时，如果播放过程中发生长时间卡顿，播放器会按照您配置的降级顺序，自动切换到下一个清晰度档位。如下图所示：
  
  为实现自动降级，您需进行以下操作：
  • 将 isNeedAutoDemote 参数设为 true 开启自动降级。
  • 将某个清晰度标记为自动档位。
  • 通过 demotePriority 参数配置清晰度降级的顺序。如果已经降级到最低清晰度，则不再降级。

  注意

  在网络恢复后，播放器不会自动切换回高码率视频播放。

• 当用户选择某一非自动档位时，如果发生长时间卡顿，发生长时间卡顿时，播放器会在进度条左上方弹出提示框提醒用户当前出现卡顿，并提供按钮供用户点击以降级到下一个清晰度档位，如下图所示：
  

不同的播放模式下，清晰度降级的示例代码如下：

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { DefinitionDemotePlugin } from '@volcengine/veplayer';

const veplayer = new VePlayer({
    id: 'mse',
    url: "//demo.video.com/1.mp4",
    width: 640,
    height: 360,
    // 注册清晰度降级插件
    plugins: [VePlayer.DefinitionDemotePlugin],
    // 如果是 npm 方式引入，使用以下代码注册插件
    // plugins: [DefinitionDemotePlugin],
    // 配置清晰度降级插件
    DefinitionDemotePlugin:{
      // 配置清晰度降级的顺序
      demotePriority: ['uhd', 'hd', 'ld']
    },
    // 指定默认档位，需要将 url 设置为 playList 中对应档位的 url
    url: 'https://voddemo-play.volcvod.com/10501b001bdd43ae89d7c0fc3d6792b5/main.m3u8?a=0&auth_key=1773925042-f0489f7ac9a14d92b96bbfb7b39a7a0d-0-4e57d65b22e9aefe63ba1c519218e9fe&br=966&bt=966&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=4&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApOmZkZzg1PGVoNzhkOzxlZ2dfZy9gMHFrYTBgLS1kYy9zcy00L2JfL19eYF42Ly0vYi06Yw%3D%3D&vl=&vr=',
    playList: [
      {
        streamType: 'hls',
        definition: 'ld',
        definitionTextKey: 'LD', // 清晰度多语言 key
        url: 'https://voddemo-play.volcvod.com/1f7e669aa403420f95d00ca7d95d1795/main.m3u8?a=0&auth_key=1773925042-b375d2f0822f4022ad39e153c3e55f58-0-8ffc2e8f845b6a8e74e6b77c25bd980d&br=448&bt=448&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=2&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApZjNkOTZkZDs6NzVmZGU3ZGdfZy9gMHFrYTBgLS1kYy9zczUzMDIxMDVgYy8tNjA0NjI6Yw%3D%3D&vl=&vr=',
      },
      {
        streamType: 'hls',
        definition: 'hd',
        definitionTextKey: 'HD', // 清晰度多语言 key
        url: 'https://voddemo-play.volcvod.com/9d71d44b87c74e29980bdad6fbf92664/main.m3u8?a=0&auth_key=1773925042-3e2dcf9a03bc48868a151241d472f769-0-f22f5fb0c822ab5999bab8282b1c4583&br=643&bt=643&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=3&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApNDtoOzs3ODw2N2Q1aTg8aWdfZy9gMHFrYTBgLS1kYy9zc2E0YDRhMjQ0XzZjMjMzX186Yw%3D%3D&vl=&vr=',
      },
      {
        streamType: 'hls',
        // 将此档位标记为自动档位
        definition: 'auto', 
        definitionTextKey: 'AUTO',
        // 标记此档位实际映射的清晰度
        mapDefinition: 'uhd',
        url: 'https://voddemo-play.volcvod.com/10501b001bdd43ae89d7c0fc3d6792b5/main.m3u8?a=0&auth_key=1773925042-f0489f7ac9a14d92b96bbfb7b39a7a0d-0-4e57d65b22e9aefe63ba1c519218e9fe&br=966&bt=966&cd=0%7C0%7C0&ch=0&cr=0&cs=0&cv=1&dr=0&ds=4&er=0&l=2023032020544973DCCFE21CF4C02E38B1&lr=&mime_type=video_mp4&net=0&pl=0&qs=0&rc=amg6c2o0aTg6ZTQzNGRnM0ApOmZkZzg1PGVoNzhkOzxlZ2dfZy9gMHFrYTBgLS1kYy9zcy00L2JfL19eYF42Ly0vYi06Yw%3D%3D&vl=&vr=',
      },
    ],
    languages: {
      // 清晰度多语言翻译
      zh: {
        SD: '标清',
        LD: '流畅',
        HD: '高清',
        UD: '超清',
        UHD: '蓝光',
        AUTO: '自动',
      },
    },
  });

// 如果是 npm 方式引入，使用以下代码
// import VePlayer, { DefinitionDemotePlugin } from '@volcengine/veplayer';

const veplayer = new VePlayer({
    id: 'mse',
    width: 640,
    height: 360,
    // 注册清晰度降级插件
    plugins: [VePlayer.DefinitionDemotePlugin],
    // 如果是 npm 方式引入，使用以下代码注册插件
    // plugins: [DefinitionDemotePlugin],
    // 配置清晰度降级插件
    DefinitionDemotePlugin:{
      // 配置清晰度降级的顺序
      demotePriority: ['1080p', '720p', '480p', '360p'],
    },
    getVideoByToken: {
      playAuthToken: 'xxxplayAuthToken',
      defaultDefinition: '1080p',
      // 将 1080p 档位标记为自动档位
      autoDemoteDefinition: '1080p',
      // 设置自动档位的文案多语言 key
      autoDemoteDefinitionTextKey: 'AUTO' 
    }
    // 清晰度多语言翻译
    languages: {
      zh: {
        SD: '标清',
        LD: '流畅',
        HD: '高清',
        UD: '超清',
        UHD: '蓝光',
        AUTO: '自动',
      },
    },
  });

自定义插件

使用 VePlayer 时，您可以通过插件机制来扩展播放器的功能。VePlayer 的插件机制是基于播放器生命周期定义的，提供了常用的 API 和相关生命周期回调函数。通过这个机制，您可以在播放器的不同生命周期阶段执行特定的操作，而无需关注插件如何与播放器交互、安装和卸载。您可以自定义插件配置，在实例化播放器时根据配置来实例化插件，并在播放器实例化完成后安装这些插件。这样就可以根据需要添加或移除特定的插件。以下是关于自定义插件机制的说明和示例演示。

插件基类

BasePlugin

BasePlugin 为基础插件类，用于实现不带 UI 的播放逻辑，并包含完整的插件生命周期（除 render 方法外）。其中，静态属性 pluginName 是必须定义的参数，用作安装和存储插件实例时的唯一标识。示例用法如下：

// demoBasePlugin.js
import { BasePlugin } from '@volcengine/veplayer';
// cdn 方式引入
// const BasePlugin = VePlayer.BasePlugin;

export default class DemoBasePlugin extends BasePlugin {
  /**
   * （必须声明）插件的名称，将作为插件实例的唯一 key 值
   * 该参数也是 SDK 上该插件的配置透传 key 值，例如：
   * var p = new VePlayer({
   *   demoBasePlugin: {
   *     text: '这是插件demoBasePlugin的配置信息'
   *   }
   * })
   * 在插件 afterCreate 之后可以通过 this.config.text 获取到该配置参数
   **/
  static get pluginName() {
    return 'demoBasePlugin';
  }

  static get defaultConfig() {
    return {
      text: '这是插件demoBasePlugin的默认Text',
    };
  }

  constructor(args) {
    super(args);
  }

  afterPlayerInit() {
    // TODO 播放器内核调用 start 初始化播放源之后的逻辑
  }

  afterCreate() {
    // 在 afterCreate 中可以加入 DOM 的事件监听

    this.on('play', () => {
      console.log('播放播放回调');
    });
  }

  destroy() {
    // 播放器内核销毁的时候一些逻辑
  }
}

Plugin

Plugin 为带 UI 插件的基类，继承自 BasePlugin。除了具有完善的生命周期回调，还内置了 render 方法以及一些 Dom 相关 API。示例用法如下：

import { Plugin } from '@volcengine/veplayer';
// cdn 方式引入
// const Plugin = VePlayer.Plugin;

const { POSITIONS } = Plugin;

// demoPlugin.js
export default class demoPlugin extends Plugin {
  // 插件的名称，将作为插件实例的唯一 key 值
  static get pluginName() {
    return 'demoPlugin';
  }

  static get defaultConfig() {
    return {
      // 挂载在 controls 的右侧，如果不指定则默认挂载在播放器内核根节点上
      position: POSITIONS.CONTROLS_RIGHT,
    };
  }

  constructor(args) {
    super(args);
  }

  beforePlayerInit() {
    // TODO 播放器内核调用 start 初始化播放源之前的逻辑
  }

  afterPlayerInit() {
    // TODO 播放器内核调用 start 初始化播放源之后的逻辑
  }

  afterCreate() {
    this.icon = this.find('.icon');
    this.onIconClick = e => {
      console.log('class为icon元素点击回调');
    };
    this.onClick = () => {
      console.log('当前插件根节点点击事件');
      const eventData = {a: 1 }
      this.emiit('custom_event', eventData) 
    };
    // 对当前插件根节点内部类名为 .icon 的元素绑定 click 事件
    this.bind('.icon', 'click', this.onIconClick);
    // 对当前插件根节点绑定click事件
    this.bind('click', this.onClick);
    //T ODO 插件实例化之后的一些逻辑
  }

  destroy() {
    this.unbind('.icon', 'click', this.onIconClick);
    this.unbind('click', this.onClick);
    this.icon = null;
    // 播放器内核销毁的时候一些逻辑
  }

  render() {
    return `<div class="demo-plugin">这是一个dmeo插件<div class="icon"></div></div>`;
  }
}

配置项

配置项 position

插件配置项 position 可用于指定 UI 插件在 DOM 中挂载的位置。可选值是插件类的一个枚举值的静态属性，具体值如下：

Plugin.POSITIONS = { 
  ROOT: 'root',                     // 挂载在根节点上 
  ROOT_LEFT: 'rootLeft',            // 挂载在播放器容器的左侧边栏 
  ROOT_RIGHT: 'rootRight',          // 挂载在播放器容器的右侧边栏 
  ROOT_TOP: 'rootTop',              // 挂载在播放器容器的顶部边栏 
  CONTROLS_LEFT: 'controlsLeft',    // 挂载在播放器控制栏的左侧 
  CONTROLS_RIGTH: 'controlsRight',  // 挂载在播放器控制栏的右侧 
  CONTROLS_CENTER: 'controlsCenter' // 挂载在播放器控制栏的中间控制条位置 
}

以下为定义的位置：
默认布局

flex 布局

配置项 mode

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

flex

bottom

配置项 index

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

插件基类 API 参考

生命周期钩子函数

基础插件类 BasePlugin 提供生命周期钩子函数。这些函数会在特定时机被播放器调用，方便实现自定义业务逻辑。以下是插件基类生命周期钩子函数的 API 定义：

declare class BasePlugin {
    // 在插件实例被创建、但尚未执行其他操作时回调。可以从 args 中获取播放器内核 player 和插件配置 config 等信息。
    beforeCreate(args: IBasePluginOptions): void;
    // 在插件实例创建后回调。此时可以获取所有内置对象，如 this.player。如果是 UI 插件，则可以获取当前插件的根节点，如 this.el。
    afterCreate(): void;
    // 在播放器初始化播放源之前回调。这是唯一可以执行异步操作的生命周期钩子函数。如果执行异步操作，请正确处理异步错误，以防止阻塞后续播放。
    beforePlayerInit(): void;
    // 在播放器内核初始化时带有的所有插件创建完成后回调。在此阶段可以获取所有注册的插件实例，进行插件实例之间的依赖交互。
    onPluginsReady(): void;
    // 在播放器内核执行 start 逻辑后、初始化播放源后回调。
    afterPlayerInit(): void;
    destroy(): void;
    // ...
}

静态属性或方法

基础插件类 BasePlugin 提供以下静态属性和方法：

• pluginName：插件名称，即插件的唯一 ID。在获取插件实例时需要传入该名称。例如，获取内置的play插件实例：

  const playPluginIns = playerSdk.getPlugin('play');
  

• defineGetterOrSetter()：用于定义对象的 getter 和 setter。

• defaultConfig()：用于定义插件的默认配置。例如，内置的poster插件的默认配置如下：

  static get defaultConfig () {
    return {
      isEndedShow: true,
      hideCanplay: false,
      notHidden: false,
      poster: '',
      fillMode: 'fixWidth'
    }
  }
  

实例属性

基础插件类 BasePlugin 的实例包含以下基本属性，可通过这些属性获取播放器内核等信息：

• player：播放器内核实例。
• playerConfig：播放器内核配置。
• pluginName：插件名称。
• domEventType：当前插件支持的事件类型。在 H5 端返回 touch，在 PC 端返回 mouse。
• root：如果当前插件为 UI 插件，则是该 UI 的根节点 DOM，通过 this.root 获取；否则为null。

多语言 API

基础插件类 BasePlugin 提供以下多语言相关的 API：

• get lang(): string;：当前语言，例如en、zh-cn。
• get i18n(): import("../lang/i18n").IXGI18nText;：当前多语言的映射配置。您可以通过 key 获取到各个文案对应当前语言的翻译。
• get i18nKeys(): {[propName: string]: string;};：当前多语言的 key。

事件 API

基础插件类 BasePlugin 提供事件相关的API，您可以自行实现事件的监听、取消监听和触发。以下是相关API的定义：

• on(event: string | Array<string>, callback: Function)：添加事件监听。通过该 API 监听指定名称的事件。示例代码：

  this.on(VePlayer.Events.PLAY, () => { 
    console.log('play') 
  }) 
  // 同时监听多个事件
  this.on([VePlayer.Events.ENDED, VePlayer.Events.PAUSE], () => { 
    console.log('ended or pause') 
  }) 
  

• once(event: string, callback: Function)：添加一次性事件监听，即事件触发后后续不再监听。示例代码：

  this.once(VePlayer.Events.PLAY, () => { 
    console.log('play') 
  }) 
  

• off(event: string, callback: Function)：取消某个事件监听。示例代码：

  this.off(VePlayer.Events.PLAY, () => { 
    console.log('play') 
  }) 
  // 同时取消多个事件监听
  this.off([VePlayer.Events.ENDED, Events.PAUSE], () => { 
    console.log('ended or pause') 
  }) 
  

• offAll()：取消本插件所有事件的监听。示例代码：

  this.off(VePlayer.Events.PLAY, () => { 
    console.log('play') 
  }) 
  

• emit(event: string, ...res: any[])：触发自定义事件。示例代码：

  this.emit('customEvent', () => { 
    console.log('customEvent') 
  })
  

• emitUserAction(event: any, action: string, params?: {})：触发用户行为事件，事件名为VePlayer.Events.USER_ACTION，第二个参数标记用户事件的类型，第三个参数为自定义事件参数。示例代码：

  handleClick(e) {
    this.emitUserAction(e, 'custom_click', {name: 'custom_click'})
  }
  

其他内置 API

• show()：显示当前插件。示例代码：

  // 默认使用 block
  plugin.show()
  // 指定显示的插件名为 flex
  plugin.show('flex')
  

• hide()：隐藏当前插件。

• find(selector: string)：在当前插件根节点下查找。底层使用的 querySelector。示例代码：

  // 获取当前 UI 插件下类名为 .icon 的 dom
  this.icon = this.find('.icon')
  // 获取当前 UI 插件下 tag 为 li 的 dom
  this.lis = this.find('li')
  

• bind(selector: string, event: string, handler: Function)：对符合选择器的 DOM 添加事件代理，相应的取消事件代理的 API 为 unbind。可以在 destroy 时调用。示例代码：

  // 对当前 UI 插件根节点下的 li a 进行事件代理
  this.bind('li a', 'click', this.clickHandler)
  this.unbind('li a', 'click', this.clickHandler)
  
  // 对当前插件根节点添加事件监听，目标元素为 this.el
  this.bind('click', this.clickHandler)
  this.unbind('click', this.clickHandler)
  
  // 同时对同一选择器的多个事件监听相同的事件代理
  this.bind('li a', ['click', 'touched'], this.clickHandler)
  this.unbind('li a', ['click', 'touched'], this.clickHandler)
  

• unbind(selector: string, event: string, handler: Function) ：对符合选择器的 DOM 取消事件代理，可以在 destroy 时调用。

• setStyle(name: string, value: string: string) ：对当前 UI 插件的根节点设置样式。示例代码：

  // 设置单个样式
  this.setStyle('height', '40px')
  // 设置多个样式
  this.setStyle({
    'height': '40px',
    'width': '40px'
  })
  

• setAttr(name: string, value: string) ：对当前 UI 插件的根节点设置属性。示例代码：

  // 设置单个属性
  this.setAttr('data-url', 'http://ixigua.com')
  // 设置多个属性
  this.setAttr({
    'data-id': 1,
    'data-name': 'name' 
  })
  

• setHtml (htmlStr: string, callback: Function) ：重置当前根节点的 HTML 结构。示例代码：

  this.setHtml(<div class="icon">重置icon</div>, () => {
    console.log('dom重置完成')
  })