参数配置

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,
  defVolume: 61.25,
  hideControlbarTimeout: 10000,
  // 高级功能
  enableDanmu: true,
  castButton: true,
  zoomButton: true,
  annotationButton: true,
  thumbnails: {
    url: "http://example.com/thumbnail.jpg",
    width: 128,
    height: 72,
    row: 7,
    col: 7,
    total: 43
  },
  chapters: 'http://example.com/chapters.json',
  annotations: 'http://example.com/annotations/movie_annotation.json',
  subtitles: 'http://example.com/subtitles/movie.vtt',
  playlistButton: true,
  playlist: {
    url: 'http://example.com/playlist/my_playlist.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 | Object
默认值: 无
必填
**说明：**媒体流的访问地址，支持以下几种传入方式：
- 字符串 URL：直接传入视频地址（MP4、HLS、FLV、DASH、WebRTC 等）。
- JS 对象：传入包含丰富配置的对象，用于同时设置视频、缩略图、章节、标注、字幕、播放列表等。请参见源地址url详解。

// 方式一：简单字符串
new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4'
});

// 方式二：JS 对象（支持同时配置多种资源）
new ZWPlayer({
    playerElm: '#mse',
    url: {
      src: 'https://example.com/video.mp4',
      thumbnails: 'https://example.com/thumbnails/movie_thumbnail.json',
      chapters: 'https://example.com/chapters/movie_chapter.json',
      annotations: 'https://example.com/annotations/movie_annotation.json',
      subtitles: 'https://example.com/subtitles/movie.vtt'
    }
});

// 方式三：传入 ZWMAP 播放列表 JSON URL（播放器自动识别）
new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/playlist/my_playlist.json'
});

// 方式四：直接传入 ZWMAP 播放列表 JSON 对象（无需托管文件）
new ZWPlayer({
    playerElm: '#mse',
    url: {
      zwp_protocol: 'ZWMAP/1.0',
      zwp_type: 'playlist',
      title: '我的播放列表',
      groups: [
        {
          name: '分组一',
          items: [
            { name: '视频1', url: 'https://example.com/video1.mp4' }
          ]
        }
      ]
    }
});

播放列表（Playlist）

url 参数支持两种方式传入播放列表：

JSON 文件 URL：指向一个符合 ZWMAP 协议的 .json 文件，播放器自动识别并加载。
内联 JSON 对象：直接将 ZWMAP 播放列表对象作为 url 参数传入，无需额外托管文件，适用于动态生成的播放列表。

播放器会自动识别 zwp_type: "playlist" 并按播放列表模式加载，无需额外配置。播放器会自动渲染分组列表 UI、支持自动播放下一项、记忆播放进度和收藏。

播放列表 JSON 必须符合 ZWMAP 协议的播放列表类型（zwp_type: "playlist"），支持分组结构和每个视频项的关联资源。

ZWMAP 播放列表 JSON 示例：

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "zwp_version": "1.0",
  "id": "demo_list_001",
  "title": "演示播放列表",
  "autoPlayNext": true,
  "groups": [
    {
      "id": "g1",
      "name": "教学视频",
      "expanded": true,
      "items": [
        {
          "id": "v1",
          "name": "第一课：基础入门",
          "url": "https://cdn.example.com/video/lesson1.mp4",
          "type": "mp4",
          "poster": "https://cdn.example.com/poster/lesson1.jpg",
          "subtitle": "https://cdn.example.com/sub/lesson1.vtt",
          "chapter": "https://cdn.example.com/chapter/lesson1.json",
          "annotation": "https://cdn.example.com/annotation/lesson1.json",
          "thumbnails": "https://cdn.example.com/thumbnail/lesson1.json"
        },
        {
          "id": "v2",
          "name": "第二课：进阶内容",
          "url": "https://cdn.example.com/video/lesson2.mp4",
          "type": "mp4",
          "subtitle": [
            "https://cdn.example.com/sub/lesson2_zh.vtt",
            "https://cdn.example.com/sub/lesson2_en.vtt"
          ]
        }
      ]
    },
    {
      "id": "g2",
      "name": "直播频道",
      "expanded": false,
      "items": [
        {
          "id": "live1",
          "name": "CCTV-1",
          "url": "https://live.example.com/cctv1.flv",
          "type": "flv",
          "isLive": true
        }
      ]
    }
  ]
}

