ZWPlayer 播放列表功能使用说明

1. 功能概述

ZWPlayer 内置播放列表功能，支持多视频有序播放。用户可以通过 ZWMAP 协议的播放列表类型加载在线列表，也可以直接拖拽本地文件自动生成列表。播放列表面板提供搜索、收藏、历史记录等管理能力，适用于系列课程、剧集播放、培训视频等连续观看场景。

2. 加载播放列表

2.1 通过 ZWMAP 协议加载

播放列表采用 ZWMAP 协议格式（zwp_type: "playlist"），支持一级或多级分组结构。通过 url 参数传入播放列表 JSON 地址即可加载：

new ZWPlayer({
    playerElm: 'mse',
    url: 'https://example.com/playlist.json'
});

播放器会自动识别 JSON 中的 ZWMAP 协议头并按播放列表模式加载。

一级菜单（单分组）： 当播放列表只有一个分组时，面板自动切换为单栏模式，直接显示所有视频项。

两级菜单（多分组）： 当播放列表包含多个分组时，面板显示为左右双栏——左侧为分组列表，右侧为当前分组下的视频项。点击左侧分组即可切换。

2.2 通过本地文件拖拽

开启 localPlayback 后，用户可以直接将视频文件拖拽到播放器区域：

拖入多个视频文件： 自动创建本地播放列表，按文件名排序
拖入单个视频文件： 追加到已有列表，或创建新列表
拖入播放列表文件： 支持 .json 格式，直接替换当前列表
自动关联附属文件： 与视频同名字幕（.srt/.vtt/.bcc）、章节（.json）、标注等文件会自动匹配加载

2.3 自动播放与连播逻辑

当播放器设置 autoplay: true 时：

加载在线播放列表后，自动播放第一个视频
拖拽本地文件后，如果当前没有正在播放的内容，自动开始播放
当前视频播放结束后，自动播放列表中的下一个视频

播放器提供四种播放模式，通过播放列表面板标题栏的播放模式按钮切换：

连播（默认）：当前视频播完后自动播放下一个，列表播完即停
列表循环：当前视频播完后自动播放下一个，最后一项播完自动回到第一项
单曲循环：当前视频反复播放，不切换到下一个
播放一次：当前视频播完后停止，不自动播放下一个

此外，播放器控制条上的 循环开关 等效于"单曲循环"模式——开启时当前视频反复播放，不切换下一个。

3. 播放列表面板功能

3.1 列表搜索

面板顶部提供搜索框，输入关键词即可实时搜索：

搜索范围覆盖所有分组中的视频名称
搜索时自动切换为单栏模式，跨分组显示匹配结果
匹配文字高亮显示
清除搜索关键词恢复原始分组视图

3.2 收藏功能

点击视频项右侧的星形图标即可收藏/取消收藏
点击面板标题栏的收藏按钮，可筛选显示所有已收藏的视频
收藏数据保存在浏览器本地，刷新页面后仍然保留

3.3 历史记录

点击面板标题栏的时钟按钮，查看最近播放过的视频
最多保留 100 条历史记录，按播放时间倒序排列
可一键清除全部历史记录

3.4 其他操作

刷新列表： 在线播放列表支持刷新重新加载（远程列表显示刷新按钮）
清空列表： 本地文件创建的播放列表支持一键清空（本地列表显示清空按钮）
删除单项： 本地列表中每个视频项右侧有删除按钮，可逐个移除
播放进度： 每个视频项上显示进度条，已播放完成的项显示完成标记
断点续播： 关闭页面后再次打开同一视频，自动从上次观看位置继续播放

4. 控制栏导航

加载播放列表后，播放器控制栏会自动出现上/下一个按钮：

点击 下一个 按钮：播放列表中的下一个视频
点击 上一个 按钮：播放列表中的上一个视频
在收藏模式下，上/下按钮仅在收藏的视频之间切换

5. 快捷键

快捷键	功能
`Q`	打开/关闭播放列表面板
`ESC`	关闭播放列表面板（在搜索框聚焦时生效）
`[` 或 `【`	播放上一个视频
`]` 或 `】`	播放下一个视频
`Enter` 或 `Space`	在分组列表中选中当前分组

