参数配置

1. 播放界面说明

为了便于说明后续参数的意义，下图展示了一个播放器实例的截图：

播放器主界面

2. 配置概述

在创建zwplayer 对象时，我们需要给zwplayer构造函数传入一个JS对象作为参数，一个拥有比较完整属性的构造函数参数JS对象样本如下（后续新的版本因为功能增强可能会增加成员，但不会减少或修改前面版本定义的属性名称，保证既有API的固化，便于无缝替换升级）

new ZWPlayer({
  // 基础配置
  playerElm: '#player-holder',
  url: 'https://example.com/video.mp4',
  videostyle: "width:100%;height:100%;",
  poster: 'https://example.com/poster.jpg',
  fluid: true,
  ratio: '16:9',
  // 播放控制
  autoplay: true,
  muted: false,
  reconnect: true,
  isLive: false,
  // 控制栏显示按钮
  infoButton: true,
  speedButton: true,
  optionButton: true,
  snapshotButton: true,
  useProgressTooltip: true,
  chapterButton: true,
  enableDanmu: true,
  fixedControlbar: true,
  // 高级功能
  enableDanmu: true,
  thumbnails: {
    url: "http://example.com/thumbnail.jpg",
    width: 128,
    height: 72,
    row: 7,
    col: 7,
    total: 43
  },
  chapters: 'http://example.com/chapters.json',
  logo: {
    icon: 'logo.png',
    dock: 'left',
    x: '5%',
    y: '5%',
    width: '30%',
    height: '30%',
    opacity: 70
  },
  
  // 功能限制
  disablePlayBtn: false,
  disableSeek: false,
  disableFullscreenWin: false,
  disablePicInPic: false,
  disableVolumeControl: false,
  autoSmallWindow: true,
  lostFocusPause: true,
  
  // 回调函数
  onready: function() {
    console.log("Player ready");
  },
  onmediaevent: function(event) {
    // 处理媒体事件
  },
  sendDanmu: function(text) {
    // 发送弹幕
  }
});

zwplayer播放器构造函数参数除playerElm和url是必填外，其他都是可选，请根据具体需要设置即可。

3. 基础配置

3.1 *playerElm - 播放器容器

类型：string | DomObject
默认值: 无
必填
说明：用于指定播放器的停靠元素，应该是一个DIV的ID或者DIV类型的DOM对象。如果传递字符串参数，可以带”#”前缀或者不带”#”，都将被当作元素的ID处理；如果是DOM对象，则该DOM对象必须是DIV类型。如果传递的playerElm不是存在的DOM，则zwplayer会试图创建一个新的DIV类型的DOM元素来作为播放器的停靠点。
示例：'mse'或 '#mse' 或 document.getElementById('mse')

new ZWPlayer({
    playerElm: '#mse',
    ...
});

3.2 *url - 源地址

类型：string | ObjectArray
默认值: 无
必填
说明：媒体流的访问url，为了能让播放器支持强大的功能，同时又为了减少参数的个数，因此该url参数的不仅可以是简单的字符串类型，也可以是JS对象类型。请参见源地址url详解。

new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4'	// 请替换为实际地址
});

3.3 videostyle - 播放器样式

类型： string
默认值： 无
说明： 设置于播放器内建Video对象上的CSS，必须是合规的CSS描述语句。
示例："width:100%;height:100%;"

new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4',
    videostyle: "width:100%;height:100%;",
});

3.4 poster - 海报

类型: String
默认值: 无
说明: 设置海报，即在播放器停止时播放器视频区域显示的图片。

3.5 fluid - 流式布局

类型: Boolean
默认值: false
说明: 设置为流式布局，可使播放器宽度跟随父元素的宽度大小变化，且高度按照配置项中的高度和宽度的比例来变化（播放器宽高未设置时按照内部默认值来计算）。宽高比计算算法如下：

如果设置ratio属性，则ratio属性值为宽高比。
如果未设置ratio属性，则计算width和height的比值得到宽高比。
如果未设置width和height属性，则宽高比为默认值 16:9。

3.6 ratio - 宽高比例

类型: Number | String
默认值: 16:9
说明: 设置播放器的宽高比例，格式为"宽度:高度"，例如"16:9"。启用流式布局时生效。

3.7 width - 宽度

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

3.8 height - 高度

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

配置项（宽高比例）：ratio

参考值：16:9

4. 播放控制

4.1 autoplay - 自动播放

类型: Boolean
默认值: true
说明: 是否自动启动播放。如果设置为false，则播放器必须点击播放按钮才能开始播放。
注意：最新的浏览器限制下，新页面自动播放需配合muted设置为true。
特性：zwplayer已经内建了自动检测功能，如果该参数设置位true，则当播放器尝试打开音频播放失败时，会自动将播放器设置为静音来启动播放，后续用户需要点击开启声音提示按钮来打开声音。

