视频热区生成器 — 使用指南

快速入门

视频热区生成器（Hotspot Generator）是一款免费的在线工具，可以在视频画面上叠加交互式热区节点，实现分支剧情、知识问答、信息展示、投票调查等互动体验。导出的 ZWMAP JSON 可直接用于 ZWPlayer 播放器。

快速上手步骤

1. 加载视频

   将本地视频文件（MP4、WebM）拖拽到窗口中，或者在地址栏中粘贴远程视频 URL 并按回车键。

2. 添加节点

   在视频画面上拖拽绘制热区，或按 N 键快速创建一个默认节点。也可以从右侧组件库中拖入预设模板。 to create a default node. You can also drag preset templates from the component library.

3. 配置属性和动作

   选中节点后，在属性面板中调整位置、时间范围、样式和交互动作。支持多条动作链式触发。

4. 预览和导出

   按 P 键进入预览模式查看交互效果。确认无误后，导出 ZWMAP JSON 或直接复制 ZWPlayer 配置。 to enter preview mode and test interactions. When ready, export the ZWMAP JSON or copy the ZWPlayer config directly.

节点类型

热区生成器支持 13 种节点类型，分为 4 个类别：

基础节点

交互节点

高级节点

系统节点

键盘快捷键

使用以下键盘快捷键提高工作效率：

动作与触发器

每个节点都可以配置一个或多个动作，在用户交互时按顺序依次触发。

动作类型

触发器类型

• 点击 — 用户点击节点时触发
• 长按 — 用户长按节点超过阈值时触发
• 滑动 — 用户在节点上滑动时触发
• 拖拽 — 用户拖拽节点时触发
• 被动 — 由其他动作或事件自动触发
• 手势 — 识别特定手势（如双指缩放）时触发

动画系统

每个节点都支持三种动画阶段：入场、强调、退场。支持多种预设动画效果和自定义时长。

入场动画

强调动画

退场动画

动画时长

动画持续时间，单位为毫秒（ms）。默认值 300ms。范围：100–3000ms。

ZWMAP 交互标注规范

ZWMAP（ZWPlayer 媒体应用协议）的交互标注类型定义了描述视频交互热区的标准 JSON 格式。该协议实现了热区编辑工具与视频播放器之间的互操作性。

协议头部

每个 ZWMAP 热区文档以协议标识符开头：

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation",
  "zwp_version": "1.0"
}

节点对象字段

完整示例

此示例展示了一个包含文本标注和按钮的简单 ZWMAP 文档：

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "annotation",
  "zwp_version": "1.0",
  "nodes": [
    {
      "id": "a1b2c3d4",
      "type": "text",
      "name": "Title Card",
      "time_range": { "start": 0, "end": 5 },
      "position": { "x": 10, "y": 10, "w": 80, "h": 15 },
      "style": { "opacity": 1 },
      "content": {
        "text": "Welcome to the interactive video!",
        "color": "#ffffff",
        "fontSize": 24
      },
      "animation": {
        "enter": { "type": "fadein", "duration": 300 },
        "exit": { "type": "fadeout", "duration": 300 }
      }
    },
    {
      "id": "e5f6g7h8",
      "type": "button",
      "name": "Skip Intro",
      "time_range": { "start": 2, "end": 8 },
      "position": { "x": 70, "y": 80, "w": 25, "h": 10 },
      "events": [
        {
          "trigger": "click",
          "actions": [
            { "type": "SEEK_TIME", "time": 10 },
            { "type": "PAUSE_MEDIA" }
          ]
        }
      ]
    }
  ]
}

ZWPlayer 集成

ZWPlayer 是一个功能丰富的 JavaScript 视频播放器，开箱即用支持视频标注交互。以下是如何将生成的标注配置与 ZWPlayer 集成。

播放器配置

在 ZWPlayer 初始化配置中添加 annotations 属性：

var player = new ZWPlayer({
  playerElm: 'mse',
  url: 'https://cdn.example.com/video.mp4',
  annotations: {
    "zwp_protocol": "ZWMAP/1.0",
    "zwp_type": "annotation",
    "nodes": [
      {
        "id": "a1b2c3d4",
        "type": "button",
        "name": "Click Me",
        "time_range": { "start": 5, "end": 15 },
        "position": { "x": 40, "y": 40, "w": 20, "h": 10 },
        "events": [
          {
            "trigger": "click",
            "actions": [
              { "type": "PAUSE_MEDIA" }
            ]
          }
        ]
      }
    ]
  }
});

从工具复制配置

在工具的 JSON 面板中，点击复制按钮即可获取可直接使用的 ZWPlayer 配置片段。

实时预览

按 P 键或点击预览按钮，打开一个完整的 ZWPlayer 实例并加载当前标注配置。在预览中可以点击标注测试交互效果。按 Esc 键退出。

使用 ZWMAP JSON

将导出的 ZWMAP JSON 存放在服务器上，应用可以获取该 JSON 并将解析后的 nodes 数组直接传递给 ZWPlayer 配置中的 annotations 属性。

使用 JSON URL

除了传入对象，还可以直接将 ZWMAP JSON 文件的 URL 作为字符串传入，ZWPlayer 会自动获取并解析：

var player = new ZWPlayer({
  playerElm: 'mse',
  url: 'https://cdn.example.com/video.mp4',
  annotations: 'https://cdn.example.com/annotations/movie_annotation.json'
});

拖拽加载

您还可以通过将文件直接拖拽到 ZWPlayer 播放器上来加载标注：

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

常见问题