参数配置

1. 播放界面说明

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

zwplaye播放器主界面，显示播放器完整界面，包括播放控制按钮、状态显示区、进度条、播放进度指示、播放器控制条、播放器控制条按钮、预览缩略图、大播放按钮等

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样式属性。

3.9 lang - 语言设置

类型: String
默认值: 根据浏览器界面语言自动检测，如果是中文，则为中文，否则为英文。
说明: 设置播放器的界面语言。支持多语言本地化，影响播放器控制栏、提示信息、菜单等所有文本内容。
支持语言:

'zh-CN' 或 'zh': 简体中文
'en-US' 或 'en': 英语

4. 播放控制

4.1 autoplay - 自动播放

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

4.2 disableMutedConfirm - 禁用自动播放静音提示框

类型: Boolean
默认值: true
说明: 是否禁用因浏览器自动播放策略触发的静音确认模态框。
详细行为：当播放器的 autoplay 属性设置为 true 时，zwplayer 会尝试自动开始播放。然而，现代浏览器的自动播放策略通常要求视频在用户与页面交互后才能播放带声音的内容。为应对此策略并提供无缝体验，zwplayer 内建了自动检测机制：

· 检测与降级：如果因浏览器策略导致带声音的自动播放失败，播放器会自动将视频设置为静音状态并开始播放。
· 用户提示（默认行为）：随后，播放器会弹出一个模态提示框，向用户说明：“因浏览器限制，视频已静音播放，请点击画面开启声音。” 此提示框需要用户手动点击关闭，以确保用户知晓当前无声音的状态，避免产生困惑。

disableMutedConfirm 属性用于控制此提示框的显示：

· 当设置为 false（默认值）时，上述模态提示框会正常显示。
· 当设置为 true 时，将禁用该模态提示框。即使因策略限制转为静音播放，也不会弹出任何需要交互的提示。

适用场景建议：

· 设置为 true：适用于追求极致沉浸式、无中断体验的场景，例如背景视频、广告、或无需音频的视频展示。开发者需自行通过UI或其他方式告知用户静音状态。
· 保持 false（默认）：适用于需要明确告知用户当前状态、避免用户因突然无声而感到困惑的通用视频播放场景，如新闻、教育、主站播放器等，能有效提升用户体验的清晰度。

4.3 muted - 静音

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

4.4 reconnect - 断线重连

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

4.5 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自动切换成小窗口播放。注意：小窗口与画中画不一样，画中画是视频小窗口浮出在当前桌面的所有窗口的上面，而小窗口播放是视频小窗口仅在当前浏览器标签页内部，没有浮出。

6.10 fixedControlbar - 固定显示控制条

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

6.11 localPlayback - 本地文件播放

类型: Boolean
默认值: false
说明: 是否启用本地视频/音频文件播放功能。当设置为true时，播放器将显示一个文件选择按钮，用户可以通过点击按钮选择本地文件或直接拖拽文件到播放器区域来播放。
功能特性:

支持拖拽上传：用户可以直接将视频/音频文件拖拽到播放器区域
文件选择按钮：显示文件图标，点击后弹出文件选择对话框
智能MIME类型检测：自动识别文件格式，确保准确播放
支持格式：MP4, WebM, MOV, MKV, M4V, OGG, FLAC, WAV, M4A, MP3, OPUS 等浏览器原生支持的格式
提示界面：当没有加载视频时，显示友好的提示信息引导用户选择文件

6.12 segmentButton - 片段选择功能

类型: Boolean
默认值: false
说明: 是否启用片段选择功能按钮。该功能允许用户选择视频中的特定片段进行循环播放；如果在录制时选择了片段，则只会录制该片段的内容
功能特性:

拖拽分段：可通过进度条上的滑块拖动片段起止时间点，操作方便
时间标记：毫秒级显示片段的开始和结束时间
直播限制：仅在非直播模式下可用（isLive为true时，片段选择功能不激活）
片段循环：支持在选定的片段内循环播放

使用场景: 适用于教学视频、会议录制等需要重点观看特定时段内容的场景

6.13 recordButton - 录制功能

类型: Boolean
默认值: false
说明: 是否启用视频录制功能。当设置为true时，播放器控制栏将显示录制按钮，用户可以录制当前播放的视频内容，也可以仅提取音频。
功能特性:

录制按钮：显示录制图标，点击开始/停止录制
录制设置：在选项菜单中提供录制配置选项，选项有：始终询问、完整录制，仅提取音频
状态指示：录制时按钮会显示不同状态，如果完整录制显示红点指示器，仅录制音频显示绿点指示器。
录制格式：完整录制格式为mp4，仅录制音频格式为m4a
录制保存：停止录制后，录制文件自动下载保存到本地

技术要求: 推荐使用chrome引擎的浏览器，部分浏览器可能支持受限。

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会逐帧打印日志。目前此参数暂不支持。

目录导航