ZWPlayer 章节功能使用说明

1. 功能概述

ZWPlayer 支持为视频文件添加章节功能，特别适用于教学视频等需要按知识点导航的场景。通过预设的章节标记，用户可以快速跳转到特定知识点进行学习。

界面如下图所示：

成功设置章节信息后：

1. 进度条标记：播放器进度条上会显示章节标志

2. 章节菜单：控制条时间显示区附近会出现章节菜单按钮，点击章节按钮弹出章节列表，点击某一章节，跳转到该位置开始播放。chapterButton 参数仅控制此按钮的显示与否，不影响章节数据的加载和进度条标记。

3. 章节搜索：在播放器设置菜单中点击"章节搜索"按钮，输入关键词可实时按标题或描述筛选章节，点击搜索结果跳转到对应时间点。

4. 章节循环：在章节搜索面板中，每个章节右侧有循环按钮，点击后在该章节时间范围内循环播放。

2. 配置参数

2.1 chapters - 章节数据（属性）

• 类型：String | Array | Object

• 默认值：无

• 说明：在播放器初始化时通过构造函数传入章节数据，支持以下输入方式：

  • URL 字符串：以 http 或 https 开头的远程章节文件地址，播放器自动下载解析
  • ZWMAP JSON 对象：包含 zwp_type: "chapter" 的协议对象
  • 章节数组：已解析的章节条目数组

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://cdn.example.com/video.mp4',
    chapters: 'https://cdn.example.com/chapters/movie_chapter.json'
});

也可以在播放器初始化后通过 setChapters 方法延迟加载（见第 3 节）。

2.2 chapterButton - 章节菜单按钮

• 类型：Boolean

• 默认值：无（加载章节时自动启用）

• 说明：控制控制条时间显示区附近的章节菜单按钮是否显示。

  • 设为 false 时：进度条上的章节标记照常显示，仅隐藏菜单按钮。章节数据的加载不受此参数影响。
  • 设为 true 或省略时：加载章节数据后自动显示菜单按钮。

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://cdn.example.com/video.mp4',
    chapterButton: false, // 隐藏菜单按钮，但进度条标记正常显示
    chapters: 'https://cdn.example.com/chapters/movie_chapter.json'
});

3. 设置章节信息（方法）

使用 setChapters 方法加载章节信息，建议在视频文件加载完成后调用此方法。

3.1 方法签名

player.setChapters(chapters);

3.2 参数类型

chapters 参数支持以下三种格式：

1. 包含章节内容的大字符串（JSON 或 VTT 格式）
2. 已解析的 js 数组
3. 章节文件的 HTTP 地址

chapters 参数可以是字符串，也可以是一个已经分析好的js数组。zwplayer会根据参数的内容自动识别并加载章节信息。

4. 章节数据格式

4.1 ZWMAP JSON 格式（推荐）

ZWMAP（ZWPlayer 媒体应用协议）是 zwplayer 定义的标准 JSON 格式，导出文件命名为 {视频标题}_chapter.json。格式如下：

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "chapter",
  "zwp_version": "1.0",
  "chapters": [
    {
      "title": "三角形知识点",
      "start_time": "00:01:04.000",
      "desc": "介绍三角形的性质，全等，与附加知识",
      "style": { "background": "blue" }
    },
    {
      "title": "四边形知识",
      "start_time": "00:02:04.000",
      "desc": "介绍四边形的性质，全等，与附加知识",
      "style": { "background": "green" }
    }
  ]
}

ZWMAP 协议附加字段：

章节数组中每个对象的属性：

4.2 旧版 JSON 格式（兼容）

章节文件也可以使用 zwplayer 定义的旧版裸数组格式：

[
  {
    "title": "三角形知识点",
    "desc": "介绍三角形的性质，全等，与附加知识",
    "time": "01:04",
    "duration": 60,
    "style": {
      "background": "blue"
    },
    "image": null
  },
  {
    "title": "四边形知识",
    "desc": "介绍四边形的性质，全等，与附加知识",
    "time": "02:04",
    "duration": 50,
    "style": {
      "background": "green"
    },
    "image": null
  }
]

