从一个触发词，到一整套文本自动化

基础与多触发词

一个 trigger 对应一段 replace；需要多个别名时改用 triggers 列表，它们展开为同一段内容。

matches:
  - trigger: ":tel"
    replace: "0755-8601-XXXX"

  - triggers: [":wx", ":wechat", ":微信"]
    replace: "微信号：espanso_cn"

整词匹配与大小写传递

用于纠错类场景：word: true 只在该词独立成词时触发，不会把 other 误改成 othere；propagate_case: true 会保留你输入时的大小写风格。

  - trigger: "alh"
    replace: "although"
    word: true
    propagate_case: true

# alh  → although
# Alh  → Although
# ALH  → ALTHOUGH

正则触发词

用 regex 取代 trigger，即可用完整正则语法定义触发条件。Espanso 会把命名分组自动转换为变量，直接写进替换内容或传给脚本。

  - regex: ":id-(?P<num>\\d{4})"
    replace: "工单编号 #{{num}}"

# 输入 :id-2048 → 工单编号 #2048

命名分组必须写成 (?P<名称>…)，缺少 P 不会生效——Espanso 使用的是 Rust regex 语法。

同一触发词的多选消歧

如果多条规则共用同一个触发词，Espanso 不会随机选一个，而是弹出选择框让你挑。签名、报价模板这类有多版本的场景很实用。

  - trigger: ":sig"
    replace: "此致敬礼，\n张工 · 产品部"
    label: "正式签名"

  - trigger: ":sig"
    replace: "祝好，\n张工"
    label: "简短签名"

表单能做什么

• 一次填多个字段：用 [[字段名]] 声明占位，Espanso 自动生成对应输入框。
• 多种控件可选：单行文本、多行文本（multiline: true）、下拉选择（type: choice）与列表框（type: list）。
• 结果可再次加工：字段值既可直接拼进文本，也能作为参数传给脚本或 Shell 命令。
• 复杂模板不必复制多份：同一份模板靠填表区分对象，比维护十几条独立规则更易管理。

脚本与命令的边界

• Shell 命令：默认在 Windows 使用 PowerShell、Linux 使用 bash，macOS 自动探测用户 shell；可用 shell 参数显式指定 bash、zsh、fish、pwsh 等。
• 外部脚本：官方建议把脚本放在配置目录的 scripts/ 下，用 %CONFIG%/scripts/xxx.py 写路径，换机器不用改。
• 环境变量：执行时 Espanso 会注入 CONFIG（配置目录路径）以及此前已求值的变量。
• 调试：给 shell 加上 debug: true 会把执行详情写入日志，用 espanso log 查看。

配置的三个层次

• 默认配置：config/default.yml，对所有程序生效。
• 程序配置：在 config/ 下新建文件，用 filter_title 或 filter_class 指定目标程序，覆盖默认设置。
• 片段组织：match/ 下的文件可按主题拆分，用 extra_includes 组合，避免单文件过长。

其他实用开关

• 退格撤销：展开后立即按退格键可回退，恢复原来的触发词。可用 undo_backspace: false 关闭。
• 开关快捷键：可自定义一键启用 / 暂停 Espanso，临时避免干扰。
• 搜索触发：除 Alt + Space 外，也可配置成输入某个字符串唤起搜索栏。