企业官网建设流程全解析

webreel 是一款开源的浏览器演示录屏工具：在 JSON 配置里用steps数组描述一串操作，它就能自动驱动 Chrome 完成点击、输入、拖拽、滚动等动作，最终输出带光标动画、按键 HUD 和音效的 MP4 / WebM / GIF 演示视频。本文带你完整掌握 webreel 的全部 12 种 Actions 动作，从最简单的点击到复杂的拖拽编排，照着写就能生成专业的产品演示视频 🎬

快速上手：3 条命令生成第一个演示视频

npm install webreel npx webreel init --name my-video --url https://example.com npx webreel record

init会生成一个webreel.config.json，核心结构如下，steps数组里的每一项就是一个 Action：

{ "$schema": "https://webreel.dev/schema/v1.json", "videos": { "my-video": { "url": "https://example.com", "steps": [ { "action": "pause", "ms": 500 }, { "action": "click", "text": "Get Started" }, { "action": "key", "key": "cmd+a", "delay": 1000 } ] } } }

12 种 Actions 动作总览

除pause外，所有步骤都接受可选的delay字段（步骤完成后的等待毫秒数），也可在视频级用defaultDelay统一设置。完整字段说明见 skills/webreel/steps-reference.md，步骤的分发执行逻辑在 packages/webreel/src/lib/runner.ts。

元素定位三件套：text、selector、within

交互类动作都需要先找到目标元素，webreel 提供三种写法：

• text：按可见文本匹配，如"Sign In"，对新手最友好
• selector：按 CSS 选择器匹配，如"#save-btn"，更精确
• within：可选，把搜索范围限定在父容器内，避免同文本元素冲突

text和selector二选一即可。另外一个小细节：点击时 webreel 会在元素范围内随机取一个落点（见 runner.ts 中的randomPointInBox），光标不会每次都戳在同一像素，视频看起来更自然。

交互类动作详解

1. click：点击元素（支持修饰键）

{ "action": "click", "text": "Submit" }

按住修饰键点击（多选、右键类操作）用modifiers字段，录制时 HUD 会同步显示按住的键：

{ "action": "click", "text": "Item 3", "modifiers": ["shift"] }

点击的底层实现（合成完整鼠标事件链、随机驻留时长等）位于 packages/@webreel/core/src/actions.ts。

2. key：按键与快捷键组合

快捷键语法用+连接修饰键，修饰键支持cmd、ctrl、shift、alt、meta；单独按键如Enter、Escape、ArrowDown也可以：

{ "action": "key", "key": "cmd+s", "delay": 800 } { "action": "key", "key": "ctrl+shift+p", "label": "Command Palette" }

label可自定义 HUD 上显示的按键文案。cmd+s、cmd+c等组合会被自动映射为浏览器标准命令（全选、复制、粘贴等），见 actions.ts 中的SHORTCUT_COMMANDS。

3. type：逐字符模拟输入

{ "action": "type", "text": "user@example.com", "selector": "#email", "charDelay": 40 }

不指定selector时，文本会输入到当前焦点元素。每个字符之间有带随机抖动的间隔（约 12% 概率出现更长的"犹豫"停顿，见 actions.ts 中的humanDelay），打字节奏接近真人，charDelay可调节快慢。

4. drag：拖拽元素

from和to各是一个元素定位对象，拖拽过程带有缓动曲线和拖动"幽灵"视觉反馈：

{ "action": "drag", "from": { "text": "Write unit tests", "within": ".column-todo" }, "to": { "selector": ".card-list", "within": ".column-in-progress" }, "delay": 600 }

完整配置可参考 examples/drag-and-drop/webreel.config.json。

5. hover / moveTo / select：其余三个交互动作

• hover：移动光标并触发mouseenter和 CSS:hover，适合展示工具提示、菜单展开
• moveTo：只移动光标、不产生点击事件，常用于"先指向、再拖拽"的连贯表演
• select：直接设置<select>下拉框的值并触发change事件，比模拟点击选项更稳定

{ "action": "hover", "selector": ".tooltip-trigger" } { "action": "moveTo", "text": "Settings", "delay": 400 } { "action": "select", "selector": "#country", "value": "us" }

流程控制类动作详解

6. pause：固定时长停顿

最基础的节奏工具，让视频在关键画面停留：

{ "action": "pause", "ms": 500 }

7. scroll：滚动页面或容器

不指定元素时滚动整个页面；指定selector或text后，滚动对应的容器（如侧边栏、卡片列表），滚动使用平滑动画：

{ "action": "scroll", "y": 400 } { "action": "scroll", "y": -300 } { "action": "scroll", "y": 200, "selector": ".sidebar" }

配置参考 examples/page-scrolling/webreel.config.json。

8. wait：等待元素或文本出现

pause是"盲等"，wait是"条件等"——元素出现才继续，超时timeout毫秒未出现则报错，这是录制动态页面（异步加载、动画）的关键：

{ "action": "wait", "selector": ".results-loaded", "timeout": 5000 } { "action": "wait", "text": "Success" }

9. navigate：视频中途跳转页面

一个视频可以跨多个页面，url支持相对路径（拼接视频级baseUrl）：

{ "action": "navigate", "url": "/settings" }

10. screenshot：录制中抓取静态截图

视频录到一半时顺手存一张 PNG，非常适合"视频 + 文档配图"一起产出：

{ "action": "screenshot", "output": "screenshots/final-state.png" }

组合实战：编排一个登录演示

下面是一个完整的登录流程编排，出自 examples/form-filling/webreel.config.json：先用waitFor确保页面就绪（视频级字段），再依次输入邮箱、密码、点击登录。

{ "url": "./web/index.html", "waitFor": "#email", "defaultDelay": 300, "steps": [ { "action": "pause", "ms": 500 }, { "action": "type", "text": "user@example.com", "selector": "#email", "charDelay": 40 }, { "action": "type", "text": "supersecret123", "selector": "#password", "charDelay": 30, "delay": 500 }, { "action": "click", "text": "Sign In" }, { "action": "pause", "ms": 2500 } ] }

几个编排要点：

• 每个动作完成后默认等待defaultDelay毫秒，节奏感主要来自它，不需要到处写pause
• 需要"元素出现 → 操作 → 稍作停留"的节奏时，优先wait+delay，比拍脑袋写pause更稳定
• 步骤顺序即执行顺序，verbose模式（webreel record --verbose）会逐步打印执行的 action，方便排查

实用技巧：共享步骤与调试命令

共享步骤：多个视频有相同的开场（比如关闭 Cookie 横幅），可以把公共步骤抽到独立 JSON 文件，再用顶层include注入所有视频，见 examples/shared-steps/webreel.config.json 与 examples/shared-steps/steps/setup.json：

{ "steps": [ { "action": "wait", "selector": ".cookie-banner", "timeout": 5000 }, { "action": "click", "selector": ".accept-btn", "delay": 300 } ] }

常用调试命令：

• webreel validate：不执行、只校验配置文件
• webreel preview：在可见浏览器窗口里跑一遍，不录制
• webreel composite：用已存的原始录像 + 时间线重新合成，调整主题后无需重新录制

更多场景可以逛 examples/ 目录：GIF 输出、WebM 输出、移动端视口、自定义光标主题、一个配置录多个视频等都有对应示例。掌握上面 12 种 Actions 动作后，把它们按业务流顺序串起来，就是你产品的专属演示视频了 ✨