配置

播放器在实例化时的配置选项，开发者可以根据自己的需求进行选择性地配置。

必选配置

选择器 id

类型: String
默认值: ''

播放器实例化的时候需要明确DOM的占位，video将挂载到该DOM下，播放器的尺寸与占位DOM一致，id为容器DOM的id

new Player({
  id:'mse',
  ...
})

容器 el

类型: HTMLElement
默认值: null

播放器容器id也可以用容器元素的DOM来代替，优先级低于id

new Player({
  el: document.querySelector('#mse'),
  ...
})

WARNING

id和el必选一项，播放器才可以初始化，二者同时存在，则id优先于el。

视频源 url

类型: String | Object[]
默认值: ''

URL为数组形式时，会使用Source Tag进行播放

new Player({
  id:'mse',
  url: '//abc.com/**/*.mp4',
  ...
});
// 或者
new Player({
  id:'mse',
  url: [
    {
      src: '//abc.com/**/*.mp4',
      type: 'video/mp4'
    },
    ...
  ],
  ...
});

Note

选择器（或容器）和视频源是播放器关键的配置项，缺一不可。

基础功能配置

width

类型: Number | String
默认值: 600

播放器宽度，传入number类型参数则播放器内部默认添加单位px，传入string类型参数则直接赋值给播放器容器width样式属性

height

类型: Number | String
默认值: 337.5

播放器高度，传入number类型参数则播放器内部默认添加单位px，传入string类型参数则直接赋值给播放器容器height样式属性

autoplay

类型: Boolean
默认值: false

是否自动播放，不是所有场景配置了自动播放都可以成功自动起播的，具体说明请看自动播放相关知识

autoplayMuted

类型: Boolean
默认值: false

是否自动静音自动播放，如果autoplay为false，则该属性的作用为默认静音播放

videoInit

类型: Boolean
默认值: true

是否默认初始化video，当autoplay为true时，该配置为false无效

playsinline

类型: Boolean
默认值: true

是否启用内联播放模式，该配置项只在移动端生效，当设置了该属性为true的时候，将会在初始化video/audio的时候，设置playsinline、webkit-playsinline、x5-playsinline三个属性为true 内联模式相关知识参考

WARNING

iOS10以下系统safari不支持playsinline，默认播放即进入系统全屏

defaultPlaybackRate

类型: Number
默认值: 1

默认起播倍速，参考值0.5/0.75/1/1.5/2

volume

类型: Number
默认值: 0.6

默认音量, 取值范围0 ~ 1

loop

类型: Boolean
默认值: false

是否循环播放

poster

类型: String
默认值: ``

封面图地址

startTime

类型: Number
默认值: 0

初始起播时间，仅点播

videoAttributes

类型: Object
默认值: {}

video扩展属性，初始化的时候会设置在videoElement/audioElement上，具体支持属性请参考Properties

lang

类型: String
默认值: document.documentElement.getAttribute('lang') || navigator.language || 'zh-cn'

播放器初始显示语言，语言包不存在的情况下默认显示'en'语言包，详见i18n

fluid

类型: Boolean
默认值: false

是否启用流式布局，启用流式布局时根据width、height计算播放器宽高比，若width和height不是Number类型，默认使用16:9比例

fitVideoSize

类型: String
默认值: fixed
- fixed 保持容器宽/高，不做适配
- fixWidth 保持容器宽度，适配高度
- fixHeight 保持容器高度，适配宽度
- auto 根据视频溢出宽/高，适配容器宽/高

播放器容器尺寸适配方式，在视频资源初始化之后，根据获取到的videoWidth和videoHeight的比例对播放器容器宽高进行调整

videoFillMode

类型: String
默认值: auto
- fillWidth 填充宽度，高度溢出则裁剪高度
- fillHeight 填充高度，宽度溢出则裁剪宽度
- fill 拉伸填充
- contain 保持宽高比，缩放至一边填满容器，另一边将添加“黑边”
- auto 默认值，同浏览器默认

