更新日志

v3.3.0 - 2026-05

📥 下载 v3.3.0

本次更新是 ZWPlayer v3.x 系列的重要里程碑版本，核心围绕视频工具生态和交互式视频能力两大方向，引入了统一数据协议 ZWMAP、六大工具模块及配套在线编辑器，并新增放大镜、投屏等体验增强功能。

🔧 1. ZWMAP 统一数据协议

引入 ZWMAP/1.0 (ZWPlayer Media Application Protocol)，为缩略图、字幕、章节、播放列表、标注、水印六大模块定义统一的 JSON 数据交换规范。所有在线编辑器生成的数据均遵循该协议，可直接在播放器中加载使用，实现工具链闭环。

协议特点：统一协议头（zwp_protocol/zwp_type/zwp_version）自动标识数据类型；字幕和章节保持旧格式向后兼容；基于版本号支持未来协议演进。

🎯 2. 标注系统 (Annotation)

将视频从「单向播放」升级为「双向交互」，支持 13 种节点类型：热区、文字、图片、按钮、选择题、测验、表单、投票、信息卡、网页嵌入、地图、倒计时、变速器。

核心特性：三阶段动画系统（18 种效果）、进度条颜色编码可视化、事件驱动动作链、防跳过与暂停触发等教学场景支持、会话变量系统。配套提供在线标注编辑器，支持时间轴可视化编辑和 ZWMAP JSON 导出。

💧 3. 水印系统 (Watermark)

覆盖品牌露出、版权保护、防录屏溯源三大场景。支持图片/文字两种类型，以及静态、动态（防录屏移动）、平铺（密集铺满）三种行为模式。水印文字支持模板变量（如 {user_name}、{sys_time}），运行时动态替换。向后兼容旧版 logo 参数。配套提供在线水印编辑器，支持 WYSIWYG 编辑和多格式导出。

🛠 4. 工具生态完善

• 缩略图：进度条悬浮预览画面，基于雪碧图加载，配套缩略图生成工具
• 章节：视频分段导航，支持 JSON/VTT 格式，进度条彩色标记，内置搜索面板，配套在线章节编辑器
• 字幕：新增 ZWMAP 协议支持，完善双字幕、翻译 API、拖拽加载等能力，配套在线字幕编辑器
• 播放列表：见下方重点说明

📋 5. 播放列表 (Playlist)

面向系列课程、视频专辑、多集内容等连续播放场景，提供完整的列表管理与播放控制能力。

数据结构：基于 ZWMAP 协议的多级分组（Group → Item），每个列表项可独立配置视频地址、封面、字幕、章节、缩略图、标注、水印等资源，实现一条数据驱动全部功能。

播放管理：

• 自动记忆每条视频的播放进度，下次打开自动续播
• 当前视频结束自动播放下一条（可配置 autoPlayNext）
• 播放错误时自动跳转下一条，避免播放中断
• 支持上一条/下一条导航，跨分组无缝切换

列表交互：

• 收藏与播放历史，数据持久化存储在 localStorage
• 实时搜索与关键词高亮
• 双栏布局（分组 + 项目列表）和单栏自适应布局
• 「即将播放」预览面板，展示队列中接下来的内容

配套工具：在线列表编辑器 可视化编辑分组与项目，支持导入/导出 ZWMAP JSON，也可直接粘贴 XML 格式进行转换。

✨ 6. 新增功能

• 放大镜：基于 Canvas 的圆形放大镜，支持 1.5x-4x 七档倍率，快捷键 Z 开关（配置项：zoomButton）
• 投屏：支持 Google Cast 和 AirPlay，基于浏览器原生 API，内置超时保护和状态恢复（配置项：castButton）

🌐 7. 框架生态支持

在已有的 Vue 2 / Vue 3 适配基础上（npm 包 zwplayervue3），新增对 React 生态的支持。ZWPlayer 采用 UMD 模块模式构建，天然兼容 CommonJS、AMD 和浏览器全局变量导入。React 项目中可通过 useRef + useEffect 快速集成，无需额外适配层，覆盖主流前端框架生态。

⚙️ 8. 属性设置增强

各功能模块属性名统一支持单数/复数自动归一化（如 chapter / chapters）。

📦 升级方式

替换 zwplayer.js 文件即可，完全向后兼容，所有新功能默认不启用。

v3.2.2 - 2026-02-21

📥 下载 v3.2.2

本次更新重点优化了微信环境下的自动播放机制，新增了对 WordPress 复杂主题的样式隔离兼容，并集中修复了自动播放状态、小屏 UI 适配及流式布局等若干细节问题，进一步提升了播放器的集成稳定性和用户体验。

✨ 功能新增与优化

• 微信自动播放优化：针对移动端微信内置浏览器，实现了自动播放功能。同时引入智能降级策略：非静音播放失败时将自动降级到静音播放，并显示“打开声音”提示（PC 端微信保持正常播放流程）。
• WordPress 主题兼容性处理：隔离了外部页面样式，有效防止了部分 WordPress 主题自带的涟漪效果、全局 SVG 样式及自定义按钮样式对播放器 UI 和交互的干扰。
• 小屏显示体验优化：优化了手机等小屏幕设备下的界面排版。

🔧 问题修复

• 修复了部分场景下，用户点击“打开声音”按钮后视频依然没有声音的体验问题。