6. 相关配置

参数	位置	类型	默认值	说明
`autoplay`	播放器初始化参数	boolean	`true`	是否自动播放
`localPlayback`	播放器初始化参数	boolean	`false`	是否启用本地文件拖拽功能

关于播放列表 JSON 的完整字段定义，请参考 ZWMAP 播放列表规范。

7. 拖拽加载：一站式视频增强体验

ZWPlayer 的播放列表功能不仅支持视频文件的批量播放，还能通过 拖拽方式 自动关联多种辅助资源文件，实现对视频教学内容的深度揭示。这种方式特别适用于教育课程、企业培训等需要丰富辅助信息的应用场景。

7.1 支持的辅助资源类型

以下类型的文件均可与视频文件一起拖拽到播放器中，播放器会自动识别并关联到对应的视频：

资源类型	文件后缀	匹配规则	功能说明
字幕	`.srt`、`.vtt`、`.webvtt`、`.bcc`、`.json`	`视频名_subtitle` 或同名	为视频添加多语言字幕，支持 SRT、VTT、BCC 等常见格式
章节	`.json`、`.vtt`、`.webvtt`	`视频名_chapter` 或同名	在进度条上显示章节标记，方便快速定位内容段落
缩略图预览	`.json`	`视频名_thumbnail` 或同名	鼠标悬停进度条时显示对应时间点的预览画面
选集预览图	`.jpg`、`.jpeg`、`.png`、`.webp`	由缩略图 JSON 引用	播放列表面板中每个视频项的封面预览图
交互标注	`.json`	`视频名_annotation` 或同名	在视频画面上叠加可交互的热区、按钮、测验等标注
水印	`.json`	`视频名_watermark` 或 `视频名_wm`	在视频画面上叠加品牌 Logo、文字水印或防录屏动态水印

7.2 文件关联机制

播放器通过 文件名匹配 自动将辅助资源与视频建立关联。匹配规则如下：

命名规则： 辅助资源文件的名称以视频文件名为基础，加上对应的功能后缀。分隔符支持 _、-、. 三种形式。

示例： 假设视频文件名为 lesson1.mp4，则以下文件会自动关联：

lesson1.mp4                          ← 视频文件
lesson1_chapter.json                 ← 章节数据
lesson1_subtitle.srt                 ← 字幕文件
lesson1_thumbnail.json               ← 进度条缩略图
lesson1_annotation.json              ← 交互标注
lesson1_watermark.json               ← 水印配置
lesson1.jpg                          ← 选集封面预览图

多视频批量拖拽时： 播放器会按文件名逐一匹配，自动将辅助资源分配给对应的视频。例如：

lesson1.mp4, lesson1_chapter.json, lesson1_subtitle.srt
lesson2.mp4, lesson2_chapter.json, lesson2_subtitle.srt

拖入以上 6 个文件后，播放器会自动创建包含 2 个视频的播放列表，每个视频分别关联各自的章节和字幕。

7.3 操作流程

准备素材：按照命名规则准备好视频文件和对应的辅助资源文件
打开播放器：访问在线播放器，开启本地播放功能
拖拽加载：将所有文件一起拖拽到播放器窗口中，播放器自动完成识别、关联和加载
开始观看：视频播放时，字幕、章节标记、缩略图预览、交互标注等增强功能自动生效

7.4 应用场景

这种拖拽加载方式非常适合以下场景：

教育培训：将课程视频与章节目录、字幕、随堂测验标注一起加载，学员可以快速定位知识点、参与互动答题
企业培训：培训视频配合章节和交互标注，实现培训内容的结构化展示和学习跟踪
内容审核：将待审视频与水印配置一起加载，确认水印效果和覆盖范围
本地演示：无需搭建服务器，直接拖拽本地文件即可展示完整的增强视频播放效果

关于本地播放的完整功能说明（格式支持、文件拖拽、片段截取等），请参阅本地播放使用说明。