# @dhruvilshah191999/use-shortcut 中文文档

规范地址：https://npmcn.com/package/%40dhruvilshah191999/use-shortcut/

版本：0\.2\.3
npm 元数据更新时间：2026-06-03T17:24:25.558Z
中文译文更新时间：2026-11-12T06:20:09.542Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dhruvilshah191999/use-shortcut
原文对照：https://npmcn.com/package/%40dhruvilshah191999/use-shortcut/?lang=original
项目主页：https://use-shortcut-playground.vercel.app/
源码仓库：https://github.com/dhruvilshah191999/use-shortcut

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

- 包体积（解压后）：74 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2026-05-31T16:08:32.848Z
- 最新版本发布：2026-06-03T17:24:25.431Z
- 近 30 天下载量：9650（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

微小的零依赖性 键盘快捷键重置钩. 跨平台,TypeScript先行.

## 安装

```sh
npm install @dhruvilshah191999/use-shortcut
```

也可以使用：`pnpm add @dhruvilshah191999/use-shortcut`、`yarn add @dhruvilshah191999/use-shortcut`、`bun add @dhruvilshah191999/use-shortcut`

## README

# @dhruvilshah191999/使用简写

> 微小的零依赖性 键盘快捷键重置钩. 跨站台, TypeScript- first, ~1KB gzipped.

