自訂鍵位綁定

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 向右刪除到詞尾。