# @chatwoot/ninja-keys 中文文档

规范地址：https://npmcn.com/package/%40chatwoot/ninja-keys/

版本：1\.2\.3
npm 元数据更新时间：2024-02-21T06:11:56.304Z
中文译文更新时间：2026-11-09T11:30:21.336Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40chatwoot/ninja-keys
原文对照：https://npmcn.com/package/%40chatwoot/ninja-keys/?lang=original
项目主页：https://github.com/ssleptsov/ninja-keys
源码仓库：https://github.com/ssleptsov/ninja-keys

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

- 包体积（解压后）：1.6 MB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-02-21T06:11:55.326Z
- 最新版本发布：2024-02-21T06:11:55.686Z
- 近 30 天下载量：140969（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

忍者键

## 安装

```sh
npm install @chatwoot/ninja-keys
```

也可以使用：`pnpm add @chatwoot/ninja-keys`、`yarn add @chatwoot/ninja-keys`、`bun add @chatwoot/ninja-keys`

## README

# 忍者键

与Vanilla JS,Vue,以及React合作的网站的键盘快捷界面.

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fssleptsov%2Fninja-keys.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fssleptsov%2Fninja-keys?ref=badge_shield) ![npm](https://img.shields.io/npm/v/ninja-keys) ![npm](https://img.shields.io/npm/dw/ninja-keys)

## 演示

[https://ninja-keys-demo.vercel.app/ (原始内容存档于2018-09-27)](https://ninja-keys-demo.vercel.app/) ![Demo](https://npmcn.com/package/%40chatwoot/ninja-keys/docs/demo-min.gif)

## 动机

许多应用程序支持用户点击的常见模式 ⌘\+ 键页:1 (或 缩写\+ 键页:1),并出现了搜索UI对话框. 最近我在Notion, Slack, Linear, Vercel和Algolia上看到过这个, 但我肯定还有更多的. Apple Spotlight,Alfred和Raycast应用也有类似的模式,但快捷方式不同. 已有一些图书馆为此而建,但它们过于具体框架,如 [只学习](https://github.com/livewire-ui/spotlight) 或者说 [只反应](https://github.com/timc1/kbar) 然而,我的不是银弹,如果你需要更多的框架整合,也检查一下.

我需要一个键盘接口来导航 与静态网站没有任何框架. 同时,我还有几个Vue项目 其中类似的东西可能是有用的, 所以我决定试试看 [Web 组件](https://open-wc.org/) 财务报告和审定财务报表 [升元素](https://lit.dev/)。 。 。 .

## 一体化

-   [Vue 3 示例 - 代码框](https://codesandbox.io/s/ninja-keys-demo-vue3-bps5w?file=/public/index.html)
-   [Vue 2 示例 - 代码框](https://codesandbox.io/s/ninja-keys-demo-vue2-b129z)
-   [反应示例 - 代码框](https://codesandbox.io/s/ninja-keys-demo-reactjs-rlv4b?file=/src/App.js)
-   [反应/下一个JS](https://github.com/ssleptsov/ninja-keys-demo/blob/master/components/LayoutWrapper.js#L14-L71)
-   [静态 Html - 密码箱](https://codesandbox.io/s/ninja-keys-demo-html-cf9wy?file=/index.html)
-   [Svelte - 密码箱](https://codesandbox.io/s/ninja-keys-demo-svelte-r31l8)
-   [固态JS 包装器](https://github.com/wobsoriano/solid-ninja-keys)

## 特征

-   键盘导航
-   光和暗主题构建于
-   材质字体和自定义 svg 图标的内置图标支持
-   嵌入式菜单 - 可使用树或平面数据结构
-   自动注册快捷键
-   根搜索 - 例如,如果搜索"黑暗",它会在"Theme"子菜单中找到它
-   自定义视图的 CSS 变量
-   自定义可打开/关闭等的热键. 选择最适合您网站的内容 .

## 为什么叫"忍者"?

因为它从哪里出现 并迅速执行任何行动... 或者因为它允许您的用户成为键盘忍者QQ

## 从国家预防机制安装

```bash
npm i ninja-keys
```

如果您使用 Web 包装、 卷起、 vite 或其他构建系统, 则导入 .

```js
import 'ninja-keys';
```

## 从 CDN 安装

主要用于没有构建系统的HTML/JS中.

```html
<script type="module" src="https://unpkg.com/ninja-keys?module"></script>
```

模块脚本

```html
<script type="module">
  import {NinjaKeys} from 'https://unpkg.com/ninja-keys?module';
</script>
```

### 使用量

在您的 HTML 中添加标签 .

```html
<ninja-keys> </ninja-keys>
```

```html
<script>
  const ninja = document.querySelector('ninja-keys');
  ninja.data = [
    {
      id: 'Projects',
      title: 'Open Projects',
      hotkey: 'ctrl+N',
      icon: 'apps',
      section: 'Projects',
      handler: () => {
        // it's auto register above hotkey with this handler
        alert('Your logic to handle');
      },
    },
    {
      id: 'Theme',
      title: 'Change theme...',
      icon: 'desktop_windows',
      children: ['Light Theme', 'Dark Theme', 'System Theme'],
      hotkey: 'ctrl+T',
      handler: () => {
        // open menu if closed. Because you can open directly that menu from it's hotkey
        ninja.open({ parent: 'Theme' });
        // if menu opened that prevent it from closing on select that action, no need if you don't have child actions
        return {keepOpen: true};
      },
    },
    {
      id: 'Light Theme',
      title: 'Change theme to Light',
      icon: 'light_mode',
      parent: 'Theme',
      handler: () => {
        // simple handler
        document.documentElement.classList.remove('dark');
      },
    },
    {
      id: 'Dark Theme',
      title: 'Change theme to Dark',
      icon: 'dark_mode',
      parent: 'Theme',
      handler: () => {
        // simple handler
        document.documentElement.classList.add('dark');
      },
    },
  ];
</script>
```

图书馆内部采用平面数据结构,如上例. 但也可以使用树结构如下:

```js
{
  id: 'Theme',
  children: [
    { id: 'light' title: 'light_mode', },
    { id: 'System Theme',
      children: [
        { title: 'Sub item 1' },
        { title: 'Sub item 2' }
      ]
    }
  ]
}
```

## 属性

| 外地 | 默认 | 说明 |
| --- | --- | --- |
| 占位符 | 输入命令或搜索... | 搜索的占位符 |
| 禁用 Hotkeys 键 | 虚假 | 如果属性存在, 将为所有动作注册所有热键 |
| 隐藏面包屑 | 虚假 | 如果真实, 在信头上隐藏面包屑 |
| 打开 Hotkey | cmd+k, ctrl+k 时间 | 打开或关闭快捷键 |
| 导航 Up Hotkey | 上, 转接+tab | 导航快捷键 |
| 导航下密钥 | 下来,塔布 | 向下导航快捷键 |
| 关闭 Hotkey | 埃斯克语 | 关闭快捷键 |
| goBack Hotkey (英语) | 后边空间 | 如果有父菜单, 返回一个关卡 |
| 选择 Hotkey | 输入 | 选择操作和执行处理器或打开子菜单 |
| 热键 Joined View | 虚假 | 如果存在/ 将显示一个元素内的热键 |
| 无自动记录MdIcons | 虚假 | 如果存在的话, 它会禁用连接上的装入材料图标字体 |
| 示例 |  |  |
| 时间轴 : |  |  |
|  |  |  |
| \`\`\` |  |  |

## 数据

矩阵 `INinjaAction` - 下面的接口属性

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 编号 | 字符串 | 独特的id/text. 将在多菜单中显示为面包屑 |
| 标题 | 字符串 | 行动名称 |
| 热键 | 字符串( 可选) | 显示和注册的快捷键 |
| 处理器 | 函数( 可选) | 要执行的功能 |
| 缩写 | 字符串( 可选) | 材料设计字体图标名称 |
| 图标 | 字符串( 可选) | 作为自定义图标渲染的 Html |
| 父目录 | 字符串( 可选) | 如果使用平面结构使用动作的ID来制作多层菜单 |
| 关键词 | 字符串( 可选) | 用于搜索的关键字 |
| 儿童 | 矩阵( 可选) | 如果使用平面结构,则使用孩子菜单动作的ID. 树型结构不需要 |
| 节 | 字符串( 可选) | 节正文. 就像一个信头会和其他相同的部分一样 |

## 方法

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `open` | {家长? : 字符串} | 用父打开菜单, 如果无效, 则打开根菜单 |
| `close` |  | 关闭菜单 |
| `setParent` | 父关系? : 字符串 | 导航到父菜单 |
| 示例 |  |  |
| \`\`\`(\`\`\`) |  |  |
| cinja = 文档.querySelector('inja-keys'); |  |  |
| 忍术. open () |  |  |
| / 或( 或) |  |  |
| 忍者. open ({ 父: 'Theme' }) |  |  |
| \`\`\` |  |  |

### 活动

构成部分广泛活动

| 名称 | 说明 | 有效载荷 |
| --- | --- | --- |
| `change` | 每次搜索输入变化时发送 | `{ detail: { search: string, actions: Array<NinjaAction> } }` |
| `selected` | 在用户选定行动或提交输入时发送 | `{ detail: { search: string, action: NinjaAction or undefined }}` |
| `closed` | 用户关闭菜单时发送 |  |

两者 `handler` 行动和组成部分活动 `selected` 用户提交表单或选择项目时释放 .

不过事件 `selected` 可用于处理边缘大小写,因此不建议在此写入每个动作逻辑. 使用动作比较好 `handler` 属性.

例如,如果一个用户输入搜索查询,并且有空列表,听这个事件就可以处理.

```js
ninja.addEventListener('change', (event) => {
  console.log('ninja on change', event.detail);
  // detail = {search: 'your search query', actions: Array<NinjaAction>}
})
ninja.addEventListener('selected', (event) => {
  console.log('ninja on selected', event.detail);
  // detail = {search: 'your search query', action: NinjaAction | undefined }
  if (event.detail.action){
  // perform API search for example
  }
   
})
```

## 主题

组件支持一个黑暗主题外框. 你只需要加个课.

```html
<ninja-keys class="dark"></ninja-keys>
```

如果您需要更多样式控制, 请使用下面的 CSS 变量 .

### CSS 变量

| 名称 | 默认 |
| --- | --- |
| \- 忍者宽度 | 640px; (中文(简体) ); |
| \-- 忍者回放过滤器 | 无; |
| \-- " 忍者流 " 背景 | rgba(255、255、255、0.5); |
| \-- 忍者文本- 颜色 | rgb(60、65、73); |
| 忍者字体大小 | 16px; (中文(简体) ); |
| 忍者顶 | 20%; |
| 忍-键-边界-射线 | 0.25毫米口径 |
| \-- 忍- 赤- 颜色 | rgb(110、94、210); |
| \-- 忍- 中等背景- 颜色 | rgb(239、241、244); |
| \-- 忍- 中文本- 颜色 | rgb(107、111、118); |
| \- 忍者选择的背景 | rgb(248、249、251); |
| \-- 忍相- 颜色 | var(--忍-中学-文本-颜色); |
| 忍术大小 | 1.2个; |
| \-- -- 忍者-隔离-边境 | 1px 固体 var (-- 忍- 二等- 后地- 颜色); |
| 忍者模式背景 | #fff; (中文(简体) ); |
| 忍-模式-阴影 | rgb (0 0 / 50%) 0px 16px 70px; 2; |
| \- 忍者行动 - 身高 | 300px; (中文(简体) ); |
| \-- 忍者组- 文本- 颜色 | rgb(144、149、157); |
| 忍脚背地 | rgba(242、242、242、0.4); |
| \-- 忍者占位符- 颜色 | #8e8e8e #e #8e8e ##8e8e ##8e8e #8e8e #8e8e #8e8e #8e8e #8e8e #8e8e #8e8e #8e8e #8e8e #8e8e" #8e8e8e" #8e8e8e" #8e8e8e"("8e") #8e8e8e"("8") #8e8e8e8e"("8") |
| \- 忍者 - z - 指数 | 1个 |

#### 示例

```css
ninja-keys {
  --ninja-width: 400px;
}
```

### CSS 阴影部件

允许您从样式中样式特定元素. 由于风格被Shadow DOM所封装,因此为所有属性创建css变量会很烦人. 这就是为什么你可以使用 `::part` 以自定义查找组件. 它的支持 [所有现代浏览器](https://caniuse.com/mdn-css_selectors_part)

| 名称 | 说明 |
| --- | --- |
| 动作列表 | 包着所有孩子元素的元素. |
| 忍者行动 | 单项行动 |
| 忍者选中 | 选定动作 |
| 忍者输入 | 输入元素 |
| 忍者输入-包装器 | Div 周围的包装元素, 对高级样式有用 |

#### 使用部件的示例样式

```css
ninja-keys::part(actions-list) {
  padding: 8px;
}
ninja-keys::part(ninja-action) {
  border-radius: 8px;
  border-left: none;
}

ninja-keys::part(ninja-selected) {
  background: rgba(51, 51, 51, 0.1);
}


ninja-keys::part(ninja-input) {
  color: #14b8a6;
}

ninja-keys::part(ninja-input)::placeholder {
  color: #f43f5e;
}

ninja-keys::part(ninja-input-wrapper) {
  background: rgba(244, 63, 93, 0.3);
}
```

### 图标

默认情况下,组件使用来自 [https://fonts.google.com/icons (中文(简体) )](https://fonts.google.com/icons)

例如,你可以刚刚设置 `mdIcon` 改为 `light_mode` 用来制作太阳图标.

要为您的网站添加材料图标, 您需要添加到您的 HTML 中, 例如

```html
<link href="https://fonts.googleapis.com/css?family=Material+Icons&display=block" rel="stylesheet">
```

如果您想要自定义图标, 您可以使用 `svg` 或者说 `img` 插入一个 `icon` 用于操作的属性 `ninja-icon` 课. 示例

```js
{
  title: 'Search projects...',
  icon: `<svg xmlns="http://www.w3.org/2000/svg" class="ninja-icon" fill="none" viewBox="0 0 24 24" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z" />
  </svg>`,
  section: 'Projects',
},
```

您也可以使用 CSS 变量更改宽度和字体

```css
ninja-keys {
  --ninja-icon-size: 1em;
}
```

### 更改或隐藏页脚

```html
<ninja-keys> 
  <div slot="footer">You can use a custom footer or empty div to hide it</div>
</ninja-keys>
```

## Dev 服务器

```bash
npm run start
```

## 线性

要插入项目运行 :

```bash
npm run lint
```

## 格式化

[高级](https://prettier.io/) 用于代码格式化。 已经按照李特的作风进行了预构.

## 许可证

版权(c) [谢尔盖·斯莱佐夫](https://sergei.ws/) [嘿@ sergei.ws (英语)](mailto:hey@sergei.ws)

许可证根据 [麻省理工学院执照](https://npmcn.com/package/%40chatwoot/ninja-keys/LICENSE)。 。 。 .

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fssleptsov%2Fninja-keys.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fssleptsov%2Fninja-keys?ref=badge_large)

## 常见问题

### @chatwoot/ninja-keys 是什么？

忍者键

### 如何安装 @chatwoot/ninja-keys？

在项目目录运行 npm install @chatwoot/ninja-keys，或使用 pnpm add / yarn add / bun add。

### @chatwoot/ninja-keys 支持 TypeScript 吗？

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

### @chatwoot/ninja-keys 支持 ESM 还是 CommonJS？

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

### @chatwoot/ninja-keys 可以商用吗？

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

### @chatwoot/ninja-keys 的下载量有多少？

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

### @chatwoot/ninja-keys 还在维护吗？

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