[![npm version](https://img.shields.io/npm/v/@dhruvilshah191999/use-shortcut.svg)](https://www.npmjs.com/package/@dhruvilshah191999/use-shortcut) [![bundle size](https://img.shields.io/bundlephobia/minzip/@dhruvilshah191999/use-shortcut)](https://bundlephobia.com/package/@dhruvilshah191999/use-shortcut) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40dhruvilshah191999/use-shortcut/LICENSE)

**▶ [现场演示](https://use-shortcut-playground.vercel.app/)** ——在浏览器中尝试每个功能([来源](https://github.com/dhruvilshah191999/use-shortcut-playground)) (中文(简体) ).

## 安装

```bash
npm install @dhruvilshah191999/use-shortcut
pnpm add @dhruvilshah191999/use-shortcut
yarn add @dhruvilshah191999/use-shortcut
bun add @dhruvilshah191999/use-shortcut
```

## 使用量

```tsx
import { useShortcut } from "@dhruvilshah191999/use-shortcut";

useShortcut("mod+k", () => setOpen(true));
```

## 为什么是这个钩子?

-   **零依赖关系**
-   **小声** (~ 1KB 叮当)
-   **跨平台出框**数字 : `mod` 成为 Mac 上的 Cmd, Ctrl 的别处
-   **智能输入字段处理**:快捷键在打字时不会起火(但 `Escape`(中文(简体) )
-   **构造的脚本类型**
-   **总是重新调用**: 无 stale 关闭, 无 `useCallback` 需求

## API 密码

### `useShortcut(key, callback, options?)`

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `key` | `string | string[]` | 一个组合像 `"mod+k"`,或将组合组合图映射到一个动作. |
| `callback` | `(e: KeyboardEvent) => void` | 以匹配事件调用 。 总是最新的参考文献. |
| `options` | `Options` | 可选的 见下文. |

Combo语法是大小写不敏感和白色空间容忍: `"Cmd+K"`, (中文(简体) ), `"cmd+k"`,以及 `" cmd + k "` 等同起来。 支持的修改名: `mod`, (中文(简体) ), `cmd`编号 :`command`, (中文(简体) ), `ctrl`编号 :`control`, (中文(简体) ), `alt`编号 :`option`, (中文(简体) ), `shift`, (中文(简体) ), `meta`。 。 。 .

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | 快捷键是否活动 . |
| `preventDefault` | `boolean` | `false` | 打电话 `event.preventDefault()` 在比赛中. |
| `stopPropagation` | `boolean` | `false` | 打电话 `event.stopPropagation()` 在比赛中. |
| `enableInInputs` | `boolean` | `false` | 在输入/ 文本区域/ 选择/ 内容可选时, 点火 . |
| `target` | `RefObject<HTMLElement> | Window` | `window` | 随附听者所出之处. 对一个元素的快捷键使用反射. |
| `scope` | `string | string[]` | —— 说 | 将快捷键限制为命名范围; 仅在一个活动时开火 。 见 [范围](https://npmcn.com/package/%40dhruvilshah191999/use-shortcut/#readme-scopes-optional)。 。 。 . |

## 实例

### 基础

```tsx
// Cmd+K (Mac) / Ctrl+K (Windows/Linux) to open search
useShortcut("mod+k", () => openSearch());
```

### 跨平台

```tsx
// `mod` resolves to Cmd on Mac and Ctrl everywhere else
useShortcut("mod+s", () => save());
```

### 同一动作的多个快捷键

```tsx
useShortcut(["mod+k", "/"], () => openSearch());
```

### 在逃逸时关闭模式

```tsx
useShortcut("escape", () => setOpen(false), { enabled: isOpen });
```

### 防止默认浏览器行为

```tsx
// Stop the browser's native "Save page" dialog
useShortcut("mod+s", () => save(), { preventDefault: true });
```

## 范围(可选)

默认每个快捷键都是 **全球** 只要组合吻合,就会开火 如果你需要的话 用于在应用程序的不同部分( 列表导航 vs. an) 中做不同事情的同一键 打开模式,例如,选择加入 **范围**: 标记快捷键 `scope`,将相关的 子树在 `<ShortcutProvider>`,并用 `useShortcutScopes()`。 。 。 .

快捷键 **无** (单位:千美元) `scope` 范围纯粹是添加剂.

```tsx
import {
  ShortcutProvider,
  useShortcut,
  useShortcutScopes,
} from "@dhruvilshah191999/use-shortcut";

function App() {
  // `list` is active on first render; `modal` is off until we open the modal
  return (
    <ShortcutProvider initialScopes={["list"]}>
      <List />
      <Modal />
    </ShortcutProvider>
  );
}

function List() {
  // fires only while the "list" scope is active
  useShortcut("j", selectNext, { scope: "list" });
  return /* ... */;
}

function Modal() {
  const { activate, deactivate } = useShortcutScopes();

  function open() {
    activate("modal");   // modal shortcuts start firing
    deactivate("list");  // list shortcuts pause
  }

  // fires only while the "modal" scope is active
  useShortcut("escape", close, { scope: "modal" });
  return /* ... */;
}
```

`useShortcutScopes()` 返回时 `{ activeScopes, activate, deactivate, toggle, set }`A级 快捷键可以属于多个范围( q)`{ scope: ["a", "b"] }`和火,如果 **任意** 联 合 国 他们正在活动.

> 如果你使用一个 `scope` 无 `<ShortcutProvider>`,快捷键可降解为全局 行为和警告 一次在发展中.

## 洞穴

-   没有序列支持(例如, `g g`) (中文(简体) ).
-   范围通过 `<ShortcutProvider>`;没有一条,每个快捷键都是全球性的(你可以) 并且将单个快捷键缩小到带有 `target` 选项).
-   没有优先/解决冲突——同一组合的全部火力都有多个处理器。 使用 瞄准门 处理者是活的.

## 当不使用时

如果需要键序列(例如, `g g`,帮助模式生成器,或密钥记录器UI,使用 [反应- hotkeys- hook](https://github.com/JohannesKlauss/react-hotkeys-hook) 或者说 [TanStack 热键](https://tanstack.com/hotkeys)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @dhruvilshah191999/use-shortcut 是什么？

微小的零依赖性 键盘快捷键重置钩\. 跨平台,TypeScript先行\.

### 如何安装 @dhruvilshah191999/use-shortcut？

在项目目录运行 npm install @dhruvilshah191999/use-shortcut，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dhruvilshah191999/use-shortcut 支持 TypeScript 吗？

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

### @dhruvilshah191999/use-shortcut 支持 ESM 还是 CommonJS？

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

### @dhruvilshah191999/use-shortcut 需要什么版本的 Node\.js？

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

### @dhruvilshah191999/use-shortcut 可以商用吗？

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

### @dhruvilshah191999/use-shortcut 的下载量有多少？

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

### @dhruvilshah191999/use-shortcut 还在维护吗？

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