v3.2.1 - 2026-01-24

📥 下载 v3.2.1

本次更新是 ZWPlayer v3.2.0 系列的深度优化版本。我们不仅在字幕与章节系统上实现了功能跃迁，还针对移动端交互、WebRTC 协议生态以及 UI 细节进行了全方位的打磨，旨在为开发者提供更专业、更流畅的跨端播放解决方案。

✨ 1. 字幕与章节系统：从“静态显示”到“深度交互”

• 智能内容检索： 新增内置字幕与章节搜索面板，支持通过关键词快速检索内容并一键跳转至对应视频进度，实现字幕即索引，台词秒跳转。
• 零门槛文件接入： 支持将本地字幕（SRT/VTT/BCC）或章节（JSON/VTT）文件直接拖拽至播放器加载，显著提升内容调试与观影效率。
• 全生命周期回调： 新增 onSubtitleLoaded、onChapterLoaded 事件，方便业务逻辑深度联动。
• 格式自动检测： 播放器现可自动识别 VTT、SRT、JSON 等多种字幕与章节内容格式。

🚀 2. 流媒体协议族：WebRTC 矩阵全面覆盖

• 多云平台深度集成： 在支持标准 WHEP 的基础上，新增对阿里云 ARTC 及腾讯云 TRTC 协议的官方适配，赋能超低延迟直播场景。
• 协议智能识别： 强化底层检测逻辑，支持对 webrtc://、artc://、trtc://、brtc:// 等多种协议头的自动解析与秒开。
• 全浏览器录制兼容： 针对 Firefox 和 Safari 浏览器进行了专项优化，确保录制功能在主流浏览器中均能稳定运行。

📱 3. 移动端适配：更懂触屏的交互设计

• 高效快进新体验： 引入长按触发 2 倍速播放机制，松开即刻恢复原速，操作逻辑对齐主流短视频 APP。
• 空间布局优化： 小窗口模式下智能隐藏非必要工具条，并缩减中间播放按钮尺寸，确保小屏下画面信息量的最大化。
• 微信环境智能策略：新增微信浏览器环境检测，针对微信自动播放限制，在微信内自动禁用 autoplay 配置，避免持续转圈等待，提升首屏体验。

🎨 4. UI/UX 进化：消除干扰，回归视觉纯净

• 全局面板互斥机制： 建立全局面板管理器，确保字幕搜索、设置、章节等功能面板同时仅激活一个，避免 UI 重叠与视觉混乱。
• 跨端交互兼容： 修复移动端浏览器 :hover 伪类导致的菜单“粘性显示”问题。
• 视觉语言统一： 统一录制选项、滚动条与弹出框样式，提升整体品牌感。

🔧 问题修复

• Fluid 模式适配优化：修正了在 fluid 自适应模式下，播放竖屏视频时，容器不能正确匹配比例导致出现非预期滚动条的问题。
• 多语言内核修复：修正了部分提示的多语言映射，以及切换语言时 disableMutedConfirm 配置失效的问题。
• 快捷键冲突：解决了在搜索面板操作方向键时，意外触发底层播放器音量调整的冲突问题。

v3.2.0 - 2025-12-01

📥 下载 v3.2.0

本次更新是一个重要功能版本，重点新增了多项实用配置项，显著增强了播放器的本地化、交互性和播放能力。

✨ 功能新增与优化

• 本地文件播放 (localPlayback)： 支持直接播放用户设备上的本地视频/音频文件。无需上传至服务器，为用户提供更快捷、私密的播放体验。
• 片段循环播放 (segmentButton)： 允许用户选择视频中的特定片段进行循环播放。极大方便了教学复盘、精彩瞬间重放等场景。
• 录制功能 (recordButton)： 支持录制正在播放的视频或仅提取音频。
• 多语言支持 (lang)： 新增国际化配置项，支持界面语言切换。
• 音量增益调节： 可调节音量增益，最大支持 4倍音量。
• 丰富快捷键： 增加了更多键盘快捷键操作，提升高级用户的操作体验。

🔧 问题修复

• 修复了 fluid 模式下部分视频显示不完整的问题。

v3.1.5 - 2025-11-01

✨ 功能新增与优化

• 新增 disableMutedConfirm 配置项：用于禁用因浏览器自动播放策略触发的静音确认提示框，为需要无中断自动播放的场景提供更流畅的体验。

🔧 问题修复

• 修复了播放器右键菜单中链接点击失效的问题。

v3.1.4 - 2025-08-30

✨ 功能新增与优化

• 协议支持扩展：新增对 webrtc:// 及 brtc:// 流媒体协议的支持。
• HLS 增强：增加对 HLS 流中 HEVC 编码格式的兼容，以支持更高效的视频播放。
• 直播优化：当设置 isLive=true 时，播放器将自动启用直播追帧功能，确保更低的延迟。

🔧 问题修复

• 修复了在 HTTP-FLV 点播模式下可能无法正常播放的问题。

v3.1.2 - 2024-05-07

• 框架适配：新增对 Vue 2 与 Vue 3 框架的官方适配支持，便于在主流前端项目中集成。
• 样式优化：解决了在部分移动设备上的UI样式兼容性问题，提升了移动端的视觉一致性。
• 🎉 正式发布：ZWPlayer v3.1.2 版本正式发布。