在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

junegunn/fzf

菜单

键绑定自定义

相关源文件

本文档介绍了如何在 fzf 中定制键绑定，以增强您与模糊查找器的交互。键绑定允许您将按键和事件映射到特定操作，从而使您能够创建定制的工作流程并提高生产力。有关 shell 集成功能的更多信息，请参阅Shell Integration。

键绑定系统概述

在 fzf 中，键绑定将用户输入（按键或事件）与修改应用程序行为的操作连接起来。键绑定系统包含三个主要组件：

  1. 按键/事件：触发操作的触发器（按键或系统事件）。
  2. 操作：执行特定功能的运算符。
  3. 绑定：按键/事件与操作之间的连接。

来源：src/terminal.go290-291 src/terminal.go450-595 src/options.go1396-1421

基本键绑定语法

您可以使用 --bind 选项，后跟一个逗号分隔的绑定表达式列表，来定制键绑定。

fzf --bind KEY:ACTION,KEY2:ACTION2,...

每个绑定表达式遵循 KEY:ACTION 的格式，其中：

  • KEY 是一个键标识符（例如，ctrl-j、alt-enter）或一个事件名称（例如，change、start）。
  • ACTION 是一个操作名称，可选参数（例如，accept、execute(ls)）。

您还可以将多个按键和事件绑定到同一个操作。

fzf --bind 'start,ctrl-r:reload:ps -ef'

来源：man/man1/fzf.11056-1058 man/man1/fzf.11152-1157

默认键绑定

fzf 随附一套用于常见操作的默认键绑定。

来源：src/terminal.go670-746 src/terminal.go450-599

可绑定的按键

fzf 支持多种可以绑定到操作的键标识符。

键类型示例
Ctrl 键ctrl-a 至 ctrl-z, ctrl-space, ctrl-\
Alt 键alt-a 至 alt-z, alt-/
功能键f1 至 f12
特殊按键enter, space, bspace, esc, tab, btab (shift-tab)
箭头键up, down, left, right
鼠标操作left-click, right-click, scroll-up, scroll-down

您也可以直接绑定任何单个字符键。

来源：man/man1/fzf.11360-1467

可用事件

事件是可绑定到操作的系统触发的发生。

事件描述
startfzf 启动时触发一次。
load初始输入流完成时触发。
change查询字符串更改时触发。
result过滤完成且结果列表就绪时触发。
focus因光标移动导致焦点改变时触发。
one只有一个匹配项时触发。
zero没有匹配项时触发。
resize终端大小改变时触发。
backward-eof尝试删除已为空的查询字符串时触发。
jump在跳转模式下成功跳转到目标项目时触发。
jump-cancel取消跳转模式时触发。
click-header在标题栏中发生鼠标单击时触发。

来源：man/man1/fzf.11469-1598 CHANGELOG.md579-1068

可用操作

fzf 提供了许多可以绑定到按键或事件的操作。以下是一些重要的类别：

  • up, down：向上/向下移动光标（实现为 actUp, actDown）。
  • page-up, page-down：向上/向下翻页（actPageUp, actPageDown）。
  • half-page-up, half-page-down：向上/向下滚动半页（actHalfPageUp, actHalfPageDown）。
  • jump：类似于 EasyMotion 的 2 键移动（actJump）。
  • first, last：移动到第一个/最后一个项目（actFirst, actLast）。
  • pos(N)：移动到位置 N（负值表示从末尾开始）（actPosition）。

选择操作

  • accept：接受当前选择（actAccept）。
  • accept-non-empty：仅当存在选择时接受（actAcceptNonEmpty）。
  • toggle：切换当前选择（actToggle）。
  • select-all, deselect-all：选择/取消选择所有匹配项（actSelectAll, actDeselectAll）。
  • toggle-all：切换所有匹配项的选择状态（actToggleAll）。
  • toggle-in, toggle-out：切换并向上/向下移动（actToggleIn, actToggleOut）。

搜索/查询操作

  • clear-query：清除查询字符串（actClearQuery）。
  • change-query(text)：更改查询字符串（actChangeQuery）。
  • transform-query(cmd)：使用外部命令转换查询（actTransformQuery）。
  • search(text)：使用给定字符串触发搜索（actSearch）。

预览操作

  • preview(cmd)：执行预览命令（actPreview）。
  • preview-up, preview-down：滚动预览窗口（actPreviewUp, actPreviewDown）。
  • toggle-preview：切换预览窗口可见性（actTogglePreview）。

执行操作

  • execute(cmd)：在不离开 fzf 的情况下执行命令（actExecute）。
  • execute-silent(cmd)：静默执行命令（actExecuteSilent）。
  • become(cmd)：用命令替换 fzf 进程（actBecome）。
  • reload(cmd)：重新加载候选列表（actReload）。

状态修改操作

  • change-prompt(text)：更改提示符字符串（actChangePrompt）。
  • transform-prompt(cmd)：使用外部命令转换提示符（actTransformPrompt）。
  • change-preview-window(opts)：更改预览窗口选项（actChangePreviewWindow）。
  • track-current：在更新期间跟踪当前项目（actTrackCurrent）。

来源：src/terminal.go450-599 src/options.go1486-1730

操作组合

可以使用 + 分隔符将多个操作链接在一起。

fzf --bind 'ctrl-a:select-all+accept'

