系统功能与参考

本页集中收录更适合查阅、而不是顺序学习的映射与项目资料。

功能键与系统控制

F1–F12 默认作为标准功能键；按住 Hyper 时发送对应的媒体或系统功能。青色区块覆盖整个顶行以及截图键。

截图键遵循同一条约定：单独的 Hyper 组合把截图放进剪贴板，再加 ⌘ 则写成桌面上的文件。

全尺寸键盘上的六键导航区提供同样三项系统控制的细粒度版本 —— 它发出的是 ⇧+ 加 ⌥ 加媒体键，也就是 macOS 自带的四分之一步长修饰键。

符号

✱ 是 Heavy Asterisk。普通星号的 ASCII 码正好是 42 —— 生命、宇宙以及任何事情的终极答案。

一条规则长什么样

配置里的每一条映射都是同一个形状。读懂一条，整个文件就都可读了，下面的定制一节也就不再吓人：

- description: 'control + h = ctrl + left (prev desktop)'
  type: basic
  from:
    key_code: h
    modifiers:
      mandatory: [left_control, right_command, right_control, right_shift, right_option]
  to:
    - key_code: left_arrow
      modifiers: [left_control]

mandatory 里那四个 right_* 修饰键就是 Hyper 本身 —— 它们出现在每一条规则里。旁边还有什么（这里是 left_control）就决定了控制平面。to 则是应用最终收到的东西。

版本历史

V2 只用到了少数几个平面。V3 引入四位二进制的平面模型，布局才得以扩展到 282 条映射而不至于变得随意。

随后 V3.1 有意调整了一些老用户会察觉的默认值：

• 剪贴板移到 6–0，1–5 不再是槽位；
• C 与 ⌘+ 加 C 启动 Codex 和 Claude；
• Spotlight 与 Alfred 5 取代 Launchpad 和 Alfred 4；
• F13 与 F14 改为截图，不再是上一首 / 下一首；
• ⌘+ 加 D 执行的是定义，而不是打开词典。

Windows 上的 AutoHotkey 版本仍以预编译程序与源码形式保留在仓库中，但不再针对当前 Windows 版本测试。

定制配置

YAML 是唯一的事实来源，JSON 由它生成。重新生成只需要一条命令，以及yq v4：

make -C mac_v3 compile

一个不错的入门定制是占用七个空闲平面之一：复制任意一条规则，改掉 mandatory 里的左侧修饰键，你就拥有了一整个键盘、且不与任何现有映射冲突的空间 —— 5 号平面（✱+ 加 ⌘+ 加 ⌃）与 7 号平面（✱+ 加 ⌘+ 加 ⌥+ 加 ⌃） 都是完全空的。

请始终保持 YAML 与生成的 JSON 同步：本站与 Karabiner 陈列馆发布的都是那份 JSON。

常见问题与排查

某个组合完全没反应。

先检查 Settings → Complex Modifications：十条规则是分别启用的，刚导入时一条都没开。如果规则已启用，就打开 Karabiner-EventViewer 再按一次 —— 它会显示真正到达系统的按键，从而区分「规则没生效」和「应用吞掉了这个快捷键」。

Caps Lock 能发 Escape，但别的都不管用。

这是只启用了第一条规则的典型症状。CapsLock to Hyper 只提供单击 Escape 与按住 Hyper，Hyper 之后能做什么，靠的是另外九条规则。

为什么某些组合会触发 macOS 系统诊断？

Issue #30 记录了 ⌘+ 加 ⌥+ 加 ⌃+ 加 ⇧+ 加 . 可能触发 macOS 系统诊断。若与自定义平面冲突， 请重新映射该系统快捷键。

为什么没有 Linux 支持？

Linux 桌面环境差异较大，作者本人主要通过 macOS 终端使用 Linux。原生支持可以使用 xmodmap 等工具实现，欢迎贡献。

仓库中为什么保留旧 macOS 版本？

旧版 Karabiner 使用 XML；macOS Sierra 以后由 Karabiner-Elements 接替，因此旧配置继续保留给历史系统。

这套设计是原创的吗？

最早的 AutoHotkey 版本可追溯到 2013 年，第一个 Mac 版本发布于 2015 年。当前配置长期收录于 Karabiner-Elements复杂规则陈列馆。

项目

CapsLock Enhancement 由 Vonng 维护，采用Apache License 2.0。源码、版本与问题跟踪位于 GitHub。