4.2 muted - 静音

类型: Boolean
默认值: false
说明: 播放器是否启动时静音。当前的H5浏览器如果设置为自动播放但不设置为静音，在用户没有交互时将无法自动启动播放。

4.3 reconnect - 断线重连

类型: Boolean
默认值: 无
说明: 播放器是否失败重连。true表示在播放断线后自动重连。在接收直播流时，建议设置为true，这样如果网络故障或者服务器故障，播放器会自动重连。

4.4 isLive - 直播流标志

类型: Boolean
默认值: 无
说明: 指定节目源是否为直播类型的流，直播流不能拖动进度与调节播放速率。对于特定情况下要将一个录播源伪装成直播节目，这个是非常有用的。默认由播放器自动检测是否为直播源。

5. 流媒体协议配置

5.1 streamtype - 流协议类型

类型: String
默认值: 无
说明: 手动指定流协议类型，支持：httpflv、hls、dash、mpegts、webrtc。当直播流地址没有扩展名时必须指定此参数。

特性: zwplayer通过直播流地址扩展名来判断流协议，对应关系为如下：

文件扩展名	对应协议	说明
flv	http-flv	HTTP-FLV流媒体协议
m3u8	HLS	HTTP Live Streaming协议
mpd	DASH	Dynamic Adaptive Streaming over HTTP协议
rtc	Webrtc	Web实时通信协议
ts	mpegts	MPEG传输流协议

但如果直播流地址没有包含扩展名，zwplayer将无法确定用何种协议来播放该流，此时必须手工指定该流的类型。

5.2 useFlv - FLV优先

类型: Boolean
默认值: false
说明: zwplayer支持多协议类型直播节目源对象（用JS对象作为url参数），一个直播节目源可能包含多种类型的流，例如一个多协议直播源可能同时包含webrtc、http-flv、hls、dash等多种传输协议类型，如果将此参数设置为true，zwplayer在检测到节目源类型中包含http-flv流时，会优先采用flv流来播放；否则zwplayer会进行自动决策，选择延时最短的传输类型来播放。

5.3 useOldFlv - 启用FLV旧接口

类型: Boolean
默认值: false
说明: 在播放Flv类型的直播流时，是否采用旧的播放接口，采用旧的Flv播放接口，zwplayer将不能播放内含H265/HEVC的视频流，这个仅仅用于测试兼容性，默认为false。在新的Chrome浏览器（部分Safari浏览器），zwplayer支持内含H265的直播源。

5.4 hasAudio - 是否包含音频流

类型: Boolean
默认值: 无
说明: 指定要播放的流是否包含音频流，如果缺省，则播放器自动判断要播放的URL是否含有音频流。如果要播放的url实际没有包含音频流，但却将hasAudio 设置为true，则播放器在启动播放之前会一直搜索流中的音频流，如果没有搜索到，播放器会一直等待。对于来源于某些监控摄像头的流，可以将该参数设置为false，这样播放器不会搜索音频流，启动播放会快些。

5.5 hasVideo - 是否包含视频流

类型: Boolean
默认值: 无
说明: 指定要播放的流是否包含视频流，如果缺省，则播放器自动判断要播放的URL是否含有视频流。如果要播放的url实际没有包含视频流，但却将hasVideo 设置为true，则播放器在启动播放之前会一直搜索流中的视频流，如果没有搜索到，播放器会一直等待。

5.6 xmc_url - 媒体网关地址

类型: String
默认值: 无
说明: xmc_url 为媒体网关地址。xmc 为 External Media Coprocessor，即外部媒体协处理器(简称：媒体网关)。一些常用的流媒体协议，例如rtsp、udp、rtp等，通过当前浏览器的H5 视频播放是无法播放的，因为目前的H5 无法支持原始socket，所以不能实现这些协议流的获取，一个办法就是采用外部服务器将协议转成http或webrtc协议，这样H5播放器就能播放rtsp、udp、rtp流了。采用xmc，zwplayer支持在浏览器中播放rtsp、udp等直播流，这对于播放当前大多数监控设备厂家的摄像头输出的rtsp流大有帮助。zwplayer支持的协处理协议采用的是websocket协议。详情可以参考播放rtsp流。

6. 控制栏显示配置

6.1 controlbar - 播放器控制条

类型: Boolean
默认值: true
说明: 是否显示播放器控制条，即显示播放器控制条。为了便于用户操作，播放器都会有一个播放控制条，播放控制条里有各种按钮，例如播放、暂停、全屏等。在某些应用场景，不需要播放控制条，可以将该参数设置为false。注意，由于H5浏览器的video标签自带的播放器控制条并不令人满意，所以zwplayer内建了一个自定义的播放器控制条，该控制条在所有浏览器下呈现一致的外观。自定义的播放器控制条上的各种按钮支持配置是否显示。

