键位绑定动作参考

这是所有 Ghostty 键位绑定动作的参考。

忽略这个按键组合。

Ghostty 不会处理该组合，也不会把它转发给终端内的子进程，但操作系统或其他应用仍可能处理它。

解绑之前绑定的按键绑定。

这无法解绑未被 Ghostty 或用户绑定的绑定（例如由操作系统或其他应用设定的绑定）。

发送一个 CSI 序列。

值应为不带 CSI 头的 CSI 序列（ESC [ 或 \x1b[）。

例如，可以发送 csi:0m 来重置当前文本的所有样式。

发送一个 ESC 序列。

发送指定的文本。

使用 Zig 字符串字面量语法。目前不做校验。如果文本无效（即含有无效的转义序列），错误目前只会出现在日志中。

根据光标键模式是否启用（application）或禁用（normal），向 pty 发送相应数据。

重置终端。

当运行中的程序把终端搞成损坏状态时，这可以修复大量问题，等价于运行 reset 命令。

如果你在 TUI 程序（如 vim）中这样做，可能会破坏该程序。如果你在 shell 中这样做，可能需要再按一次回车才能得到新的提示符。

把选中的文本复制到剪贴板。

粘贴默认剪贴板的内容。

粘贴选区剪贴板的内容。

如果光标下有 URL，把它复制到默认剪贴板。

把终端标题复制到剪贴板。如果终端标题未设置或为空，这没有效果。

把字号增大指定的磅数（pt）。

例如，increase_font_size:1.5 会把字号增大 1.5 磅。

把字号减小指定的磅数（pt）。

例如，decrease_font_size:1.5 会把字号减小 1.5 磅。

把字号重置为最初配置的大小。

把字号设置为指定的磅数（pt）。

例如，set_font_size:14.5 会把字号设为 14.5 磅。

开始搜索给定文本。如果文本为空，则取消搜索。被取消的搜索不会禁用任何显示搜索的 GUI 元素；为此应使用显式的 end_search 绑定。

如果之前的搜索处于活动状态，则被替换。

开始搜索当前选中的文本。如果没有选区，什么都不做。如果已有搜索处于活动状态，这会改变搜索词。

在搜索结果中导航。如果没有活动搜索，不执行。

如果尚未开始搜索，则开始搜索。这不设置任何搜索词，但会打开用于搜索的 UI。

结束当前搜索（如有）并隐藏所有 GUI 元素。

清空屏幕与全部回滚缓冲。

选中屏幕上的所有文本。

滚动到屏幕顶部。

滚动到屏幕底部。

滚动到选中的文本。

滚动到屏幕上给定的绝对行，0 为第一行。

向上滚动一页。

向下滚动一页。

把屏幕滚动指定的页分数。

正值向下滚动，负值向上滚动。

例如，scroll_page_fractional:0.5 会把屏幕向下滚动半页，而 scroll_page_fractional:-1.5 会把它向上滚动一页半。

把屏幕滚动指定的行数。

正值向下滚动，负值向上滚动。

例如，scroll_page_lines:3 会把屏幕向下滚动 3 行，而 scroll_page_lines:-10 会把它向上滚动 10 行。

在给定方向或位置上调整当前选区，相对于光标。

警告：这不会创建新选区，而且当前没有选区时什么都不做。

有效参数是：

• left、right

  分别把选区向左或向右调整一格。

• up、down

  分别把选区向上或向下调整一行。

• page_up、page_down

  分别把选区向上或向下调整一页。

• home、end

  分别把选区调整到屏幕的左上角或右下角。

• beginning_of_line、end_of_line

  分别把选区调整到行首或行尾。

把视口向前或向后跳过给定数量的提示符。

需要 shell 集成。

正值向下滚动，负值向上滚动。

把整个回滚缓冲以指定动作写入临时文件。该动作决定对文件路径怎么做。

有效动作是：

• copy

  把文件路径复制进剪贴板。

• paste

  把文件路径粘贴进终端。

• open

  在系统默认的文本文件编辑器中打开该文件。

  默认的系统编辑器在 macOS 上通过 open 决定，在 Linux 上通过 xdg-open 决定。

把屏幕内容以指定动作写入临时文件。

可能的动作见 write_scrollback_file。

把当前选中的文本以指定动作写入临时文件。

可能的动作见 write_scrollback_file。

没有选中文本时什么都不做。

打开一个新窗口。

如果应用当前没有焦点，这会把它带到前台。

打开一个新标签页。

转到上一个标签页。

转到下一个标签页。

转到最后一个标签页。

转到具有特定索引的标签页，从 1 开始。

如果标签页编号大于标签页数量，这会转到最后一个标签页。

以相对偏移移动标签页。

正值把标签页向前移动，负值向后移动。如果新位置越界，会在标签页列表内循环取回。

例如，move_tab:1 把标签页向前移动一个位置，如果它已是列表中最后一个，则循环回到列表第一个。同样，move_tab:-1 把标签页向后移动一个位置，如果它本是第一个，则会变成最后一个。

切换标签页概览。

这只在 Linux 上受支持，且要求系统 libadwaita 版本为 1.4 或更新。可以通过运行 ghostty +version 查看当前 libadwaita 版本。

通过弹出的提示修改当前聚焦表面的标题。

通过弹出的提示修改当前标签页的标题。通过该提示设置的标题会覆盖终端设置的任何标题，并在该标签页内的焦点变化中持久保留。

设置当前聚焦表面的标题。

如果标题为空，表面标题被重置为空标题。

设置当前聚焦标签页的标题。

如果标题为空，则清除标签页标题覆盖。

在指定方向创建新分屏。

有效参数：

• right、down、left、up

  在相应方向创建新分屏。

• auto

  沿较大的一方创建新分屏。例如，如果父分屏当前宽于高，则会创建左右分屏，反之亦然。

把焦点移到指定方向的分屏（right、down、left 与 up），或按创建顺序移到相邻分屏（previous 与 next）。

聚焦前一个或下一个窗口（'previous'、'next'）

放大或还原当前分屏。

当分屏被放大时，它会占据当前标签页的整个空间，隐藏其他分屏。标签页或标签页栏也会通过显示一个放大状态图标来反映这一点。

切换当前表面的只读模式。

当表面处于只读模式时：

• 不向 PTY 发送任何输入（鼠标事件、按键编码）
• 输入仍可在终端级别用于选择、复制/粘贴（keybind）、滚动等
• 该状态下退出前警告总是启用，即使没有活动进程在运行

以指定的方向与数量（像素）调整当前分屏大小。两个参数应以逗号连接（,），如 resize_split:up,10。

把当前窗口中所有分屏的大小均分。

把窗口重置为默认大小。"默认大小"是新窗口被创建时的大小。窗口全屏时这没有效果。

只在 macOS 上实现。

控制终端检查器的可见性。

有效参数：toggle、show、hide。

显示 GTK inspector。

在 macOS 上没有效果。

如果存在屏幕键盘，则显示它。

只在 Linux（GTK）上实现。在 GNOME 上必须开启"屏幕键盘"辅助功能，可在 Settings > Accessibility > Typing 下找到。其他平台目前未测试。

在系统默认编辑器中打开配置文件。

如果系统默认编辑器未配置，这会失败。目前，打开配置的任何失败只会出现在日志中。

重新加载配置。

确切含义取决于使用的应用运行时，但这通常涉及重新读取配置文件并应用任何更改。注意并非所有更改都能在运行时应用。

关闭当前"表面"，无论它是窗口、标签页、分屏等。

这可能触发关闭确认弹窗，取决于 confirm-close-surface 配置设置的值。

关闭当前标签页及其所有分屏、关闭所有其他标签页，或关闭当前标签页右侧的每一个标签页，取决于模式。

如果未指定模式，默认为关闭当前标签页。

这可能触发关闭确认弹窗，取决于 confirm-close-surface 配置设置的值。

关闭当前窗口及其所有标签页与分屏。

这可能触发关闭确认弹窗，取决于 confirm-close-surface 配置设置的值。

关闭所有窗口。

警告：该动作已被弃用，在 Linux 或 macOS 上都没有效果。建议用户改用 all:close_window。

最大化或取消最大化当前窗口。

这在 macOS 上没有效果，因为它没有最大化窗口的概念。

对当前窗口执行全屏或取消全屏。

切换当前窗口的窗口装饰（标题栏、按钮等）。

只在 Linux 上实现。

切换终端窗口是否总是悬浮在其他窗口之上，即使未获得焦点。

终端窗口总是以普通（非悬浮置顶）窗口启动。

只在 macOS 上实现。

切换安全输入模式。

它用于防止应用在输入密码或其他敏感信息时监视你的键盘输入。

这适用于整个应用，不只是聚焦的终端。你必须手动取消该开关，或完全退出 Ghostty 才能停用。

只在 macOS 上实现，因为它使用内建的系统 API。

开启或关闭鼠标报告。

当鼠标报告被禁用时，即使终端应用请求鼠标事件，也不会收到报告。这让你总能把鼠标用于选择和其他终端 UI 交互，而不用被应用捕获鼠标输入。

这也可以通过 mouse-reporting 配置选项控制。

切换命令面板。

命令面板是一个弹窗，让你能看到可以执行哪些动作、与它们关联的键位绑定（如有）、一个用于过滤动作的搜索栏，以及随后执行动作的功能。

这在 Linux 上需要 libadwaita 1.5 或更新。可以通过运行 ghostty +version 查看当前 libadwaita 版本。

切换 quick terminal。

quick terminal 也被称为 "Quake 风格" 或下拉式终端，是一个按需从键位绑定呼出的终端窗口，通常从屏幕边缘（如顶部）滑入。这有利于快速访问终端，而不必打开新窗口或标签页。

终端状态在多次呼出之间保留，因此在已隐藏之后再次呼出 quick terminal 会显示同一个窗口，而不是创建新的。

由于 quick terminal 常常在其他窗口获得焦点时有用，它最适合配合 全局 keybind。例如，可以定义下面这个绑定，在系统中的任何地方按 Cmd+` 来切换 quick terminal：

keybind = global:cmd+backquote=toggle_quick_terminal

quick terminal 有一些限制：

• 同一时刻只能存在一个 quick terminal 实例。

• 与普通终端窗口不同，在支持窗口恢复的系统（如 macOS）上重启应用时，quick terminal 不会被恢复。

• 在 Linux 上，quick terminal 只支持 Wayland 而非 X11，且只支持实现了 wlr-layer-shell-v1 协议的 Wayland 合成器。实际上，这意味着只有 GNOME 用户无法使用该特性。

• 在 Linux 上，滑入动画只在 KDE 上受支持，且要求启用 "Sliding Popups" KWin 插件。

  如果你没有启用该插件，打开 System Settings > Apps & Windows > Window Management > Desktop Effects，并在插件列表中启用该插件。随后 Ghostty 需要完全重启才能生效。

• Quick terminal 分页只在 Linux 上受支持，macOS 不支持。这是因为 macOS 上的分页需要标题栏。

• 在 macOS 上，全屏的 quick terminal 总是处于非原生全屏模式。这是由 quick terminal 的渲染方式决定的要求。

关于 quick terminal 的各种配置见配置文件中的相关项，以自定义其行为。

显示或隐藏所有窗口。如果所有窗口都变为显示，我们还会确保 Ghostty 获得焦点。隐藏所有窗口时，焦点会被交给由操作系统决定的下一个应用。

注意：当聚焦表面处于全屏时，该方法什么都不做。

只在 macOS 上实现。

在透明与不透明之间切换窗口背景不透明度。

当 background-opacity 设为 1 或以上时这不做任何事。

当 background-opacity 小于 1 时，该动作会根据窗口当前的透明状态，把窗口变为透明或不透明。

只在 macOS 上实现。

检查更新。

只在 macOS 上实现。

尽可能撤销聚焦表面或终端上最近一次可撤销的动作。这可以撤销关闭标签页或窗口等动作。

并非 Ghostty 中的每个动作都可以撤销或重做。支持撤销/重做的动作列表目前限于：

• 新窗口、关闭窗口
• 新标签页、关闭标签页
• 新分屏、关闭分屏

所有动作只在有限时间内可撤销/重做。例如，恢复一个已关闭的分屏只能在分屏关闭后的若干秒内进行。确切时长由 undo-timeout 配置设置决定。

限制撤销/重做动作能确保内存使用随时间有界、已关闭的表面不会无限期地在后台继续运行，以及这些键位绑定能被终端应用使用。

只在 macOS 上实现。

尽可能重做聚焦表面或终端上最近一次可撤销的动作。关于什么可以与不可以撤销或重做的更多细节，见 "undo"。

结束当前活动的按键序列（如有），并把到此为止的按键冲刷给终端，不包括触发该动作的按键。

例如：ctrl+w>escape=end_key_sequence 会把 ctrl+w 编码给终端并退出该按键序列。

正常情况下，无效的序列会重置按键序列，并冲刷包括无效按键在内的所有数据。该动允许你只冲刷先前的按键，这在你想要绑定类似控制键（ctrl+w）但不发送额外输入的东西时很有用。