播放列表字段说明：

字段	类型	必填	说明
`zwp_protocol`	string	是	协议标识，固定 `"ZWMAP/1.0"`
`zwp_type`	string	是	固定 `"playlist"`
`id`	string	否	播放列表唯一标识符，用于隔离进度和收藏
`title`	string	否	播放列表标题
`groups`	array	是	分组数组，每个分组包含 `name`、`expanded`、`items`

视频项（VideoItem）字段：

字段	类型	必填	说明
`url`	string	是	视频 URL
`name`	string	否	视频显示名称
`type`	string	否	视频类型：`mp4`/`hls`/`dash`/`flv`/`webrtc`/`auto`（默认）
`isLive`	boolean	否	是否直播流，默认 `false`
`poster`	string	否	海报图片 URL
`subtitle`	string \| array	否	字幕文件 URL，支持单个或数组（多语言字幕）
`chapter`	string	否	章节 JSON 文件 URL
`annotation`	string	否	交互标注 JSON 文件 URL
`thumbnails`	string	否	缩略图 JSON 文件 URL
`epg_now`	string	否	当前节目名称（EPG 信息）

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，则在 hideControlbarTimeout 设定的超时时间后，控制条自动隐藏。

6.11 timeFormat - 时间显示格式

类型: String
默认值: 's'
说明: 控制播放器控制栏上时间码的显示精度。's' 显示到秒（如 01:30），'ms' 显示到毫秒（如 01:30.500）。适用于需要精确时间定位的场景，如字幕编辑、视频标注等。

new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4',
    timeFormat: 'ms'  // 显示毫秒精度: 00:01:30.500
});

6.12 defVolume - 默认音量

类型: Number
默认值: 61.25
说明: 播放器启动时的默认音量百分比，取值范围 0–100。播放器会记住该值，用户通过界面调节音量后会覆盖此默认值。

6.13 hideControlbarTimeout - 控制栏自动隐藏超时

类型: Number
默认值: 10000
说明: 控制栏自动隐藏的超时时间，单位为毫秒。当 fixedControlbar 设置为 false 时，播放器在用户无操作超过此时间后自动隐藏控制栏。默认 10 秒。

6.14 castButton - 投屏按钮

类型: Boolean
默认值: false
说明: 是否在播放控制条上显示投屏按钮。投屏功能使用浏览器原生的 Cast API（如 Chromecast、AirPlay），可将当前视频投射到支持的设备上播放。仅在浏览器支持投屏协议时按钮才会显示。

6.15 zoomButton - 放大镜按钮

类型: Boolean
默认值: false
说明: 是否在播放控制条上显示放大镜按钮。启用后，用户可以点击放大镜按钮进入放大模式，通过鼠标滚轮或拖拽来放大视频画面的局部细节，适用于教学演示、医疗影像等需要观察细节的场景。

6.16 annotationButton - 标注编辑按钮

类型: Boolean
默认值: 当配置了 annotations 属性时默认为 true，否则为 false
说明: 是否在播放控制条上显示标注编辑按钮。该按钮用于打开在线标注编辑器，对当前视频的交互标注进行可视化编辑。仅在配置了 annotations 参数时才会显示此按钮，可通过显式设置为 false 来禁用。

6.17 localPlayback - 本地文件播放

类型: Boolean
默认值: false
说明: 是否启用本地视频/音频文件播放功能。当设置为true时，播放器将显示一个文件选择按钮，用户可以通过点击按钮选择本地文件或直接拖拽文件到播放器区域来播放。
功能特性:
- 支持拖拽上传：用户可以直接将视频/音频文件拖拽到播放器区域
- 文件选择按钮：显示文件图标，点击后弹出文件选择对话框
- 智能MIME类型检测：自动识别文件格式，确保准确播放
- 支持格式：MP4, WebM, MOV, MKV, M4V, OGG, FLAC, WAV, M4A, MP3, OPUS 等浏览器原生支持的格式
- 提示界面：当没有加载视频时，显示友好的提示信息引导用户选择文件