旧版格式与 ZWMAP 格式的字段对应关系：

4.3 VTT 格式（WEBVTT）

如果章节数据以 WEBVTT 开头，zwplayer 会自动按 VTT 格式解析。 具体参看VTT格式说明

5. 自动识别规则

zwplayer 根据参数内容自动识别章节格式：

• HTTP/HTTPS 开头：作为远程章节文件 URL 自动下载
• 对象且含 zwp_type: "chapter"：按 ZWMAP 协议格式解析，提取 chapters 数组
• “[” 开头：作为 JSON 数组解析
• “WEBVTT” 开头：作为 WEBVTT 文件处理

6. 使用示例

示例 1：通过 URL 加载章节

// 初始化播放器
window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    chapterButton: true, // 启用章节按钮
});

// 延迟加载章节信息
setTimeout(function () {
    if (window.mainplayer) {
        window.mainplayer.setChapters('http://example.com/chapters/movie_chapter.json');
    }
}, 200);

示例 2：通过 chapters 属性配置

window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    chapterButton: true,
    chapters: 'http://example.com/chapters/movie_chapter.json'
});

示例 3：通过 Ajax 加载并传递数组

// 初始化播放器
window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    chapterButton: true,
});

// 使用jquery Ajax 加载章节信息
$.get('http://example.com/chapters/movie_chapter.json', {}, function (data) {
    if (window.mainplayer) {
        window.mainplayer.setChapters(data);
    }
}, 'json');

示例 4：直接传递章节数组

const chapters = [
    {
        title: "第一章",
        desc: "知识点介绍",
        time: "00:00:10"
    },
    {
        title: "第二章",
        desc: "进阶内容",
        time: "00:05:30"
    }
];

player.setChapters(chapters);

示例 5：拖拽文件加载

将章节 JSON 文件直接拖拽到播放器上即可加载章节。支持以下拖拽方式：

• 单独拖拽章节 JSON：将 _chapter.json 文件拖入播放器，为当前播放的视频加载章节
• 同时拖拽视频和章节：将视频文件与对应的章节 JSON 一起拖入，播放器自动匹配并加载（如 movie.mp4 匹配 movie_chapter.json）
• 播放列表拖拽：拖入多个视频及对应的章节文件，自动按文件名匹配创建带章节的播放列表

拖拽的 JSON 文件支持 ZWMAP 协议格式和旧版裸数组格式，播放器会自动识别。

7. 章节搜索功能

加载章节后，在播放器设置菜单中点击"章节搜索"按钮可打开章节搜索面板：

• 关键词搜索：输入关键词可实时按标题或描述筛选章节，匹配文字高亮显示
• 跳转播放：点击搜索结果可跳转到对应章节的时间点开始播放
• 面板拖拽：搜索面板支持拖拽移动，不遮挡视频画面
• 关闭方式：点击关闭按钮或按 Esc 键关闭面板

8. 章节循环播放

在章节搜索面板中，每个章节条目右侧有一个循环按钮：

• 启用循环：点击循环按钮后，视频在该章节的时间范围内循环播放
• 到达终点自动跳回：播放到章节结束时间时自动跳回章节起始时间继续播放
• 取消循环：拖动进度条或点击其他章节的循环按钮可取消当前循环

9. 注意事项

1. 时机选择：建议在视频加载完成后再设置章节信息
2. 格式验证：确保章节数据格式正确，特别是时间格式
3. 图片支持：当前版本暂不支持章节起点图片功能
4. 兼容性：同时支持 hh:mm:ss 格式和浮点数时间表示法
5. 章节编辑器：可从 在线章节编辑工具 可视化创建和编辑章节数据

通过合理使用章节功能，可以显著提升用户的学习体验，特别是对于内容结构清晰的教程类视频。