video画面填充模式

seekedStatus

类型: String
默认值: play
- play 播放
- pause 暂停
- auto 保持操作前的状态

seek操作结束之后播放器的状态，如果取值为auto，则维持原播放状态, 默认是seek之后直接播放

progressDot

类型: Array
默认值: []

播放器进度条故事点信息，具体数据结构如下：

const progressDot = [
  {
    id: 0,         // 唯一标识，用于删除的时候索引
    time: 10,      // 展示的时间点，例子为在播放到10s钟的时候展示
    text: 'Demo',  // hover的时候展示文案，可以为空
    duration: 5,   // 展示时间跨度，单位为s
    style: {       // 指定样式
        backgroundColor: 'red'
    }
  },
  ...
]

thumbnail

类型: Object
默认值: null

进度条预览图配置，该配置会用于pc端进度条帧预览或者是移动端的拖动预览，具体配置信息格式如下：

var thumbnail = {
  urls: [],      // 雪碧图url列表
  pic_num: 128,  // 预览图总帧数
  row: 10,       // 每张雪碧图包含的预览图行数
  col: 10,       // 每张雪碧图包含的预览图列数
  height: 160,   // 预览图每一帧的高度（单位：px）
  width: 90      // 预览图每一帧的宽度（单位：px）
}

marginControls

类型：Boolean
默认值：false

是否开启画面和控制栏分离模式，设置为false，控制栏将会常驻，与视频画面不重叠，两种配置显示具体如下所示

marginControls: false

marginControls: true

domEventType

类型：string, default| touch | mouse
默认值：default

响应的事件类型，通常情况下不需要指定，在绑定事件的时候会校验当前环境是否支持相关事件，一般情况mobile端响应touch类事件，pc端响应mouse类事件

minWaitDelay

类型：number
默认值：200 (ms)

事件waiting延迟响应的阈值，典型场景是：通过这个配置可以不展示短卡顿loading UI。当视频播放到该时间点之后，如果视频播放器的状态仍然是waiting，则会触发waiting事件。可能改变 waiting 事件的触发时机有：canplay、timeupdate、seeked

交互配置

fullscreenTarget

配置名: fullscreenTarget
类型: HtmlElement
默认值: null

全屏按钮生效的dom, 该dom节点必须是播放器容器的父节点，作用的在调用player.getFullscreen() 或者 player.getCssFullscreen() 的时候允许指定全屏的dom; 使用场景如下：

<div class="container">
  <div class="tips">这是一个提示信息</div>
  <div class="video-container" id='vs'></div>
</div>

类似以上dom结构，video-container是播放器容器，我想让tips这个提示信息在播放器全屏/网页全屏的时候也显示，那么就可以如下配置

let player = new Player({
  id: 'vs',
  ...,
  // 将tips和video-container的祖先元素dom作为全屏的触发元素
  fullscreenTarget: document.querySelector('.container')
})

closeFocusVideoFocus

类型: Boolean
默认值: true

是否关闭播放器移动鼠标或者是起播的时触发焦点状态（只在pc端生效）

closePauseVideoFocus

类型: Boolean
默认值: false

是否关闭pause时触发player焦点状态，会强制呼出控制栏

closePlayVideoFocus

类型: Boolean
默认值: false

是否关闭play时触发player焦点状态

closeVideoClick

类型: Boolean
默认值: false

pc端: 是否单击播放器区域切换播放/暂停
mobile端: closeVideoDblclick 为是否通关闭video的click/touchend行为切换播放暂停

closeVideoDblclick

类型: Boolean
默认值: false

pc端: 是否关闭双击播放器进入全屏的能力
mobile端: 是否关闭双击切换暂停/播放的能力

closeDelayBlur

类型: Boolean
默认值: false

关闭播放器自动失焦（只在pc端生效）

inactive

类型: Number
默认值: 3000