6.18 segmentButton - 片段选择功能

类型: Boolean
默认值: false
说明: 是否启用片段选择功能按钮。该功能允许用户选择视频中的特定片段进行循环播放；如果在录制时选择了片段，则只会录制该片段的内容
功能特性:
- 拖拽分段：可通过进度条上的滑块拖动片段起止时间点，操作方便
- 时间标记：毫秒级显示片段的开始和结束时间
- 直播限制：仅在非直播模式下可用（isLive为true时，片段选择功能不激活）
- 片段循环：支持在选定的片段内循环播放
使用场景: 适用于教学视频、会议录制等需要重点观看特定时段内容的场景

6.19 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 | String
默认值: 无
说明: 进度条预览图参数，预览图为预先抓取的视频缩略图，用于当用户在进度条上移动鼠标时，显示该视频不同时间的预览画面，仅对点播节目有效。支持以下三种传入方式：

方式一：直接传入对象

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

方式二：传入 ZWMAP JSON 对象

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "thumbnail",
  "zwp_version": "1.0",
  "thumbnail": {
    "url": "thumbnail.jpg",
    "width": 160,
    "height": 90,
    "col": 10,
    "row": 10,
    "total": 100
  }
}

方式三：传入 JSON URL 地址

thumbnails: 'http://example.com/thumbnails/movie_thumbnail.json'

此外，也支持将缩略图 JSON 文件和雪碧图图片直接拖拽到播放器上加载，播放器会自动按文件名匹配视频与缩略图。详情请参见进度条预览图参数说明

8.2 chapters - 章节信息

