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. 快捷键

6. 相关配置

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