插件说明

VePlayer 支持通过插件实现所有功能，包括简单的功能按钮、播放控制以及复杂的播放逻辑等。本文将介绍插件的注册、禁用和配置方法。

适用版本

本文档适用于 2.1.0 版本的 Web 拉流 SDK，其他版本请参考历史文档。

自定义插件

注册插件

VePlayer 支持在初始化时注册和初始化之后注册 2 种注册插件的方式。

方法一：在初始化时注册

在初始化 VePlayer 实例时，您可以直接传入插件名称来注册插件（内置插件无需注册），代码示例如下所示。

VePlayer.createLivePlayer({
  width: 640,
  height: 360,
  url: 'https://testpull.mycloud.com/live/mystream.m3u8',
  plugins: [window.VePlayerTimeShift],
  logger: {
    appId: '5****8',
  },
});

方法二：在初始化后注册

您可以在初始化完成之后，调用 registerPlugin 方法并传入插件名称来注册插件（内置插件无需注册），代码示例如下所示。

VePlayer.createLivePlayer({
  //...
}).then(function(veplayer){
	veplayer.registerPlugin(window.VePlayerTimeShift)      	
})

禁用插件

VePlayer 内置了一些常用的功能插件。如您需要禁用某个内置插件，可以使用以下方法。

• 对于大部分插件，您可以将插件名称（不区分大小写）传入 VePlayer 配置项的 ignores 属性来进行禁用。以禁用画中画插件为例，代码示例如下所示。

  ignores: ['pip']
  

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

配置插件

VePlayer 允许您传入各个插件的名称来配置插件的具体逻辑。例如，配置报错插件的相关参数。

error: {
   errorTipsText: '报错信息', // 报错展示的信息
   showRefresh: true, // 是否需要刷新按钮
}

替换插件图标

您可以通过配置来替换内置插件的按钮图标，支持替换图标的插件列表可参见内置插件图标配置。例如，将播放/暂停按钮的图标替换为自定义的图标，只需在配置中传入所需替换的图片 URL 或 DOM 节点即可，代码示例如下所示。

import MyPlayIcon from '../icons/my-play-icon.svg';
import MyPauseIcon from '../icons/my-pause-icon.svg';

VePlayer.createLivePlayer({
  icons: {
    play: <img src={MyPlayIcon}>,
    pause: <img src={MyPauseIcon}>
  }
})

内置插件

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

含 UI 的内置插件

controls: false,

// 或
controls: {
  disable: true,
}

fullscreen: false

// 或
fullscreen: {
  disable: true
}

pip: false

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

配置挂载位置

插件配置项 position 可用于指定插件在用户界面中的位置，即将插件的 UI 元素挂载到特定的 DOM 节点上。VePlayer 定义了以下两种位置。

• 默认布局：插件的 UI 元素按照预设的布局方式进行排列和展示。

  

• flex 布局：一种灵活的布局方式，可以根据屏幕大小和需求自动适应 UI 元素的排列方式。

  

  说明

  • 如果没有指定 position 参数或者 root 参数，插件的 UI 元素会默认挂载在根节点 root 下。这意味着插件会出现在默认的位置。
  • 在播放器失去焦点时，位于 ROOT_TOP、ROOT_RIGHT 和 ROOT_LEFT 位置的插件会自动隐藏。这可以提供更好的用户体验，避免干扰用户观看视频内容。
  • 对于手机小屏幕的情况下，使用 Flex 布局时，中间位置的插件会自适应屏幕大小，通常用于展示进度条等功能。这样可以确保在有限的屏幕空间中，合理地展示插件的功能。

配置布局模式

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

• normal：普通布局方式，控制栏中的各个插件按照配置的顺序排列显示。
  

• flex：使用 Flex 布局方式，可以灵活地调整控制栏中各个插件的位置和大小，使其适应不同的屏幕尺寸和布局要求。

  

• bottom：底部布局方式，将控制栏放置在播放器底部，适合在移动设备上显示，提供更好的触控操作体验。

  

配置索引

插件配置项 index 是一个数字值，用于确定插件在父节点中的位置。数字越小，插件在父节点中的位置越靠前。当多个插件具有相同的 index 值时，它们的插入顺序将按照注册的顺序进行。通过调整插件的 index 值，可以优化插件的显示顺序，以满足特定的需求和布局要求。

不含 UI 的内置插件

内置插件图标