6.2 nativecontrols - 原生播放控制条

类型: Boolean
默认值: false
说明: 是否用浏览器的原生播放控制条，如果为true，则用浏览器video元素的原生播放控制条，原生播放控制条在不同的浏览器里外观也许不一样，如果需要让用户在不同浏览器下显示一致的外观，请不要设置这个属性为true。设置为false后，zwplayer会创建一个自定义的播放控制条来控制播放，同时禁止原生播放控制条。不建议用原生播放控制条。

6.3 infoButton - 媒体信息按钮

类型: Boolean
默认值: false
说明: 是否在播放控制条上显示媒体信息按钮，播放信息按钮用于显示当前播放的媒体的相关信息。

6.4 speedButton - 播放速率控制按钮

类型: Boolean
默认值: false
说明: 是否在播放控制条上显示播放速率控制按钮，播放速率控制仅对录播节目有效，如果是直播节目，即使设置为true，播放器也不会显示播放速率控制按钮。

6.5 optionButton - 播放器设置按钮

类型: Boolean
默认值: false
说明: 是否在播放控制条上显示播放器设置按钮，如果为true，则播放控制条上会出现一个设置按钮，当鼠标移动到设置按钮上时，会弹出设置菜单。目前可以设置的包括图像旋转，循环播放控制与视频色度调节等功能。后续版本的设置功能可能更丰富。

6.6 snapshotButton - 图像截取按钮

类型: Boolean
默认值: false
说明: 是否在播放控制条上显示图像截取按钮，点击图像截取按钮可以让用户一键截取当前正在播放的视频图像。

6.7 enableDanmu - 弹幕功能

类型: Boolean
默认值: false
说明: 是否启用内建的弹幕显示功能，弹幕作为当前视频播放的交互控制功能已经被各大视频网站所支持。采用zwplayer的弹幕功能，也可以做到与各大视频网站的一样的功能。如果未设置此想，则zwplayer播放器无法显示呈现弹幕。

6.8 useProgressTooltip - 进度条预览图显示

类型: Boolean
默认值: false
说明: 是否启用播放进度条上的提示，如果启用，则当用户鼠标移动到播放进度条上时，会随鼠标指针显示事件提示。对于视频点播节目，如果有缩略图，则必须将此参数设置为true。

6.9 autoSmallWindow - 自动小窗口

类型: Boolean
默认值: false
说明: 窗口滚动将要隐藏播放器时，自动切换成弹出小窗口播放，当页面比较长，有滚动条时，如果用户滚动页面时，会导致zwplayer被滚出页面之外而隐藏，如果将此参数设置为true，则在这种情况发生时，zwplayer自动切换成小窗口播放。注意：小窗口与画中画不一样，画中画是视频小窗口浮出在当前桌面的所有窗口的上面，而小窗口播放是视频小窗口仅在当前浏览器标签页内部，没有浮出。

fixedControlbar - 固定显示控制条

类型: Boolean
默认值: true
说明: 是否总是显示播放控制条，如果设置为false，则播放10秒后，控制条消失。

7. 功能限制配置

7.1 disablePlayBtn - 禁止播放按钮

类型: Boolean
默认值: false
说明: 是否禁止播放按钮，在某些应用情景中，需要用户强制观看某个节目，用户在播放过程中不得暂停，则需将此参数设置为true。如果设置为true，则在视频播放过程中，用户无法通过单击视频、按下Space键、点击播放器工具条上的播放/暂停按钮来暂停播放。

7.2 disableSeek - 禁止拖动进度条

类型: Boolean
默认值: false
说明: 是否禁止在播放过程中拖动进度条，在某些应用情景中，需要用户强制观看完整个某个节目，用户在播放过程中不得前进与后退，则需将此参数设置为true。

7.3 disableFullscreenWin - 禁止网页全屏

类型: Boolean
默认值: false
说明: 是否禁止网页全屏，如果设置为true，则播放器控制条上的网页全拼按钮将不出现，用户不能进入网页全屏模式。网页全屏与普通全屏的区别是网页全屏时播放器仅铺满当前网页，并随网页的缩放而缩放；普通全屏时，播放器占据整个屏幕，并位于所占据的屏幕的最顶层。

7.4 disablePicInPic - 禁止画中画功能

类型: Boolean
默认值: false
说明: 是否禁止画中画功能，如果没有明确指定禁止画中画功能，播放器会自动检测当前浏览器是否支持画中画功能，如果支持并可供调用，则播放器控制条上会出现一个画中画操控按钮，点击此按钮，会将当前视频切换成画中画模式。画中画模式时，用户最小化当前浏览器，该画中画窗口仍旧会位于屏幕上，不会消失。

