内置 keymap 插件

@opentui/keymap 保持引擎精简。内置插件包在公共注册 API 之上安装解析器阶段、字段编译器、诊断、消歧义和宿主特定的辅助函数。

如果您想构建自己的插件，请参阅自定义插件。

每个插件都返回一个 disposer。

import * as addons from "@opentui/keymap/addons"
import * as opentuiAddons from "@opentui/keymap/addons/opentui"

通用插件

默认值

共享的默认解析器接受单按键命名键、修饰键组合、字面标点符号、" " 表示空格、"+" 作为字面加号键、<token> 别名和 {pattern} 运行时捕获。它解析连接的多按键序列，如 dd、<leader>s 或 {count}j。

如果解析的序列引用了未知令牌，该扩展绑定会被跳过直到令牌注册。这是一种失败关闭行为：没有注册的 leader 令牌时，<leader>s 不会变成普通 s。

识别的修饰键前缀（不区分大小写，用 + 连接）：

字段插件

registerBindingOverrides() 期望 bindingOverrides 已经是一个 Binding[] 数组。它在注册时一次性重写该层的绑定数组。匹配的字符串命令会被覆盖绑定替换，未匹配的绑定保持不变。

registerEnabledFields() 接受 boolean、() => boolean 或 ReactiveMatcher 值。它适用于层和命令，而不适用于绑定。它仅控制激活；不发布 attr。

registerMetadataFields() 在暴露到投影之前验证和修剪元数据字段。绑定 desc / group 成为绑定元数据。命令 desc / title / category 成为 commandAttrs 中的命令元数据。

层元数据是应用特定的。直接使用 registerLayerFields() 注册层字段，并在图/调试可视化需要层标签或分组元数据时调用 ctx.attr(...)。

registerAliasesField() 添加绑定而不是替换原始绑定，别名保留在声明它们的层本地。

语法和序列插件

选项：

在注册同层精确/前缀绑定（如 g 和 gg）之前注册消歧义插件。

Leader trigger 接受按键字符串、按键对象、类绑定的 { key }，或来自 createBindingLookup().get(...) 的单个绑定查找结果。空查找结果被视为禁用并返回空操作 disposer；包含多个绑定的查找结果会被拒绝。

支持禁用 leader 键的应用可以省略 leader 插件或传递空查找结果。任何 <leader>... 绑定将保持休眠，因为未解析的令牌会被跳过。

诊断

Ex 命令

registerExCommands() 安装 ex 命令字段编译器、命令转换器和 :name ...args 字符串的解析器。通过使用冒号前缀的命令名称或 namespace: "excommands" 在正常 keymap 层中注册 ex 命令。

import { registerExCommands } from "@opentui/keymap/addons"

registerExCommands(keymap)

keymap.registerLayer({
  commands: [
    {
      name: "write",
      namespace: "excommands",
      aliases: ["w"],
      nargs: "1",
      desc: "Write file",
      run({ payload }) {
        // payload.raw === ":write session.log"
        // payload.args === ["session.log"]
      },
    },
  ],
})

ExCommand 字段：

• 已注册的 ex 命令默认 namespace 为 excommands。
• 别名产生额外的已注册命令，例如 :write 和 :w。
• 额外字段保留在 getCommands() / getCommandEntries() 结果中，并通过命令字段插件编译。
• runCommand(":write file.txt") 和 dispatchCommand(":write file.txt") 都通过已安装的解析器。

OpenTUI 插件

@opentui/keymap/addons/opentui 重新导出所有通用插件并添加以下 OpenTUI 特定的辅助函数。

registerBaseLayoutFallback()

添加一个事件匹配解析器，回退到 KeyEvent.baseCode，使绑定在 Kitty 基础布局报告可用时可以忽略活动键盘布局更改。直接击键匹配优先于基础布局回退匹配，即使跨越活跃层也是如此。

编辑缓冲区辅助函数

registerManagedTextareaLayer() 接受全局 Layer 形状加上可选的 bindings，但它有意排除了 target 和 targetMode。该辅助函数是全局的，跟随 renderer.currentFocusedEditor。

EditBufferCommandOptions：

registerEditBufferCommands() 和 registerTextareaMappingSuspension() 在每个 keymap 上是引用计数的，因此多个集成可以安全地共享它们。

EditBufferCommandName

生成的 textarea 绑定来自 @opentui/core 中的共享 defaultTextareaKeyBindings。createTextareaBindings() 在这些默认值之前前置覆盖，因此自定义绑定按顺序优先。

请参阅自定义插件了解公共插件编写 API、生命周期规则、回调上下文和扩展点特性。