ZWPlayer 交互标注功能使用说明

1. 功能概述

ZWPlayer 支持为视频添加交互标注（Annotation）功能，可在视频画面上叠加可交互节点，实现点击跳转、分支选择、测验问答、投票调查、表单收集等丰富的互动体验。广泛应用于互动教学、分支剧情、产品展示、在线培训等场景。

交互标注功能支持 13 种节点类型，分为四大类：

成功加载标注数据后：

1. 视频覆盖层：在视频画面上显示交互节点，用户可点击、长按触发动作
2. 进度条标记：播放器进度条上会显示标注节点的时间范围
3. 标注按钮：如果初始化时设置了 annotations 参数，控制条上会出现标注编辑按钮，点击可打开在线标注编辑器

2. 设置标注信息

2.1 通过构造函数配置

在创建 ZWPlayer 实例时，通过 annotations 参数传入标注数据：

var player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    // 传入标注 JSON URL
    annotations: 'http://example.com/annotations/movie_annotation.json'
});

也支持 annotation（单数）属性名，播放器内部会自动归一化。

2.2 通过方法动态加载

使用 loadAnnotations 方法在运行时动态加载标注数据：

// 加载远程 JSON 文件
player.loadAnnotations('http://example.com/annotations/movie_annotation.json');

// 加载 ZWMAP JSON 对象
player.loadAnnotations({
    "zwp_protocol": "ZWMAP/1.0",
    "zwp_type": "annotation",
    "nodes": [ /* ... */ ]
});

// 卸载标注
player.unloadAnnotations();

2.3 通过 URL 对象配置

在 url 参数的 JS 对象中同时配置视频和标注：

var player = new ZWPlayer({
    playerElm: '#mse',
    url: {
        src: 'http://example.com/vod/movie.mp4',
        annotations: 'http://example.com/annotations/movie_annotation.json',
        chapters: 'http://example.com/chapters/movie_chapter.json',
        subtitles: 'http://example.com/subtitles/movie.vtt'
    }
});

2.4 拖拽文件加载

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

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

3. 标注数据格式

3.1 ZWMAP JSON 格式

交互标注采用 ZWMAP（ZWPlayer 媒体应用协议）标准 JSON 格式，导出文件命名为 {视频标题}_annotation.json。

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation",
  "zwp_version": "1.0",
  "nodes": [
    {
      "id": "btn001",
      "type": "button",
      "name": "了解更多",
      "time_range": [10, 30],
      "position": { "x": 60, "y": 70, "w": 25, "h": 8 },
      "style": {
        "border_radius": 4,
        "opacity": 1.0,
        "bg_color": "#1890ff"
      },
      "event": {
        "trigger": "click",
        "actions": [
          { "type": "SEEK_TIME", "payload": { "target": 120 } }
        ]
      }
    },
    {
      "id": "quiz001",
      "type": "quiz",
      "name": "知识测验",
      "time_range": [60, 90],
      "position": { "x": 20, "y": 20, "w": 60, "h": 60 },
      "content": {
        "prompt": "以下哪个是正确的？",
        "options": [
          { "text": "选项 A", "value": "A", "is_correct": true },
          { "text": "选项 B", "value": "B", "is_correct": false }
        ]
      },
      "pause_on_show": true
    }
  ]
}

3.2 协议头部字段

3.3 节点对象字段

3.4 事件与动作链

每个基础元素节点可配置一个 event（单数对象），包含触发器和动作链；动作参数统一放在 payload 中：

{
  "trigger": "click",
  "actions": [
    { "type": "PAUSE_MEDIA", "payload": {} },
    { "type": "SEEK_TIME", "payload": { "target": 120 } },
    { "type": "EMIT_MESSAGE", "payload": { "params": { "key": "value" } } }
  ]
}

提示：一个触发器可以同时绑定多个动作，动作会按顺序依次执行。例如点击一个按钮，可以先暂停视频，再弹出一个信息卡片，然后跳转到指定时间点。

支持的触发器类型：

说明：当前版本播放端仅支持 click 触发；长按、滑动、拖拽、被动、手势等为协议预留值，尚未在播放端实现，已从编辑器中移除。旧数据中出现这些值时按 click 处理。

支持的动作类型：

动作按功能分为五大类：

媒体控制

页面导航

交互控制

开发者接口

数据通信

关于事件设置的可视化操作方法，可参阅 在线标注工具使用帮助 中的交互设置部分。

3.5 动画系统

每个节点都支持三个阶段的动画效果：入场（出现时）、强调（停留时）、退场（消失时）。所有动画均支持自定义时长（100–3000ms），默认 500ms。

