@gentleduck/vim

中文文档
0.3.0发布于 2026/05/30MITTypeScriptES Module零依赖近 30 天下载 3103

A keyboard command engine with hotkey parsing, sequences, recording, and React hooks.

原始使用文档
文档目录7 节
  1. Why
  2. Quick start
  3. Features
  4. Modules
  5. Bundle
  6. Docs
  7. License

@gentleduck/vim

@gentleduck/vim

Keyboard command engine with hotkey parsing, sequences, recording, and React hooks.

MIT - Changelog - Contributing - Docs

npm downloads MIT


Keyboard command engine for React.

Bind hotkeys, record key sequences, and handle platform-aware modifier keys. Framework-agnostic core with React hooks included.

Why

  • Multi-step key sequences (g then d) with configurable timeout
  • Key recording for settings UIs where users customize their bindings
  • Platform-aware Mod key: resolves to Cmd on macOS, Ctrl everywhere else

Quick start

npm install @gentleduck/vim
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>
  )
}

Features

  • Key parsing -- parse, normalize, and validate binding strings (Mod+Shift+S to structured descriptors)
  • Sequences -- multi-step key chains with timeout and progress tracking
  • Recording -- capture key combinations from user input for rebinding UIs
  • React hooks -- useKeyBind, useKeySequence, useKeyRecorder, useKeyCommands
  • Platform detection -- auto-detect macOS/Windows/Linux and resolve modifier labels
  • Conflict detection -- warn, error, or silently replace duplicate bindings
  • Per-binding options -- preventDefault, stopPropagation, ignoreInputs, requireReset

Modules

Each module is a separate subpath export and can be used independently:

ModuleImportPurpose
platform@gentleduck/vim/platformOS detection, Mod resolution
parser@gentleduck/vim/parserParse/normalize/validate bindings
matcher@gentleduck/vim/matcherMatch keyboard events
format@gentleduck/vim/formatPlatform-aware display formatting
command@gentleduck/vim/commandRegistry and key handler
sequence@gentleduck/vim/sequenceMulti-key sequence matching
recorder@gentleduck/vim/recorderKey combination recording
react@gentleduck/vim/reactReact context, hooks

Bundle

  • Zero runtime dependencies (React is a peer dep)
  • Tree-shakeable subpath exports
  • "sideEffects": false

Docs

gentleduck.org

License

MIT

版本与发布记录

@gentleduck/vim 共发布 20 个版本,首次发布于 2025/09/02;过去 12 个月发布了 9 个版本。

版本发布日期距今
0.3.0latest2026/05/305 个月前
0.2.22026/05/205 个月前
0.2.12026/05/066 个月前
0.2.02026/04/196 个月前
0.1.182026/03/277 个月前
0.1.172026/03/158 个月前

关于 @gentleduck/vim 的常见问题

@gentleduck/vim 是什么?

A keyboard command engine with hotkey parsing, sequences, recording, and React hooks.

如何安装 @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 和提交记录判断。