插件

播放组件实现了插件系统，用与解耦功能，增加各功能之间的组合能力。
播放组件内置了很多插件，如控制条、水印、信息面板等插件。

播放组件中已经生成了多个版本的插件组合产物

插件	默认导出	basic	Vue2	Vue3	React
I18nPlugin（国际化）	✅	✅	✅	✅	✅
LoggerPlugin（日志上报）	✅	✅	✅	✅	✅
WaterMarkPlugin（水印）	✅	--	✅	✅	✅
ChromeControlsPlugin（控制条）	✅	✅	✅	✅	✅
EventLogPlugin（信息面板）	✅	--	✅	✅	✅
PrefetchPlugin（预热）	✅	--	✅	✅	✅
PreviewPlugin（预览图）	✅	--	✅	✅	✅
HotkeyPlugin（热键）	✅	--	✅	✅	✅
MirrorImagePlugin（镜像画面）	✅	--	✅	✅	✅

引用插件

如利用第三方实现的 UI 控件插件

import KwaiPlayerReact, { KwaiPlayer } from '@ks-video/kwai-player-web/react';
import StreamLakeControlsPlugin from '@ks-video/kwai-player-plugin-streamlake-controls';

// 在实例化播放器前注册
KwaiPlayer.register(StreamLakeControlsPlugin);

const App: React.FC<Props> = () => {
  return (
    <div>
      <KwaiPlayerReact
        src={''}
        // 主动关闭默认控制条插件
        plugins={{ ChromeControlsPlugin: false }}
      ></KwaiPlayerReact>
    </div>
  );
};

禁用插件

实例化播放组件时可以暂时禁用插件