入场动画

节点出现时播放的动画，共 7 种效果：

强调动画

节点在画面停留期间循环播放的动画，用于吸引用户注意力，共 5 种效果：

退场动画

节点消失时播放的动画，共 6 种效果：

4. 自动识别规则

zwplayer 根据参数内容自动识别标注格式：

• 字符串 URL：作为远程 JSON 文件自动下载并解析
• 对象且含 zwp_type: "annotation"：按 ZWMAP 协议格式解析，提取 nodes 数组
• 对象含 nodes 数组：直接作为节点数组使用
• 拖拽文件：文件名匹配 *_annotation.json 模式，自动按 ZWMAP 格式解析

5. 在线标注编辑器

ZWPlayer 提供在线标注编辑器，可通过以下方式使用：

1. 在播放器控制条上点击标注编辑按钮（需配置 annotations 参数）
2. 直接访问 在线标注编辑工具 打开独立编辑器

编辑器功能包括：

• 可视化画布绘制：直接在视频画面上拖拽绘制节点区域
• 属性面板：配置节点的位置、时间范围、样式、内容和交互动作
• 时间线编辑：在时间轴上直观管理节点的时间范围
• 实时预览：按 P 键进入预览模式，在真实播放器中测试交互效果
• JSON 面板（可编辑）：支持导入/导出标准 ZWMAP JSON 文件；面板文本域可直接编辑或粘贴 JSON，点击"应用"（或 Ctrl+Enter）立即载入编辑器，"重置"恢复最近应用的内容。编辑期间面板进入保护态（标记变黄），画布与属性面板的改动不会覆写你正在编辑的文本；应用即整体替换当前节点
• 快捷键操作：按 N 快速创建节点，Delete 删除，Ctrl+Z 撤销
• 浮动快捷菜单：选中节点后在节点上方弹出，按类型定制（详见下节）

5.1 浮动快捷菜单

选中画布上的任意节点，节点上方会出现快捷菜单：类型专属动作在前，公共区在后；多选时仅显示公共区。公共区四键为 隐藏/显示、复制节点、图层（置顶/上移/下移/置底，写入 z_index）、删除节点——删除固定在末位以防误触。所有菜单操作与属性面板同源写入状态，支持撤销/重做与草稿自动保存。

各类型的专属动作：

6. 使用示例

示例 1：加载远程标注文件

var player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    annotations: 'http://example.com/annotations/movie_annotation.json'
});

示例 2：直接传入 ZWMAP 对象

var player = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    annotations: {
        "zwp_protocol": "ZWMAP/1.0",
        "zwp_type": "annotation",
        "nodes": [
            {
                "id": "node1",
                "type": "button",
                "name": "Click Me",
                "time_range": [5, 15],
                "position": { "x": 40, "y": 40, "w": 20, "h": 10 },
                "event": {
                    "trigger": "click",
                    "actions": [
                        { "type": "SEEK_TIME", "payload": { "target": 30 } }
                    ]
                }
            }
        ]
    }
});

示例 3：运行时动态加载与卸载

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

// 视频播放后加载标注
player.onmediaevent = function(event) {
    if (event.type === 'play') {
        player.loadAnnotations('http://example.com/annotations/movie_annotation.json');
    }
};

// 切换视频时卸载旧标注
function switchVideo(newUrl) {
    player.unloadAnnotations();
    player.setVideoUrl(newUrl);
}

示例 4：在播放列表中使用标注

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "groups": [
    {
      "name": "互动课程",
      "items": [
        {
          "name": "第一课",
          "url": "https://cdn.example.com/lesson1.mp4",
          "annotation": "https://cdn.example.com/annotations/lesson1_annotation.json"
        },
        {
          "name": "第二课",
          "url": "https://cdn.example.com/lesson2.mp4",
          "annotation": "https://cdn.example.com/annotations/lesson2_annotation.json"
        }
      ]
    }
  ]
}

7. 注意事项

1. 协议头必需：标注 JSON 必须包含 zwp_protocol: "ZWMAP/1.0" 和 zwp_type: "annotation"，否则将拒绝加载
2. 时间范围：time_range 是 [开始秒, 结束秒] 数组，第一个值必须小于第二个值
3. 位置坐标：position 中的 x、y、w、h 均为百分比值（0–100），相对于视频画面
4. 性能考虑：同一时间段内同时显示的节点数量建议不超过 20 个，以保持流畅的播放体验
5. 编辑器：可通过 在线标注编辑工具 可视化创建和编辑标注
6. 单复数兼容：配置参数同时支持 annotations 和 annotation（单数），播放器内部自动归一化