# @gentleduck/vim 中文文档

规范地址：https://npmcn.com/package/%40gentleduck/vim/

版本：0\.3\.0
npm 元数据更新时间：2026-05-30T06:22:41.158Z
中文译文更新时间：2026-11-16T04:10:21.465Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gentleduck/vim
原文对照：https://npmcn.com/package/%40gentleduck/vim/?lang=original
项目主页：https://gentleduck.org/duck-ui
源码仓库：https://github.com/gentleeduck/gentleduck

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

- 包体积（解压后）：49.6 kB，62 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- peer 依赖：react ^18 \|\| ^19，react-dom ^18 \|\| ^19
- 首次发布：2025-09-02T09:02:29.056Z
- 最新版本发布：2026-05-30T06:22:41.034Z
- 近 30 天下载量：3103（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 9 个）

## 中文简介

一个键盘命令引擎,带有热键解析,序列,记录,以及回放钩.

## 安装

```sh
npm install @gentleduck/vim
```

也可以使用：`pnpm add @gentleduck/vim`、`yarn add @gentleduck/vim`、`bun add @gentleduck/vim`

## README

![@gentleduck/vim](https://npmcn.com/package/public/logo-dark.svg)

# @ gentleduck/vim (英语)

键盘命令引擎带有热键解析,序列,录音,和回放钩.

[麻省理工学院](https://npmcn.com/package/LICENSE) - 说吧 [更改日志](https://npmcn.com/package/CHANGELOG.md) - 说吧 [捐款](https://npmcn.com/package/CONTRIBUTING.md) - 说吧 [文档](https://gentleduck.org/duck-ui)

[![npm](https://img.shields.io/npm/v/@gentleduck/vim.svg)](https://www.npmjs.com/package/@gentleduck/vim) [![downloads](https://img.shields.io/npm/dm/@gentleduck/vim.svg)](https://www.npmjs.com/package/@gentleduck/vim) [![MIT](https://img.shields.io/npm/l/@gentleduck/vim.svg)](https://npmcn.com/package/LICENSE)

* * *

React 的键盘命令引擎.

捆绑出热键,记录出密钥序列,并处理有平台意识的修改键. 包含有反应钩子的框架不可知核.

## 为什么

-   多步键序列( E)`g` 接下来 `d`) 带有可配置的超时
-   用户自定义绑定的设置 UI 的密钥记录
-   平台意识 `Mod` 键: 决定 `Cmd` 在macOS上, `Ctrl` 到处都是

## 快开始

```bash
npm install @gentleduck/vim
```

```tsx
import { KeyProvider, useKeyBind } from '@gentleduck/vim/react'

function App() {
  useKeyBind('ctrl+k', () => console.log('open palette'), {
    preventDefault: true,
  })

  return <div>Press Ctrl+K</div>
}

export default function Root() {
  return (
    <KeyProvider>
      <App />
    </KeyProvider>
  )
}
```

## 特征

-   **密钥解析** -- 解析、正常化并验证绑定字符串(`Mod+Shift+S` 到结构化描述符)
-   **顺序** -- 有超时和进展跟踪的多步骤关键链
-   **记录** -- 从用户输入中获取密钥组合以重新绑定 UI
-   **反应钩** - 说吧 `useKeyBind`, (中文(简体) ), `useKeySequence`, (中文(简体) ), `useKeyRecorder`, (中文(简体) ), `useKeyCommands`
-   **平台检测** -- 自动检测macOS/Windows/Linux并解决修改标签
-   **冲突探测** -- 警告、出错或静音替换重复绑定
-   **具有约束力的备选方案** - 说吧 `preventDefault`, (中文(简体) ), `stopPropagation`, (中文(简体) ), `ignoreInputs`, (中文(简体) ), `requireReset`

## 模块

每个模块是一个单独的子路径导出,可以独立使用:

| 模块 | 导入 | 目的 |
| --- | --- | --- |
| `platform` | `@gentleduck/vim/platform` | OS检测, `Mod` 决议 |
| `parser` | `@gentleduck/vim/parser` | 解析/规范/验证约束 |
| `matcher` | `@gentleduck/vim/matcher` | 匹配键盘事件 |
| `format` | `@gentleduck/vim/format` | 平台意识显示格式 |
| `command` | `@gentleduck/vim/command` | 书记官处和钥匙处理员 |
| `sequence` | `@gentleduck/vim/sequence` | 多键序列匹配 |
| `recorder` | `@gentleduck/vim/recorder` | 密钥组合记录 |
| `react` | `@gentleduck/vim/react` | 反应上下文,钩子 |

## 套装

-   0 运行时依赖性( React 是一个对等的 dep)
-   可树动子路径导出
-   `"sideEffects": false`

## 文档

[温特多克.org](https://gentleduck.org/)

## 许可证

[麻省理工学院](https://npmcn.com/package/%40gentleduck/vim/LICENSE)

## 常见问题

### @gentleduck/vim 是什么？

一个键盘命令引擎,带有热键解析,序列,记录,以及回放钩\.

### 如何安装 @gentleduck/vim？

在项目目录运行 npm install @gentleduck/vim，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18 \|\| ^19）、react-dom（^18 \|\| ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gentleduck/vim 支持 TypeScript 吗？

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

### @gentleduck/vim 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gentleduck/vim 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gentleduck/vim 可以商用吗？

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

### @gentleduck/vim 的下载量有多少？

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

### @gentleduck/vim 还在维护吗？

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