播放器focus状态自动消失延迟时长，单位为ms

leavePlayerTime

类型: Number，单位ms
默认值: 3000

用户鼠标离开播放器区域之后，控制栏隐藏延时时间，如果想要鼠标移出播放器区域就隐藏，则配置为0（只在pc端生效）

topBarAutoHide

类型: Boolean
默认值: true

是否自动隐藏播放器容器的顶部边栏（即自定义插件挂载点 ROOT_TOP）

enableContextmenu

类型: Boolean
默认值: false

播放器区域是否允许右键功能菜单

allowSeekAfterEnded

类型: Boolean
默认值: true

播放结束之后是否允许seek

zoom

类型: Number
默认值: 1

缩放值，该配置只在播放器节点或者其父节点css中有zoom配置的时候启用，用来修正zoom产生的计算偏差

插件配置

plugins

类型: array
默认值: []

自定义插件列表，开发者可以将自己开发的插件通过该配置项传入，播放器初始化的时候会将其实例化，并注册在播放器上（开发者可以为播放器传入插件列表以扩展播放器功能）

// 自定义插件
import Aplugin from 'a-xgplayer-plugin'
// 普通传参
new Player({
  el:document.querySelector('#mse'),
  url: '...',
  plugins: [Aplugin]
});

通过pluginConfigs对象，以pluginName作为对象的key值，也可以将参数传递给插件的构造函数

// 自定义插件 pluginName: Aplugin
import Aplugin from 'a-xgplayer-plugin'

new Player({
  el:document.querySelector('#mse'),
  url: '...',
  plugins: [Aplugin],
  Aplugin: { ... }
});

懒加载插件

new Player({
  ...,
  plugins: [{
    loader: () => import('a-xgplayer-plugin'), // 异步加载器，需要bundler(webpack、rollup等)支持
    timeout: 10000, // 插件加载超时时间
    lazy: true, // 标识为懒加载方式
    forceBeforeInit: true // 强制在此插件加载完后开始播放
    options: { ... }
  }]
})

presets

类型: array
默认值: []

自定义preset列表，更多信息请参考preset

ignores

类型: array
默认值: []

禁用内置插件列表, 例如想要禁用内置插件start, 配置如下：

new Player({
  ...,
  ignores: ['start']
})

icons

类型: object
默认值: {}

内置插件按钮配置，可以将内置插件的按钮替换为想要的icon，例如替换start插件的开始按钮在xgplayer 3.0之后的版本中为大家提供了方便的图标替换方式，只需要在配置中传入想要替换的DOM字符串、图片url、DOM节点，均可替换

可替换icon列表，详细列表可查看内置插件icons配置

以播放/暂停按钮的图标替换为例：

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

const player = new Player({
  el:document.querySelector('#mse'),
  icons: {
    play: MyPlayIcon,
    pause: MyPauseIcon
  }
})

注意！项目中传给播放器的svg需要通过webpack处理成字符串形式引入，推荐使用：raw-loader

i18n

类型: Array<Object>
默认值: [] 内置文本语言扩展，相对于静态配置I18N.use(xx)，该配置项只在当前实例生效，I18N.use(xx)则会在所有实例生效, 使用方式如下

const player = new Player({
  ...,
  i18n:[{
    LANG: 'en', // 要定义的语言
    // 文本语言
    TEXT: {
      HAVE_NOTHING:'没有关于音频/视频是否就绪的信息', // 如果内置已经有该文本的定义，则直接覆盖， 没有则扩展
      ...
    }
  }]
})

commonStyle

类型: object
默认值: {}

一些关键点颜色配置, 具体说明如下:

{
  // 进度条底色
  progressColor: '',
  // 播放完成部分进度条底色
  playedColor: '',
  // 缓存部分进度条底色
  cachedColor: '',
  // 进度条滑块样式
  sliderBtnStyle: {},
  // 音量颜色
  volumeColor: ''
}

