# @androidtui/keymap 中文文档

规范地址：https://npmcn.com/package/%40androidtui/keymap/

版本：0\.8\.0
npm 元数据更新时间：2026-10-30T13:51:17.831Z
中文译文更新时间：2026-11-08T05:36:06.265Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40androidtui/keymap
原文对照：https://npmcn.com/package/%40androidtui/keymap/?lang=original
项目主页：https://github.com/bd-loser/opentui#readme
源码仓库：https://github.com/bd-loser/opentui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，94 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19\.2\.0，solid-js ^1\.9\.12，@opentui/react npm:@androidtui/react@0\.8\.0，@opentui/solid npm:@androidtui/solid@0\.8\.0
- 首次发布：2026-08-09T04:50:43.079Z
- 最新版本发布：2026-10-30T13:51:17.673Z
- 近 30 天下载量：1888（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

Android 和 Termux 上的 OpenTUI 应用程序的密钥绑定和命令序列

## 安装

```sh
npm install @androidtui/keymap
```

也可以使用：`pnpm add @androidtui/keymap`、`yarn add @androidtui/keymap`、`bun add @androidtui/keymap`

## README

# @ opentui/ keymap

用于终端和DOM应用程序的主机-不可知密钥映射引擎. 同一核心,多个适配器.

它将密钥绑定为与目标相接的有优先级、有重点的、有重点的地层(地铁可转换物或DOM元素)。 核心是故意裸露的;除了原始密钥调度之外,其他一切都是通过加通,解析器,扩展器,解析器和字段编译器选择入.

## 要点

-   **主机不可知核心** 过一个小 `KeymapHost` 与主机元数据、焦点、母机转录、目标销毁、关键新闻/释放、可选原始输入和合成命令事件相连接.
-   **目标意识重点路径** 全球层加局部层 `focus` 编号 : `focus-within` 沿活动目标母链排列的层.
-   **分层绑定** 优先排序 最新的第一联系, `fallthrough`,以及 `preventDefault` 控制系统.
-   **分支意识多键序列** 超过平面编译的装订, 并有公开的待处理序列 API, 同步 `pendingSequence` 事件、活动继续查询和对焦点变化的自动无效.
-   **可编程的精确 vs 前缀分解** (例如:. `g` 对 `gg`与 `runExact`, (中文(简体) ), `continueSequence`, (中文(简体) ), `clear`,并推迟 `AbortSignal` + 键 `sleep` 决定。 船型为Neovim式超时解析器.
-   **可插入绑定语言**:可叠装绑定解析器,密钥扩展器,层装绑定式变压器,绑定式变压器,命令解析器,命令解析器,以及所订购的事件相匹配解析器.
-   **广泛的计划和激活**:在地层上注册自定义字段,绑定并命令. 字段编译器可以弹出 `attrs`; 所有字段类型都可以通过 `require(...)` 财务报告和审定财务报表 `activeWhen(matcher)`。 。 。 .
-   **反应匹配器** 带有订阅驱动的状态通知,加上React store和Solid信号帮助器.
-   **原始和密钥截取** 正常约束发送之前和之后,包括预先约束 `consume({ preventDefault, stopPropagation })`,发送后处理/无匹配结果,以及原始投入 `stop()` 处理.
-   **命令目录和调度** 包含命名命令,内置命令处理器,命令链,命名空间,搜索,能见度级(`registered` 编号 : `reachable` 编号 : `active`)),有拘束的询问, `runCommand`,并注意焦点 `dispatchCommand`。 。 。 .
-   **缩写图快照和诊断** 对于分层,命令,绑定,序列节点,待决路径,不活动原因,有阴影,稳定的警告/错误代码,以及林特风格的分层分析器.
-   **B. 广泛的关键覆盖面** 在默认解析器中,包括函数键、导航/编辑键、numpad键、介质键、左/右修改符, `super`, (中文(简体) ), `hyper`文字 `+` 装订.
-   **平台感知修改名** 通过 `registerModBindings`,解决 `mod+...` 从主机元数据中保留显示字符串.

## 加词

`@opentui/keymap/addons` 现成构件:

-   `registerDefaultKeys` —— 说 `ctrl+shift+s` 样式解析器和事件匹配.
-   `registerLeader`, (中文(简体) ), `registerTimedLeader` ——带可选超时的领头符.
-   `registerEmacsBindings` —— 说 `ctrl+x ctrl+s` 和弦相会.
-   `registerExCommands` —— 说 `:write`\- 样式命令 `aliases` 财务报告和审定财务报表 `nargs`。 。 。 .
-   `registerCommaBindings`, (中文(简体) ), `registerModBindings`, (中文(简体) ), `registerAliasesField`, (中文(简体) ), `registerBindingOverrides`。 。 。 .
-   `registerEnabledFields`, (中文(简体) ), `registerMetadataFields` (单位:千美元)`desc`, (中文(简体) ), `group`, (中文(简体) ), `title`, (中文(简体) ), `category`) (中文(简体) ).
-   `registerNeovimDisambiguation`, (中文(简体) ), `registerEscapeClearsPendingSequence`, (中文(简体) ), `registerBackspacePopsPendingSequence`。 。 。 .
-   `registerDeadBindingWarnings`, (中文(简体) ), `registerUnresolvedCommandWarnings`。 。 。 .

