自定义

• 1: 键盘编辑器
• 2: App 规则
• 3: 动作
• 4: Hyper 模式与方案行为
• 5: 设置、菜单栏与统计

1 - 键盘编辑器

「键盘」页就是编辑器。它按所选平面画出你的键盘，并在每个已映射的键上标注动作。你的键盘上没有的键（例如 F16，或笔记本上的数字小键盘）列在「不在此键盘上的键」中；轻按和双击类映射列在「其他触发方式」中。在工具栏切换到「列表」，可以看到按触发方式分组的列表。

修改一个键

点按一个键，弹出框显示它的组合键、所在平面和当前「动作」：

• 「更改」：改选另一个内置动作或你的自定义动作。
• 「编辑…」：打开完整的映射编辑器，见下文。
• 「显示 YAML」：显示这条映射在文件中的原样内容。
• 「恢复 Classic 默认」：恢复 Capslock Classic 中的动作；只有当该键与 Classic 布局不同时才出现。

有三个按钮可以让一个键不再执行映射的动作，区别在于之后这个键做什么：

没有映射的键会显示「此平面上未映射。」、它当前的行为，以及「指定动作」按钮。

新建映射

点击工具栏中的「+」，或在某个键上点「编辑…」，即可打开映射编辑器。

触发方式，可选：

• 「Caps + 按键」：按下要捕获的键，再用 ⌘ ⌥ ⌃ ⇧ 开关选择平面。
• 「轻按 Caps」：轻按 Caps Lock 时执行的动作（默认是 Escape）。
• 「双击 Caps」：在双击间隔内连按两次。设置后，单击会等过这个间隔再执行。
• 「双击修饰键」：连按两次左侧或右侧的 ⌘、⌃、⌥、⇧ 或 fn（fn 为实验性）。

「更改触发方式」可以把已有映射移到另一个键、平面或触发方式上，动作和 App 规则随之移动。

默认动作：在所有 App 中生效，除非下方有 App 规则匹配。可以选择内置动作、你的自定义动作、「新建动作…」，或直接在此定义。

App 规则：可选。每条规则指定一个或多个 App，以及在这些 App 中执行的动作。见App 规则。

每个键在每个平面上只能有一条映射，编辑器会拒绝重复。

修改如何生效

每次保存都会先校验，然后把整份配置一次性写入磁盘，最后才切换正在运行的键盘。一处修改要么完整生效，要么完全不生效。

工具栏中的「撤销」「重做」，或 ⌘Z 与 ⇧⌘Z，可以撤回或重做最近一次映射修改。只保留一步， Capslock 重新启动后历史清空。

如果你在其他应用中编辑了配置文件，下次切回 Capslock 时它会重新加载。会覆盖这类外部修改的保存会被拒绝，你可以在新内容之上重新修改。

导入、导出与 Classic 布局

工具栏的「更多」菜单中有三条命令：

• 「导出」：把整份配置（包括自定义动作和方案行为）写入一个 YAML 文件，默认名为capslock-config.yml。
• 「导入」：读取这样的文件，替换你当前的全部映射；自定义动作会合并。当前文件会先备份。导入文件中的 Shell 命令和睡眠动作会被停用，直到你重新复核并信任。
• 「安装 Capslock Classic V3」：重新安装内置布局。它会先展示经过校验的预览（包括它要打开的哪些 App 尚未安装），然后在替换映射之前请你确认。你的自定义动作、App 设置和 Hyper 模式保持不变，并且会先保存备份。

2 - App 规则

App 规则让一个键在特定 App 位于前台时执行不同的动作，而不影响它在其他地方的行为。

规则如何匹配

每条映射都有一个「默认动作」，并可以带一组「App 规则」。按下组合键时，Capslock 用前台 App 自上而下地检查这些规则，第一条包含该 App 的规则生效；如果都不匹配，就执行默认动作。

App 以精确的 Bundle ID 识别，例如 com.apple.Safari。即使 App 被移动或改名，规则依然有效，也绝不会误匹配名称相近的其他 App。

添加规则

从某个键开始：

1. 在「键盘」页点按该键，再点「编辑…」。
2. 在「App 规则」下点击「添加 App 规则」。
3. 在「适用于」下点击「添加 App」，选择一个或多个 App。
4. 选择在这些 App 中执行的动作，然后保存。

也可以在「App 规则」页点击「添加规则…」，选好 App 后，映射编辑器会自动填入该 App。如果 App 尚未安装，可以直接输入它的 Bundle ID，而不用浏览选择。

用规则旁的箭头调整顺序。每条规则至少要包含一个 App。

「App 规则」页

「App 规则」页列出所有设置了规则的 App，标出其中未安装的，并显示每条规则。在某个 App 的菜单中，可以为它再添加规则，或「移除全部规则」。移除某个 App 的全部规则是一次修改：会先备份，并且可以撤销。

在配置文件中

规则是映射上的一条 bindings。下面这条让 ⇪ N 在其他地方照旧用 ⌥⌫ 删除前一个词， 但在终端和 iTerm 中改为发送 Shell 习惯的 ⌃W：

- trigger:
    kind: hyper_plus_key
    key: 78            # N
    plane: 0           # Base
  action:
    kind: key_combo
    target_key: 8      # Backspace
    with_alt: true
  bindings:
  - when:
    - type: frontmost_app
      include:
      - com.apple.Terminal
      - com.googlecode.iterm2
    action:
      kind: key_combo
      target_key: 87   # W
      with_ctrl: true

