章节标注设置

1. 功能概述

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

界面如下图所示：

成功设置章节信息后：

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

2. 章节菜单：如果初始化时设置 chapterButton: true，控制条时间显示区附近会出现章节菜单按钮，点击章节按钮弹出章节列表，点击某一章节，跳转到该位置开始播放。

2. 设置章节信息

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

2.1 方法签名

player.setChapters(chapters);

2.2 参数类型

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

1. 包含章节内容的大字符串（JSON 或 VTT 格式）

2. 已解析的 js 数组

3. 章节文件的 HTTP 地址

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

3. 章节数据格式

3.1 JSON 格式（ZWPlayer 私有格式）

章节文件的json格式是zwplayer定义的私有格式，一个json格式的章节文件内容如下：

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

如上章节列表json中每一个章节点都是一个js对象，对象的属性说明如下：

3.2 VTT 格式（WEBVTT）

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

4. 自动识别规则

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

• HTTP/HTTPS 开头：作为远程章节文件 URL 自动下载

• "[" 开头：作为 JSON 数组解析

• "WEBVTT" 开头：作为 WEBVTT 文件处理

5. 使用示例

示例 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.json?v=236');
    }
}, 200);

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

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

// 使用jquery Ajax 加载章节信息
$.get('http://example.com/chapters.json?v=236', {}, function (data) {
    if (window.mainplayer) {
        // 章节信息如果被正确加载，data应该是一个js数组了
        window.mainplayer.setChapters(data);
    }
}, 'json');

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

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

player.setChapters(chapters);

6. 注意事项

1. 时机选择：建议在视频加载完成后再设置章节信息

2. 格式验证：确保章节数据格式正确，特别是时间格式

3. 图片支持：当前版本暂不支持章节起点图片功能

4. 兼容性：同时支持 hh:mm:ss 格式和浮点数时间表示法

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