自定义键位绑定

Ghostty 通过 keybind 配置选项 支持灵活的自定义键位绑定。配置参考中有该选项的详细参考文档，但本页将给出在 Ghostty 中指定键位绑定的高层概述。

Note

CLI 命令 list-keybinds 可用于列出 Ghostty 的所有可用键位绑定。你可以运行它来查看默认值：

ghostty +list-keybinds --default

键位绑定配置的基本语法是：

keybind = trigger=action

键位绑定的 trigger 部分指定触发该动作的按键事件。触发器可以是单个按键、带修饰键的单个按键，或按键序列。

触发器由零个或多个修饰键与一个按键组合而成。例如 a、ctrl+a、ctrl+shift+a、ctrl+alt+a 都是有效触发器。

可能的按键集合目前只能通过 查看源代码 来参考。该列表源自 Chromium 的 keycodes，与带有 USB HID 码的按键紧密关联。

如果某个按键不在该列表中，你还可以指定一个 Unicode 码点。如果你的按键能解码成单个 Unicode 码点，Ghostty 会视其为有效触发器，并且当发生生成该码点的按键事件时触发器会激活。这在非美式键盘布局上特别有用。

例如，在德语键盘上你可以用下面的配置绑定 "ö"。当按下 "ö" 键（美式实体键盘上的 ";"）时会触发，因为该键在 Unicode 中生成 "ö"。

keybind = ctrl+ö=action

有效的修饰键有：

• shift
• ctrl（别名：control）
• alt（别名：opt、option）
• super（别名：cmd、command）

Note

键盘上的 fn 或 "globe" 键不被支持为修饰键。这是 Ghostty 所使用的操作系统与 GUI 工具包的限制。

触发器也可以以一些特殊值为前缀，以改变键位绑定的行为。这些下文列出。

键位绑定触发器对每个前缀组合而言不是唯一的。例如 ctrl+a 与 global:ctrl+a 不是两个单独的键位绑定。后设置的键位绑定会覆盖先设置的。在这种情况下，global: 键位绑定会被使用。

可以指定多个前缀。例如，global:unconsumed:ctrl+a=reload_config 会使键位绑定成为全局的，同时不消耗输入并重新加载配置。

使键位绑定应用到所有终端表面。默认情况下，键位绑定只应用于获得焦点的终端表面。如果其为真，那么键位绑定会被发送到所有终端表面。这仅适用于与表面相关的动作。对已经是全局的动作（即 quit），该前缀没有效果。

使键位绑定全局生效。默认情况下，键位绑定只在 Ghostty 内、并在正确的条件下（应用获得焦点、有时终端获得焦点等）才有效。如果你希望某个键位绑定在整个系统中全局有效（即即使 Ghostty 未被聚焦也有效），请指定该前缀。该前缀蕴含 all:。注意：这并非在所有环境中都有效；细节见下文的补充说明。

该功能仅在 macOS 上受支持。在 macOS 上，该功能要求授予 Ghostty 辅助功能权限。当指定了 global: 键位绑定且 Ghostty 被启动或重新加载时，Ghostty 会尝试请求这些权限。如果权限未被授予，该键位绑定将不工作。在 macOS 上，你可以在系统偏好设置 -> 隐私与安全 -> 辅助功能中找到这些权限。

Note

global: 前缀仅在 macOS 上可用。

不消耗输入。默认情况下，键位绑定会消耗输入，这意味着相关联的编码（若有）不会被发送到终端中正在运行的程序。如果你希望把编码后的值发送给程序，请在整个键位绑定之前指定 unconsumed: 前缀。例如：unconsumed:ctrl+a=reload_config。

无论该设置如何，global: 与带 all: 前缀的键位绑定总是消耗输入。由于它们不与任何特定终端表面关联，它们从不被编码。

只有在动作能被执行时才消耗输入。例如，copy_to_clipboard 动作只在有可复制的选区时才消耗输入。若没有选区，Ghostty 的表现就像该键位绑定未被设置一样。这对 global: 或带 all: 前缀的键位绑定没有影响。对于按键序列，如果动作无法执行，序列会被重置（行为与完全没设置键位绑定相同）。

可执行判定的键位绑定不会作为菜单快捷键出现在应用菜单中。这是因为菜单快捷键会无视终端状态而强制执行动作。可执行判定的键位绑定仍然会工作，只是不会作为快捷键标签出现在菜单里。

示例：

keybind = performable:ctrl+c=copy_to_clipboard

动作是触发器被激活时发生的事情。其格式为 action，若动作需要参数则为 action:parameter。

下面是一些可以在键位绑定中使用的常见动作。请查看完整动作列表 来得到完整列表。Ghostty 支持数十个动作。

动作	描述
ignore	什么都不做，忽略按键输入。这可以用来把某些输入丢进"黑洞"，使其既无效果也不产生编码。
unbind	移除该绑定。这会使之前的动作被移除，且按键在可打印时会直接传给子命令。
text:text	发送一个字符串。使用 Zig 字符串字面量语法，即 text:\x15 发送 Ctrl-U。可以使用 \x1b[ 前缀发送控制序列，但建议改用便利动作 csi: 与 esc:。
csi:text	发送一个 CSI 序列。例如 csi:A 发送"光标上移"。
esc:text	发送一个 escape 序列。例如 esc:d 向右删除到词尾。