第06章 - 动作详解（二）：键盘操作

本章讲解三种键盘类动作：type（在输入框中输入文本）、press（按下单个键）、combo（组合键）。键盘动作是表单填写、快捷键操作的核心。

6.1 type：输入文本

type 用于在某个输入框中输入文本，它需要两个信息：在哪个输入框输入（into）和输入什么（text）：

- type: {into: "templates/input.png", text: "Hello World"}

也可以用展开的多行写法（更适合长文本或含变量）：

- type:
    into: "templates/input_username.png"
    text: "$input.username"

对应源码中的 TypeSpec 结构，包含 Into（输入框模板路径）与 Text（要输入的文本）两个字段。

6.1.1 type 的执行流程

type.go 中 TypeAction.Execute 的逻辑是：

1. FindElement(template) 定位输入框中心；
2. eng.Click(pt.X, pt.Y) 先点击输入框，让它获得焦点；
3. eng.TypeText(text) 输入文本。

第 2 步是关键——type 动作会先点击目标输入框再输入。这意味着你不需要在 type 之前额外加一个 click 来聚焦；type 已经帮你做了。

6.1.2 文本输入的底层行为

引擎的 TypeText 有两种模式：

• 普通模式：直接调用 robotgo.Type(text)，快速逐字输入，支持 Unicode（包括中日韩文字）；
• 人类模式：调用人类行为模块的 typeText，逐字输入时带有可变延时，并按 mistake_rate 概率引入打字错误再修正（详见第 11 章）。

6.1.3 结合运行时变量

type 的 text 是最常用的运行时变量注入点：

inputs:
  - name: keyword
    label: "搜索关键词"
    required: true

steps:
  - name: "搜索"
    actions:
      - type: {into: "templates/search_box.png", text: "$input.keyword"}
      - press: "enter"

执行时用户输入的关键词会替换 $input.keyword，实现「同一份工作流搜索不同关键词」。

6.2 press：按下单个键

press 用于按下一个键，最常见的是回车、Tab、Esc 等特殊键：

- press: "enter"

press 的值是一个键名字符串，内部调用 robotgo.KeyTap(key)。常用的特殊键名包括：

除了特殊键，也可以按单个字符键，如 press: "a"。不过对于连续文本，应该用 type 而非逐个 press。

6.2.1 典型用法：提交与跳转

steps:
  - name: "填写并提交"
    actions:
      - type: {into: "templates/username.png", text: "$input.username"}
      - press: "tab"                     # Tab 跳到下一个字段
      - type: {into: "templates/password.png", text: "$input.password"}
      - press: "enter"                   # 回车提交

6.3 combo：组合键

combo 用于按下组合键（快捷键），值是一个键名数组：

# 复制
- combo: ["ctrl", "c"]

# 粘贴
- combo: ["ctrl", "v"]

# 全选
- combo: ["ctrl", "a"]

# 三键组合
- combo: ["ctrl", "shift", "n"]

对应源码中 Action 的 Combo []string 字段。引擎的 PressCombo 逻辑是：数组的最后一个元素作为主键，前面的都作为修饰键（modifier），最终调用 robotgo.KeyTap(key, modifiers...)。

例如 ["ctrl", "shift", "n"] 会被解析为：主键 n，修饰键 ctrl + shift，等价于按下 Ctrl+Shift+N。

6.3.1 常用组合键速查

提示：许多浏览器操作（刷新、前进、后退、切换标签）robotgo-flow 已经封装成了专门的动作（refresh/back/forward/switch_tab，见第 8 章），内部就是用组合键实现的。对于这些常见操作，优先使用语义化的浏览器动作，代码更清晰。

6.4 press 与 combo 的区别

初学者容易混淆 press 和 combo：

• press 按下一个键（可带该键的敲击），值是字符串：press: "enter"；
• combo 同时按下多个键的组合，值是数组：combo: ["ctrl", "c"]。

如果你只需要按一个键，用 press；如果需要「修饰键 + 主键」的快捷键，用 combo。

6.5 综合示例：登录表单

把键盘动作组合起来，完成一个典型的登录表单填写：

inputs:
  - name: user
    label: "账号"
    required: true
  - name: pass
    label: "密码"
    required: true
    mask: true

steps:
  - name: "填写登录信息"
    actions:
      - type: {into: "templates/input_user.png", text: "$input.user"}
      - type: {into: "templates/input_pass.png", text: "$input.pass"}
      - combo: ["ctrl", "a"]            # 若需要先清空，可全选
      - press: "enter"                   # 回车登录

再看一个「复制粘贴搬运数据」的例子：

steps:
  - name: "复制来源"
    actions:
      - click: "templates/source_field.png"
      - combo: ["ctrl", "a"]
      - combo: ["ctrl", "c"]
  - name: "粘贴到目标"
    actions:
      - click: "templates/target_field.png"
      - combo: ["ctrl", "v"]

6.6 中文与 Unicode 输入

得益于 robotgo 的能力，type 支持直接输入中文和其他 Unicode 字符：

- type: {into: "templates/comment.png", text: "这是一段中文备注"}

同时，框架的 internal/encoding 包会自动处理 Windows 中文环境下 GBK 与 UTF-8 的编码转换（例如从 GBK 编码的命令行参数、YAML 文件读入的中文），因此中文文本与中文模板路径都能正常工作，无需手动处理编码。

6.7 常见问题

6.8 小结

本章我们详解了三种键盘动作：type 会先点击输入框再输入文本、支持运行时变量与 Unicode；press 按下单个键、常用于回车与 Tab；combo 按下组合键、数组最后一个为主键其余为修饰键。我们厘清了 press 与 combo 的区别，演示了登录表单、数据搬运等组合用法，并说明了中文输入与编码处理。下一章，我们讲解等待、延时与滚动这三类控制节奏的动作。