类型: String | Array | Object
默认值: 无
说明: 节目章节信息。支持以下传入方式：
- URL 字符串：以 http 或 https 开头，zwplayer 会自动从远程下载解析。
- JSON 字符串：以 [ 开头，会被当作 JSON 数组解析。
- WEBVTT 字符串：以 WEBVTT 开头，按 WEBVTT 格式解析。
- ZWMAP JSON 对象：直接传入包含 zwp_type: “chapter” 的 ZWMAP 协议对象。
- JS 数组：传入已解析好的章节数组。
也支持 chapter（单数）属性名，播放器内部会自动归一化。

不建议在播放器初始化时设置该参数，推荐的方式是在播放器启动播放后通过 setChapters 方法进行延时加载。详情请参见章节设置说明
章节搜索功能：加载章节后，在播放器设置菜单中点击”章节搜索”按钮，可打开章节搜索面板。输入关键词即可实时过滤匹配的章节条目，点击搜索结果可跳转到对应时间点。支持按章节标题和描述内容进行搜索。
按章节循环播放：在章节搜索面板中，每个章节条目右侧有一个循环按钮。点击后，播放器将在该章节的时间范围内循环播放，再次点击取消循环。适用于教学场景中反复观看某个片段。

8.3 chapterButton - 章节菜单按钮

类型: Boolean
默认值: 无（加载章节后自动启用）
说明: 控制是否在控制条时间显示区附近显示章节菜单按钮。设为 false 时，进度条上的章节标记仍然正常显示，仅隐藏菜单按钮；章节数据的加载不受此参数影响。

8.4 annotations - 交互标注信息

类型: String | Object
默认值: 无

说明: 视频交互标注（热区）配置，用于在视频画面上叠加可交互节点，支持点击跳转、测验、投票、表单等交互类型。支持以下传入方式：

方式一：传入 ZWMAP JSON URL

annotations: 'https://cdn.example.com/annotations/movie_annotation.json'

方式二：传入 ZWMAP JSON 对象

annotations: {
  “zwp_protocol”: “ZWMAP/1.0”,
  “zwp_type”: “annotation”,
  “nodes”: [
    {
      “id”: “node1”,
      “type”: “button”,
      “name”: “Click Me”,
      “time_range”: { “start”: 5, “end”: 15 },
      “position”: { “x”: 40, “y”: 40, “w”: 20, “h”: 10 },
      “events”: [{ “trigger”: “click”, “actions”: [{ “type”: “SEEK_TIME”, “target”: 30 }] }]
    }
  ]
}

也支持 annotation（单数）属性名，播放器内部会自动归一化。此外，支持将标注 JSON 文件直接拖拽到播放器上加载，播放器会自动按文件名（*_annotation.json）匹配视频。可通过 loadAnnotations(url) 和 unloadAnnotations() 方法在运行时动态加载和卸载。

8.4 subtitles - 外挂字幕

类型: String | Array
默认值: 无
说明: 外挂字幕配置，支持 VTT、SRT、BCC（Bilibili JSON）格式。支持以下传入方式：
- URL 字符串：传入单个字幕文件地址。
- 数组：传入多个字幕轨道，每个元素可以是 URL 字符串或包含 url 和 title 的对象。
```
// 单个字幕
subtitles: 'https://cdn.example.com/subtitles/movie.vtt'

// 多语言字幕
subtitles: [
  { url: 'movie_zh.vtt', title: '中文' },
  { url: 'movie_en.vtt', title: 'English' }
]
```
也可通过 addSubtitle(url, pos, title) 方法在运行时动态添加字幕轨道。
字幕搜索功能：加载字幕后，在播放器设置菜单中点击"字幕搜索"按钮，可打开字幕搜索面板。输入关键词即可实时过滤匹配的字幕条目，显示时间戳和内容。单击搜索结果可跳转到对应时间点，双击可直接定位并播放。搜索结果会随播放进度自动高亮当前字幕。
字幕翻译功能：在播放器设置菜单中点击"字幕翻译"按钮，可打开字幕翻译面板。选择目标语言后，播放器会将当前字幕发送到翻译服务进行翻译，翻译完成后在原字幕下方叠加显示翻译内容，支持实时跟随播放进度同步显示。需要配置 translateApi 参数指定翻译服务地址。

8.5 translateApi - 字幕翻译服务地址

类型: String
默认值: 无

说明: 字幕翻译 API 的服务端地址。配置后，用户可在字幕翻译面板中选择目标语言，播放器会自动将当前字幕内容以 SRT 格式通过 POST 请求发送到该地址，翻译完成后在视频上叠加显示翻译字幕。

请求格式：POST 请求，multipart/form-data 编码，包含以下字段：

字段	类型	说明
`file`	File	原始字幕文件（SRT 格式）
`targetLang`	string	目标语言（如 `"中文"`、`"英语"`、`"日语"` 等）
`outputFormat`	string	输出格式，固定 `"srt"`

响应格式：服务端应返回翻译后的 SRT 内容（纯文本或 JSON）。

支持的目标语言：中文、英语、日语、韩语、法语、德语、西班牙语、俄语、葡萄牙语。未指定目标语言时，默认根据浏览器语言自动选择。

new ZWPlayer({
    playerElm: '#mse',
    url: 'https://example.com/video.mp4',
    subtitles: 'https://example.com/subtitles/movie_en.vtt',
    translateApi: 'https://api.example.com/translate'
});

8.6 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设置说明

8.7 watermarks - 水印参数

类型: String | Array | Object
默认值: 无
说明: 设置视频水印，支持图片水印、文字水印、动态游走水印和铺满水印，常用于品牌标识、版权声明和防录屏保护。支持以下输入方式：
- URL 字符串：以 http 或 https 开头，指向 ZWMAP JSON 文件地址，播放器自动下载解析。
- ZWMAP JSON 对象：包含 zwp_type: "watermark" 的协议对象。
- 水印数组：直接传入水印条目数组。
也可以在播放器初始化后通过 setWatermarks 方法延迟加载。

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://cdn.example.com/video.mp4',
    watermarks: [
        {
            type: 'image',
            icon: 'https://example.com/watermark.png',
            dock: 'bottom-right',
            x: '5%',
            y: '5%',
            width: 120,
            opacity: 40
        },
        {
            type: 'text',
            text: '{user_id} {sys_time}',
            font_size: 14,
            font_color: 'rgba(255,255,255,0.3)',
            behavior: 'dynamic',
            dock: 'center'
        }
    ],
    variables: {
        user_id: '138****1234'
    }
});

详细的水印数据结构和行为模式说明请参见水印设置

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