这将按顺序执行操作。如果包含会终止 fzf 的操作（例如 accept 或 abort），则会忽略后续操作。

来源：src/options.go1486 src/options.go1496-1730

带参数的操作

许多操作都可以接受参数。通用语法是：

action-name(argument)

例如

fzf --bind 'ctrl-v:preview(cat {})'

如果参数包含括号，您可以使用替代表示法来避免解析错误。

action-name[argument]
action-name{argument}
action-name<argument>
action-name~argument~

还有其他几种表示法可以避免解析问题。

来源：man/man1/fzf.11744-1776 CHANGELOG.md740-760

占位符表达式

占位符可以在操作参数中使用，以引用动态值。

占位符描述实现
{}当前行（项目）placeholderItem
{q}当前查询字符串placeholderQuery
{n}当前项目的零基序数索引。placeholderOrdinal
{+}选定的项目，每个项目单独引用placeholderItems
{+f}包含所选项目的文件夹路径placeholderItemsFile
{s}使用字段索引表达式时保留空格placeholderFlags 中的标志
{r}原始输出，不带引号placeholderFlags 中的标志

可以使用字段索引表达式来提取特定字段

fzf --bind 'enter:execute(echo Field 1: {1})'

来源: src/terminal.go69-70 src/terminal.go627-634

高级按键绑定技巧

转换操作

转换操作允许根据命令的输出有条件地执行其他操作

fzf --bind 'enter:transform:[[ -n {} ]] && echo accept || echo "change-header:Invalid selection"'

这实际上是在您的按键绑定中创建了一个 if-else 语句。转换操作（actTransform）执行一个命令，然后将输出作为新操作进行处理。

来源: src/terminal.go549-550 src/options.go1841-1842

动态按键绑定管理

您可以在运行时修改按键绑定

  • unbind(KEY): 移除按键绑定 (actUnbind)
  • rebind(KEY): 解绑后恢复按键绑定 (actRebind)
  • toggle-bind: 切换按键绑定状态 (actToggleBind)
fzf --bind 'ctrl-g:unbind(ctrl-t)+change-header:Unbound'

这些操作会修改 Terminal 结构中的 keymap 和 keymapOrg 映射，以动态更改可用的按键绑定。

来源: src/terminal.go590-592 src/options.go1793-1795

交互式命令执行

您可以在不离开 fzf 的情况下执行命令

fzf --bind "enter:execute(less {})"

这会在 less 中打开选定的文件。该命令在新终端会话中执行，fzf 在返回控制之前等待其完成。

来源: man/man1/fzf.11779-1786 CHANGELOG.md827-835

通过环境变量控制状态

fzf 会将一些环境变量导出到子进程，这些变量可用于自定义命令

可变描述代码中的来源
$FZF_QUERY当前查询字符串。FZF_QUERY="+string(t.input)"
$FZF_PROMPT提示字符串FZF_PROMPT="+string(t.promptString)"
$FZF_PREVIEW_LINES预览窗口的行数预览环境中的 LINES=%d
$FZF_PREVIEW_COLUMNS预览窗口的列数预览环境中的 COLUMNS=%d
$FZF_POS列表中光标的垂直位置FZF_POS=%d
$FZF_ACTION上一个执行的操作的名称FZF_ACTION="+t.lastAction.Name()"
$FZF_KEY上一个按下的键的名称FZF_KEY="+t.lastKey"

这些可以用来创建动态行为

fzf --bind 'focus:transform-preview-label:echo [ Position: $FZF_POS ]'

来源: src/terminal.go1078-1137 src/terminal.go1092-1117

实际示例

以下是一些按键绑定自定义的实用示例

简单的导航和选择

fzf --bind 'ctrl-a:select-all,ctrl-d:deselect-all,ctrl-t:toggle-all'

动态预览窗口

git ls-files | fzf --preview 'cat {}' \
    --bind 'ctrl-/:toggle-preview' \
    --bind 'ctrl-y:execute-silent(echo {} | clipboard)+abort'

交互式文件浏览器

find . -type f | fzf \
    --bind 'enter:execute(less {})' \
    --bind 'ctrl-e:execute(vim {})' \
    --bind 'ctrl-y:execute-silent(echo {} | xclip -selection clipboard)'

条件执行

fzf --bind 'enter:transform:[[ -n {} ]] && echo accept || echo "change-header:Please select an item"'

跳转导航

fzf --bind 'space:jump,jump:accept'

来源: man/man1/fzf.11056-1058 CHANGELOG.md450-550 CHANGELOG.md792-827

与 Shell 脚本集成

按键绑定在将 fzf 与 shell 脚本集成时特别有用。例如

来源: man/man1/fzf.11779-1786 CHANGELOG.md1049-1062

按键绑定架构

fzf 中按键绑定系统的内部架构如下所示

来源: src/terminal.go290-291 src/terminal.go450-599 src/terminal.go670-746

结论

按键绑定自定义是 fzf 的一个强大功能，它允许您创建定制的工作流程。通过了解可用的键、事件和操作，您可以显著提高使用 fzf 的效率。尝试不同的组合，找到最适合您特定用例的设置。

请记住，您还可以通过 FZF_DEFAULT_OPTS 环境变量设置默认的按键绑定，这样就不必每次运行 fzf 时都指定它们了。