`@opentui/keymap/addons/opentui` 添加 OpenTUI 专用棋子: 基底放出匹配通过 `event.baseCode` 对于非拉丁语密钥和数字行(与Core相同的规则),以及预线文本区域/编辑-缓冲命令。 直接事件匹配在倒计时匹配前获胜, 甚至跨层.

## 条目点

-   `@opentui/keymap` ——核心API
-   `@opentui/keymap/addons` ——普遍加价
-   `@opentui/keymap/addons/opentui` ——通用+OpenTUI加通
-   `@opentui/keymap/extras/graph` ——用于调试和图表 UIs 的图快取帮助
-   `@opentui/keymap/testing` ——宿主不可知的假键图宿主和用于加成测试的诊断
-   `@opentui/keymap/html` — HTML 适配器
-   `@opentui/keymap/opentui` — OpenTUI 适配器
-   `@opentui/keymap/react` —— 说 `KeymapProvider`, (中文(简体) ), `useKeymap`, (中文(简体) ), `useBindings`, (中文(简体) ), `useActiveKeys`, (中文(简体) ), `usePendingSequence`, (中文(简体) ), `reactiveMatcherFromStore`
-   `@opentui/keymap/solid` —— 说 `KeymapProvider`, (中文(简体) ), `useKeymap`, (中文(简体) ), `useKeymapSelector`, (中文(简体) ), `useBindings`, (中文(简体) ), `reactiveMatcherFromSignal`
-   `@opentui/keymap/extras` —— 欺骗表 UIs 的助手(`createBindingLookup`, (中文(简体) ), `commandBindings`, (中文(简体) ), `formatCommandBindings`(中文(简体) )

## 使用量

```tsx
import { registerDefaultKeys } from "@opentui/keymap/addons"
import { createOpenTuiKeymap } from "@opentui/keymap/opentui"
import { KeymapProvider } from "@opentui/keymap/react"

const keymap = createOpenTuiKeymap(renderer)
registerDefaultKeys(keymap)

createRoot(renderer).render(
  <KeymapProvider keymap={keymap}>
    <App />
  </KeymapProvider>,
)
```

创建密钥映射, 安装您想要的附加符, 然后将配置的实例传递到您的应用程序 。 React and Solid 的切入点通过上下文消耗了预设的 OpenTUI 密钥映射.

`Keymap` 是核心运行时间。 在需要图示或分层分析器时,将特征工厂传给其构造器.

## 适配器

适配器执行小型 `KeymapHost` 接口( e)`metadata`, (中文(简体) ), `rootTarget`, (中文(简体) ), `getFocusedTarget`, (中文(简体) ), `getParentTarget`, (中文(简体) ), `onKeyPress`, (中文(简体) ), `onKeyRelease`, (中文(简体) ), `onFocusChange`, (中文(简体) ), `onTargetDestroy`(中文(简体) ). HTML 适配器规范 DOM 密钥名称(`Escape` → `escape`, (中文(简体) ), `ArrowUp` → `up`, (中文(简体) ), `Meta` → `super`, (中文(简体) ), `Alt` → `meta`)和跟踪目标通过 `MutationObserver`。 OpenTUI 适配器钩 `CliRenderer` `keypress`, (中文(简体) ), `keyrelease`,焦点,破坏,目标破坏,以及原始输入事件.

## 格式化密钥

使用 `keymap.formatKey` 当显示原始绑定字符串时。 它通过键图的解析器和符号在字符串化之前运行它们.

```ts
keymap.formatKey("<leader>s", { separator: " " }) // "space s"
keymap.formatKey("<leader>s", { preferDisplay: true }) // "<leader>s"
```

## 重返大气层

运行时间/数据再入在发送过程中得到支持:命令处理器,截取,等待序列的收听者可以读取或写入运行时间数据和等待序列状态.

结构再入是 **没有** 已支持。 在发送时不要注册或取消注册层、标志、解析器或解析器.

## 安装

```bash
bun install @opentui/keymap
```

## 发展

```bash
bun run build
bun run test
bun src/keymap-benchmark.ts
```

HTML 演示居住在 Docs app 中 `/demos/keymap-html/` 下级 `packages/web`。 。 。 .

## 常见问题

### @androidtui/keymap 是什么？

Android 和 Termux 上的 OpenTUI 应用程序的密钥绑定和命令序列

### 如何安装 @androidtui/keymap？

在项目目录运行 npm install @androidtui/keymap，或使用 pnpm add / yarn add / bun add。

### @androidtui/keymap 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @androidtui/keymap 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @androidtui/keymap 可以商用吗？

@androidtui/keymap 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @androidtui/keymap 的下载量有多少？

根据 npm 官方下载统计，@androidtui/keymap 在 2026/10/06 – 2026/11/04 这 30 天内被下载 1,888 次，日均约 63 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @androidtui/keymap 还在维护吗？

最新版本 0\.8\.0 发布于 2026/10/30（8 天前）；至今共发布 29 个版本，其中过去 12 个月发布了 29 个；首次发布于 2026/08/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。