7.5 disableVolumeControl - 禁止音量控制按钮

类型: Boolean
默认值: false
说明: 是否禁止音量控制按钮，如果设置为true，则播放音量控制按钮不会出现再播放器控制条上，pc平台上，用户无法通过鼠标来控制音量，或进行静音切换，但仍旧可以通过上下箭头键来控制音量。再智能手机上，由于大多数手机已经可以通过手机自带的音量按键来控制音量，因此，可以将本参数设置为true。

7.6 lostFocusPause - 失焦暂停

类型: Boolean
默认值: 无
说明: 窗口失去焦点时暂停播放，当前主流的浏览器在PC平台上都采用标签页的方式来支持多页面访问，用于可以通过标签来切换不同的页面，只有当前位于最前端的页面才获得焦点，其它页面将失去焦点，位于后方。可以通过设置此参数为true来让zwplayer在其页面失去焦点时暂停播放，当页面重获焦点时重启播放。

8. 媒体信息配置

8.1 thumbnails - 进度条预览图参数

类型: Object
默认值: 无
说明: 进度条预览图参数，预览图图为预先抓取的视频缩略图，用于当用于在进度条上移动鼠标时，显示该视频不同时间的预览画面，仅对点播节目有效。该参数是一个js对象，一个有效的thumbnails参数如下：

{
  "url": "https://cdn.zwplayer.cn/media/b44c43c90be3521bc352aad1e80f9cd0_thumb.jpg",
  "width": 160,
  "height": 90,
  "row": 9,
  "col": 9,
  "total": 74
}

详情请参见进度条预览图参数说明

8.2 chapters - 章节标注信息

类型: String | Array
默认值: 无
说明: 节目章节标注信息，chapters 参数可以是字符串，也可以是一个已经分析好的js数组。如果chapters是字符串并且是以http或https开头的，则zwplayer会把该参数当作一个章节的url，在加载时自动从远程下载；如果chapters是以字符“[” 开头的，则会被当作一个JSON数组来进行分析；如果chapters是以WEBVTT开头的，则会当作一个WEBVTT文件来处理。不建议在播放器初始化时设置该参数，推荐的方式时在播放器启动播放后通过 setChapters 方法进行延时加载。由于章节信息的内容比较多，详情请参见章节标注设置说明

8.3 logo - 台标参数

类型: String | Object
默认值: 无
说明: 设置台标。如果输入的是一个字符串，则该字符串标识台标图片的url，为了更多的控制台标，建议用object，object的格式如下：

{
    icon: 'http://example.com/vod/logo.png',
    dock: 'left',
    x: '5%',
    y: '5%',
    width: '20%',
    height: '20%',
    opacity: 70
}

详情请参见 logo设置说明

9. 事件回调配置

9.1 onmediaevent - 媒体事件回调

类型: Function
默认值: 无
说明: 播放器媒体时间回调函数，此参数必须是一个js函数。该函数的原型如下：
```
function onmediaevent(event)
```
其中event为事件参数，该参数是一个js对象，可以通过event.type来区别事件的类型。可能的事件类型包括'play', 'pause', 'seeked', 'ended', 'error'等。

9.2 onready - 播放就绪事件回调

类型: Function
默认值: 无
说明: 播放器创建就绪时触发的事件回调。函数原型如下：
```
function onready()
```

9.3 sendDanmu - 发送弹幕函数

类型: Function
默认值: 无
说明: 发送弹幕函数，函数原型如下：
```
function sendDanmu(text)
```
zwplayer 内建了弹幕输入界面，此弹幕输入界面仅作弹幕输入而不负责发送，通过此界面输入的弹幕必须提供一个发送函数才能发送出去。弹幕发送函数的实现由用户完成，由于zwplayer没有跟任何弹幕后台服务器绑定，开发者需完全实现自己的弹幕服务器或者采用第三方的弹幕服务器。此函数接受一个utf-8字符串参数，该参数实际是一个json字符串，包含弹幕的内容，风格等设置信息。
详情请参见弹幕设置说明

10. 其他配置

10.1 videoElm

类型: String | DomObject
默认值: 无
说明: 用于播放器的视频元素（VIDEO）的ID或者Video类型的DOM对象，如果传入的参数不是一个实际存在的Video对象ID或者DOM对象，则zwplayer播放器会自动创建一个VIDEO对象；如果已经存在，则zwplayer会用这个已经存在的DOM对象来播放视频。建议仅在需要自定义播放器UI时才设置此参数，否则此参数可以忽略。

10.2 logframe

类型: Boolean
默认值: 无
说明: 是否逐帧打印日志。在采用zwplayer的WebAssembly 核心技术时，将该参数设置为true，zwplayer会逐帧打印日志。目前此参数暂不支持。

目录导航