编辑器无法显示的规则会标为「高级规则（在 YAML 中编辑）」，并原样保留。见配置文件。

3 - 动作

映射执行的是动作。动作分为内置动作和你自己的动作，「动作」页同时列出两者；内置动作不能修改，但都可以被映射。

内置动作

这些 ID 是永久的：引用它们的映射在各个版本中都能继续使用。

自定义动作

在「动作」页点击「新建动作…」，或在映射编辑器中直接定义。可用的类型有：

Classic 布局使用的鼠标、滚动、睡眠、剪贴板槽位和媒体动作列在「鼠标与系统」下。你可以把它们映射到其他键，但不能新建这类动作。

正在被映射使用的动作不能删除；「动作」页会列出需要先移除的映射。

Shell 命令与信任

保存 Shell 命令时会询问「信任此动作？」：受信任的动作以你的用户权限运行，可以修改文件、访问网络，暂停和撤销都无法挽回它已做的事。点击「信任并保存」保留它。「Mac 睡眠」和「显示器睡眠」动作也会出现同样的询问。

命令不会在无意中获得信任：

• 修改命令文本会撤销信任，直到你再次确认。
• 导入的配置中的所有命令和睡眠动作都处于停用状态，显示为「已停用 · 待审阅」；在编辑器中打开并保存即可确认。
• 未受信任的命令不会运行，无论配置文件里写了什么。

命令在后台运行，输出被丢弃；Capslock 不会记录它们打印的内容。

切换输入法

默认布局中的 ⇪ Space 发送 ⌃Space，因此 macOS 会使用你为「选择上一个输入法」设置的快捷键。如果想直接切换到某个输入法，把一个键映射到「切换输入法」并选中它。

部分中文、日文和韩文输入法在被直接切换时不能可靠生效。「设置 › 输入法」为切换输入法的 Caps + 按键映射提供两种修正方式：

• 「模拟快捷键」：按下「选择上一个输入法」快捷键。在 macOS 26 之前更可靠，需要在系统设置中打开该快捷键。
• 「切换焦点」：短暂移动焦点，让新的输入法生效。在 macOS 26 上效果更好，但在浮动窗口中无效。

4 - Hyper 模式与方案行为

Hyper 模式

「设置 › Hyper 键 › Hyper 模式」有两个选项，首次引导时也会让你选择。

如果你在其他应用中有依赖 Hyper（⌃⌥⇧⌘）的快捷键，或是从 Karabiner-Elements 配置迁移过来，选「经典」。如果没有别的应用监听 Hyper，并且希望左右两侧的修饰键都能选择平面，选「原生」。

在经典模式下，右侧修饰键由 Capslock 自己按住，所以只有左侧能用来选择平面。

未映射的组合键

「设置 › 方案行为 › 未映射的 Caps 组合键」决定没有映射的组合键（例如基础平面上的 ⇪ A） 做什么：

映射为「保持原键」的键，无论这里怎么设置，都总是输出自己；被「移除映射」的键则遵循这里的设置。见修改一个键。

修饰键左右

「设置 › 方案行为 › 修饰键左右」决定哪些 ⌘ ⌥ ⌃ ⇧ 用于选择平面：

• 「自动」（默认）：经典模式下仅左侧，原生模式下左右皆可。
• 「仅左侧」。
• 「左右皆可（原生）」：仅在原生模式下可用。

这两项方案设置保存在你的配置中，会随导出、导入、备份和撤销一起生效。

双击间隔

「设置 › Hyper 键 › 双击间隔」是两次轻按之间仍算作双击的最长间隔：默认 200 毫秒，范围 100 到 500 毫秒。它作用于「双击 Caps」和「双击修饰键」类映射。

把右侧修饰键变成额外按键

「设置 › 高级 › 改键」可以把闲置的右侧 ⌘、⌥、⌃ 或 ⇧ 变成 F13、F14、F15、F16、F17 或 F19，用作任意应用中的快捷键。被改键的修饰键不再作为修饰键使用，左侧的同名键不受影响。 F18 保留给 Caps Lock。

5 - 设置、菜单栏与统计

设置

设置保存在 app_config.yml 中，见配置文件。

「状态」「权限」「恢复」三个分组重复了主页和诊断页上的控制项：暂停与继续、权限状态、全部松开、恢复 Caps Lock，以及显示配置文件夹。

底部的「重置设置…」会把所有设置恢复为默认值，你的映射、动作和 App 规则保持不变。

菜单栏

菜单栏图标始终存在：运行时是实心的 ⇪，暂停时是空心的，需要处理问题时显示警告三角。菜单包含：

• 当前状态；
• 「暂停」或「继续」；
• 「检查更新」（正式版提供）；
• 「Capslock 网站」；
• 「打开 Capslock」；
• 「退出 Capslock」（⌘Q）。

关闭主窗口或按 ⌘W 只会隐藏窗口，Capslock 继续运行。

统计

「统计」页显示每个触发方式的使用频率，可选今天、近 7 天、近 30 天或全部，并列出「最常用」排行。

• 每次物理按下计一次；按住不放导致的重复也只计一次。
• 次数归属于触发方式，因此改绑一个键不会丢失它的历史。
• 按天的计数保留 30 天，更早的部分并入全部累计。
• 只在本机保存次数，从不记录你输入的内容。

「重置统计」会清除所有计数，且无法撤销。「设置 › 高级 › 在映射上显示次数」控制是否在映射旁显示次数。