controls

类型: Boolean/object
默认值: true

true/false决定是否使用底部控制栏，也可以赋值为一组控制栏插件的配置项，具体使用方式请看internalPlugins -> controls

miniprogress

类型: Boolean
默认值: false

是否启用mini进度条，该选项为true，在控制栏隐藏的时候会在底部显示一个迷你进度条

screenShot

类型: Boolean
默认值: false

是否使用截图插件，该配置项为截图按钮快捷启动配置，也可以传入一组截图插件的配置项，具体使用方式请看internalPlugins -> screenShot

rotate

类型: Boolean
默认值: false

是否使用旋转插件，该配置项为旋转插件快捷启动配置，也可以传入一组配置项，更多配置和API请看internalPlugins -> rotate

download

类型: Boolean
默认值: false

是否使下载按钮，该配置项为下载按钮快捷启动配置，也可以传入一组配置项，更多配置和API请看internalPlugins -> download

pip

类型: Boolean
默认值: false

是否使用画中画插件，该配置项为控制栏上画中画按钮的启动配置，也可以传入一组配置项，更多配置和API请看internalPlugins -> pip

mini

类型: Boolean
默认值: false

是否启用mini小窗插件，该配置仅仅为控制栏上小窗的按钮的启动配置，小窗插件更多的配置和API请看internalPlugins -> miniscreen

cssFullscreen

类型: Boolean | {}
默认值: false

是否使用网页样式全屏按钮开关，也可以传入一组配置项，更多插件配置和API请看internalPlugins -> cssfullscreen

playbackRate

类型: Boolean | array | {}
默认值: [0.5, 0.75, 1, 1.5, 2]

倍速插件显示列表，当改配置为false的时候，相当于禁用倍速切换插件，也可以传入一组配置项，更多配置和API请看internalPlugins -> playbackrate

keyShortcut

类型: Boolean
默认值: true

是否开启快捷键，该配置项用于快捷键功能的开关，具体快捷键的实现请看internalPlugins -> keyboard

微信专用配置

详情可参考X5内核视频

微信同层播放

配置项：x5-video-player-type
默认值：''
参考值：'h5'

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-type': 'h5'
});

微信全屏播放

配置项：x5-video-player-fullscreen
默认值：''
参考值：true | false

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-player-fullscreen': false
});

微信横竖屏控制

配置项：x5-video-orientation
默认值：''
参考值：'landscape' | 'portraint'
- 'landscape' 横屏
- 'portraint' 竖屏

new Player({
  el:document.querySelector('#mse'),
  url: 'video_url',
  'x5-video-orientation': 'portraint'
});

西瓜播放器 HTML5 video video.js 播放器 HTML5播放器 mp4 hls hls.js flv flv.js dash dash.js 无缝切换

# 配置

# 必选配置

# 选择器 id

# 容器 el

# 视频源 url

# 基础功能配置

# width

# height

# autoplay

# autoplayMuted

# videoInit

# playsinline

# defaultPlaybackRate

# volume

# loop

# poster

# startTime

# videoAttributes

# lang

# fluid

# fitVideoSize

# videoFillMode

# seekedStatus

# progressDot

# thumbnail

# marginControls

# domEventType

# minWaitDelay

# 交互配置

# fullscreenTarget

# closeFocusVideoFocus

# closePauseVideoFocus

# closePlayVideoFocus

# closeVideoClick

# closeVideoDblclick

# closeDelayBlur

# inactive

# leavePlayerTime

# topBarAutoHide

# enableContextmenu

# allowSeekAfterEnded

# zoom

# 插件配置

# plugins

# presets

# ignores

# icons

# i18n

# commonStyle

# controls

# miniprogress

# screenShot

# rotate

# download

# pip

# mini

# cssFullscreen

# playbackRate

# keyShortcut

# 微信专用配置

# 微信同层播放

# 微信全屏播放

# 微信横竖屏控制

配置