new KwaiPlayer('#player-1', {
  plugins: {
    WaterMarkPlugin: false,// 当前实例关闭水印插件
  }
}

<KwaiPlayerReact
  src={''}
  // 主动关闭默认控制条插件
  plugins={{ ChromeControlsPlugin: false }}
></KwaiPlayerReact>

<kwai-player-vue
  :plugins="{ ChromeControlsPlugin: false }"
>
</kwai-player-vue>

内置插件

I18nPlugin（国际化）

插件默认语言为zh-Hans，内置en
可直接指定为英语

new KwaiPlayer('#player-1', {
  plugins: {
    I18nPlugin: {
      lang: 'en'
    }
  }
}

自定义语言

new KwaiPlayer('#player-1', {
  plugins: {
    I18nPlugin: {
      lang: 'en-US',
      locals: {
        'en-US': {
          "CONTEXT_MENU_LOOP": "Loop",
          "CONTEXT_MENU_EVENT_LOG": "Debug Info",
          "PLAYBACK_RATE_NORMAL": "Normal",
          "OVERFLOW_BACK": "Options",
          "OVERFLOW_ITEM_DOWNLOAD": "Download",
          "OVERFLOW_ITEM_VIDEO": "Video Tracks",
          "OVERFLOW_ITEM_AUDIO": "Audio Tracks",
          "OVERFLOW_ITEM_PLAYBACK_RATE": "Playback speed",
          "OVERFLOW_ITEM_PICTURE_IN_PICTURE": "Picture in Picture",
          "OVERFLOW_ITEM_EVENT_LOG": "Debug Info",
          "OVERFLOW_ITEM_LOOP": "Loop",
          "OVERFLOW_ITEM_MIRROR_IMAGE": "Mirror Image"
        }
      }
    }
  }
}

LoggerPlugin（日志上报）

提供播放组件数据上报
可利用appendSummaryField 方法追加上报字段到汇总日志中

const plugin = player.getPluginInstance('LoggerPlugin');
plugin.appendSummaryField('fieldA', { a: 1, b2 });

WaterMarkPlugin（水印）

可以通过在播放器容器中增加子元素的方式添加水印

水印

必须包含属性 kwai-player-watermark

原生 js 示例

<style>
  .wm {
    background-repeat: repeat;
    background-image: url(data:image/svg+xml;base64,.......);
  }
</style>
<div id="player">
  <div class="wm" kwai-player-watermark></div>
</div>

Vue 示例

<style>
.wm {
    background-repeat: repeat;
    background-image: url(data:image/svg+xml;base64,.......)
}
</style>


<kwai-player-vue2
    class="player"
    :src="src"
    :autoplay="autoplay"
>
    <div className="wm" kwai-player-watermark></div>
</kwai-player-vue2>

React 示例

<style>
.wm {
    background-repeat: repeat;
    background-image: url(data:image/svg+xml;base64,.......)
}
</style>


<KwaiPlayerReact
    className="kwai-player-react"
    src={src}
    autoPlay={true}
>
    <div className="wm" kwai-player-watermark="true"></div>
</KwaiPlayerReact>

ChromeControlsPlugin（控制条）

实现了默认控制条 UI 交互
提供 addContextMenuItem、addOverflowItem分别增加右键菜单选项与增加更多选项

const plugin = player.getPluginInstance('ChromeControlsPlugin')
plugin.addContextMenuItem(
  name: string,
  callback: () => void,
  iconSrc: string,
  isChecked: boolean
): SwitchItem

const plugin = player.getPluginInstance('ChromeControlsPlugin')
plugin.addOverflowItem(
  name: string,
  callback: () => void,
  iconSrc: string,
  isChecked: boolean
): OverflowItem

EventLogPlugin（信息面板）

提供播放器内部 Debug 数据展示面板
可利用open、close 开启关闭

const plugin = player.getPluginInstance('EventLogPlugin');
plugin.open();
plugin.close();
plugin.isShow; // 是否展示

PrefetchPlugin（预热）

提供播放地址链接预热功能，可提前做 dns 解析等。

const player1 = new KwaiPlayer('#player-1', {
  prefetch: true
})
<KwaiPlayerReact prefetch={true}/>
<kwai-player-vue :prefetch="true" />

PreviewPlugin（预览图）

增加控制条上的预览画面，需要指定预览图地址

new KwaiPlayer('#player-1', {
  plugins: {
    PreviewPlugin: {
      src: 'https://mp-dev2.test.gifshow.com/web-test/preview-vtt/1b28b2dec66cc543-136e323bf4bee2f38e902291450a8326-tob-player-sprite-test4.vtt',
    },
  },
});

HotkeyPlugin（热键）

可利用键盘快进快退、暂停播放、音量高低调节

键位	单击	长按
ArrowRight	前进 10s	3 倍速
ArrowLeft	回退进度的两百分之 1 秒(若大于 10s 则为 10s、小于 5s 则为 5s)	每 100ms 出发一次回退（时长如单击）
ArrowUp	增加音量的 5%	每 100ms 增加音量的 5%
ArrowDown	减少音量的 5%	每 100ms 减少音量的 5%
Space	播放/暂停	--

MirrorImagePlugin（镜像画面）

可实现画面镜像，提供onChangeShowMirrorImage 开启或关闭镜像

const plugin = player.getPluginInstance('MirrorImagePlugin');
plugin.onChangeShowMirrorImage();

如何自定义一个插件

通过继承 PluginModule 实现一个插件，例如水印插件

import KwaiPlayer, { PluginModule } from '@ks-video/kwai-player-web';

export default class WaterMarkPlugin extends PluginModule {
  // 需指定name为唯一值
  name = 'WaterMarkPlugin';
}

利用钩子

• beforeInstall
  数据准备完成，还未开始实例化播放内核前触发
• afterInstall
  实例化播放内核后触发
• beforeUninstall
  销毁播放内核前触发
• afterUninstall
  销毁播放内核后触发

注册销毁插件

实现一个插件后需要在KwaiPlayer对象上注册

KwaiPlayer.register(WaterMarkPlugin); //注册
KwaiPlayer.deregister(WaterMarkPlugin); //注销

插件传参

new KwaiPlayer('#player-1', {
  plugins: {
    WaterMarkPlugin: false,// 当前实例关闭水印插件
    WaterMarkPlugin: {
      id:'domid'
    }, // 传入domid
  }
}

调用插件

const plugin = player.getPluginInstance('WaterMarkPlugin');
plugin.changePosition(100, 200);

插件实现示例

export default class WaterMarkPlugin extends PluginModule {
  name = 'WaterMarkPlugin';

  private player: KwaiPlayer | undefined;
  private container: HTMLDivElement | undefined;

  beforeInstall(): void {}
  afterInstall(player: KwaiPlayer, options: { domid?: '' }): void {
    this.player = player;
    const main = this.player.getMainContainer();
    const watermark = main?.querySelector(
      options.domid || '[kwai-player-watermark=""]'
    ) as HTMLElement;
    if (watermark) {
      this.container = this.player.createSubContainer();
      this.container?.appendChild(watermark);
    }
  }

  beforeUninstall(player: KwaiPlayer): void {
    this.container && player?.removeSubContainer(this.container);
    this.player = undefined;
    this.container = undefined;
  }
  afterUninstall(): void {}

  changePosition(x, y) {}
}