# @chatwoot/jumpbar 中文文档

规范地址：https://npmcn.com/package/%40chatwoot/jumpbar/

版本：0\.1\.2
npm 元数据更新时间：2026-11-04T02:50:46.610Z
中文译文更新时间：2026-11-09T12:13:53.203Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：93.5 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vue ^3\.4\.0
- 首次发布：2026-11-02T14:40:51.530Z
- 最新版本发布：2026-11-04T02:50:46.384Z
- 近 30 天下载量：2887（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

Vue 3的轻量级指令调色板:一个框架无排位核心,有模糊的匹配,段落,页面,前缀和frecency,外加有Aync源的原生外壳.

## 安装

```sh
npm install @chatwoot/jumpbar
```

也可以使用：`pnpm add @chatwoot/jumpbar`、`yarn add @chatwoot/jumpbar`、`bun add @chatwoot/jumpbar`

## README

# 跳转栏

按QQK键,键入几个字母,选择动作. 跳转到栏是命令调色板 在Chatwoot仪表板后面, 包装好任何 Vue 3 应用程序都可以使用它, 任何 JavaScript app可以使用其排名核心.

它很小: 排名核心是没有依赖关系的平版JavaScript( 关于 1 KB gziped; 外壳为原生 `<dialog>` 用尾风制成 公用事业(约5个KB与核心相接).

-   模糊地匹配重音折叠、区域、嵌入页和前缀
-   火力,所以你用的东西 上升到顶端
-   同步 `commands` 源在每次按键中排名, 自动 `search` 来源 按源代码解析,最小查询长度和 `AbortSignal`
-   键盘和指针处理、打开/关闭运动、骨架行,同时 远程结果负载、 RTL 和 IME 意识

如何组合:你的应用描述它能通过什么 _来源_, (中文(简体) ), 有标题和标题的平面对象 `run` 函数。 跳转到栏中进行对等 用户输入什么,而 shell 绘制列表。 包裹什么都不知道 关于你的产品.

这个 [指南](https://npmcn.com/package/%40chatwoot/jumpbar/docs/guide.md) 通过配置、 Vue 使用、 plain JavaScript的使用和完整的参考. 此 README 是短版本 .

## 安装

```sh
pnpm add @chatwoot/jumpbar
```

包船编译了ES模块,并附有TypeScript声明; Vue 保持对外. `vue` 外壳需要3.4或更新.

### 任何框架

排名核心没有框架依赖性. 反应、 Svelte、 固态或平态 JavaScript 项目导入它 `@chatwoot/jumpbar/core` 执行《公约》和 自己的列表 :

```js
import { rank, groupBySection, createFrecency } from '@chatwoot/jumpbar/core';

const ranked = rank(items, { text: query, scopes: ['conversation'] });
const sections = groupBySection(ranked);
```

这个 `CommandBar` 外壳和 `useCommandBar` 状态是Vue 3.

## 样式

壳由Tailwind公用设施建造,并读取从a 小套语义符号,因此适应了任何设计系统.

1.  添加预设并扫描软件包从而生成其类 :
    
    ```js
    // tailwind.config.js
    module.exports = {
      presets: [require('@chatwoot/jumpbar/tailwind')],
      content: ['./node_modules/@chatwoot/jumpbar/dist/*.js'],
    };
    ```
    
    预设记录 `jumpbar-*` 作为 CSS 变量的颜色和 打开和关闭键框.
    
2.  主题 导入中性默认并覆盖您喜欢的内容 (a) 暗值 `dark` 分类:
    
    ```js
    import '@chatwoot/jumpbar/theme.css';
    ```
    
    ```css
    :root {
      --jumpbar-primary: #2781f6;
    }
    ```
    
    或者跳过导入并映射到您现有的 Tailwind 颜色上, 将您的暗模式带入:
    
    ```js
    theme: {
      extend: {
        colors: {
          jumpbar: {
            background: colors.surface,
            foreground: colors.text,
            primary: colors.brand,
          },
        },
      },
    },
    ```
    
    | 脚本 | 用于 |
    | --- | --- |
    | `background` | 小组讨论会 |
    | `foreground` | 标题和输入文本 |
    | `muted-foreground` | 字幕、分科标签、面包屑、徽章 |
    | `subtle-foreground` | 占位符、图标、提示、切夫龙 |
    | `muted` | 活行、芯片、相机倒置、骨架行 |
    | `subtle` | 钥匙盖,更轻的骨架栏 |
    | `border` | 分割符和密钥上限大纲 |
    | `ring` | 小组大纲 |
    | `primary` | 活动行标记, 页面芯片文本 |
    | `primary-soft` | 页面芯片背景 |
    | `overlay` | 后投弃 |
    | `online` `busy` `offline` | 存在点 |
    
3.  提供图标类 `i-lucide-search`, (中文(简体) ), `i-lucide-loader-circle` 财务报告和审定财务报表 `i-lucide-chevron-right` (例如通过) `@egoist/tailwindcss-icons` 与卢西德集. 物品带来了自己的图标类.
    

## 快开始

4个步骤,均见下例:

1.  添加 Tailwind 预设和主题符号(见上文Styling).
2.  渲染器 `<CommandBar />` 一次,靠近你的应用程序的根, 并得到共享 状态为 `useCommandBar()`。 。 。 .
3.  登记来源: `commands` 对于你已经知道的事情, `search` 用于用户键入时获取的东西.
4.  绑住快捷键并打电话 `bar.toggle()`。 。 。 .

```vue
<script setup>
import { CommandBar, createFrecency, useCommandBar } from '@chatwoot/jumpbar';

const bar = useCommandBar();

bar.configure({
  prefixes: ['@', '#'],
  context: () => ({ scopes: ['conversation'] }),
  frecency: createFrecency({ storage: localStorage, key: 'palette-usage' }),
  onSelect: item => track(item),
  onClose: () => {},
  onError: (error, source) => report(error),
  limit: 100,
});

bar.register({
  id: 'navigation',
  commands: () => [
    {
      id: 'inbox',
      title: 'Go to inbox',
      section: 'Navigation',
      icon: 'i-lucide-inbox',
      shortcut: ['⌥', 'I'],
      run: () => router.push('/inbox'),
    },
  ],
});

bar.register({
  id: 'contacts',
  minQuery: 3,
  debounce: 300,
  when: ({ page }) => !page,
  search: async ({ text, signal }) => {
    const contacts = await api.search(text, { signal });
    return contacts.map(contact => ({
      id: `contact-${contact.id}`,
      title: contact.name,
      subtitle: contact.email,
      section: 'Contacts',
      avatar: { name: contact.name, src: contact.thumbnail },
      run: () => router.push(`/contacts/${contact.id}`),
    }));
  },
});
</script>

<template>
  <CommandBar
    placeholder="Search or jump to"
    empty-text="No matches"
    :hints="[
      { keys: ['↑', '↓'], label: 'navigate' },
      { keys: ['↵'], label: 'select' },
      { keys: ['esc'], label: 'close' },
    ]"
  />
</template>
```

自己绑住全局快捷键并打电话 `bar.toggle()`。 。 。 . `bar.open({ page, query })` 直接打开到一页中,例如取斯努兹语.

`CommandBar` 道具 : `placeholder`, (中文(简体) ), `emptyText`, (中文(简体) ), `scopeLabel` (一个芯片之前 输入,例如选定的记录), `hints` 财务报告和审定财务报表 `dir` (单位:千美元)`ltr` 或者说 `rtl`) (中文(简体) ).

## 项目

源返回普通对象 :

| 外地 | 含义 |
| --- | --- |
| `id` | 所有来源都独一无二 火力和减震键在上面. |
| `title` | 行标签. 儿童通过 `parentTitle title` 我也一样. |
| `subtitle` | 标题后已静音文本 。 仅取出面包屑和标题后剩下的空间. |
| `section` | 组头. 没有输入, 组保持源顺序; 有文本, 最好的匹配线索 . |
| `icon` | CSS类作为主格莱弗完成. |
| `avatar` | `{ name, src, status }` 而不是图标,缩写为倒置; `status` 实值 `online`, (中文(简体) ), `busy` 或者说 `offline`。 。 。 . |
| `badge` | 短后行文字. |
| `shortcut` | 跟踪密钥标签, 例如 `['⌥', 'E']`作为嵌入式清单的替代品: `[['⌥', 'J'], ['⌥', 'K']]`。 。 。 . |
| `keywords` | 匹配者看到的额外单词( 单词启动匹配) . |
| `scopes` | 单打第一 `context.scopes`。 。 。 . |
| `prefix` | 输入此字符首先只列出携带该字符的项目 . |
| `weight` | 0到1之间的静态助推. |
| `place` | `first` 或者说 `last`:按宣布的顺序,按其他比赛的顺序排序. |
| `searchFromRoot` | `false` 将一个孩子保存在根搜索外(只有前缀和页面). |
| `page` | 选择打开一个列出其 `parent` 是其编号. |
| `placeholder` | 在该页面打开时输入占位符 . |
| `parent` | 页面编号 此项目生活在下. |
| `run` | 以上下文调用, 当栏开始关闭时; 对话框会在150毫秒后离开顶层 。 没有它的行是惰性的. |

## 来源

```js
bar.register({
  id: 'conversations',
  minQuery: 2,
  debounce: 300,
  when: ({ page }) => !page,
  commands: request => [],
  search: async request => [],
});
```

`commands` 运行在每个键盘上并排序. `search` 运行于 与一个 `AbortSignal`;其结果保持了自己的顺序,附加于 ,并替换页面上的静态子. 请求包含 `query`, (中文(简体) ), `text`, (中文(简体) ), `prefix`, (中文(简体) ), `page`, (中文(简体) ), `context` 还有, 对于 `search`, (中文(简体) ), `matches` (有多少命令与当地匹配)和 `signal`。 。 。 . `register` 返回再次删除源的函数。 一个搜索器 抛出其行并 `onError(error, source)` 调用; 默认 复掷出. 最多显示文本查询 `limit` 排序命令(默认为50).

## 排名

标题按精确的、前缀的、开始的、每个字开头的、然后 分散的字符。 字幕和关键词只匹配于文字开始,所以 长描述从不淹没列表。 项目在 `context.scopes` 得到一个助推器, 最近用过的另一件, `weight` 一个小静态的. `place: 'first'` 财务报告和审定财务报表 `place: 'last'` 完全坐在积分之外.

## 键盘

`↑` `↓` 移动, `⌘`编号 :`Ctrl` + 键 `↑` `↓` 跳到第一行或最后一行, `Enter` 选择, `Esc` 关闭, `Backspace` 在空查询中 倒数一页。 Hover只在指针真正移动时更改选择, 因此箭头键在休息光标下继续工作.

## 发展

```sh
pnpm install
pnpm test
pnpm build
```

来源居住在 `src/` 旁边有相片; `dist/` 以出版和 没有承诺。 要释放,出事 `version` 内 `package.json` 运行 `pnpm publish`编辑 `prepublishOnly` 脚本先建立和运行测试, 因此,一个破烂的建筑永远不会到达注册.

## 常见问题

### @chatwoot/jumpbar 是什么？

Vue 3的轻量级指令调色板:一个框架无排位核心,有模糊的匹配,段落,页面,前缀和frecency,外加有Aync源的原生外壳\.

### 如何安装 @chatwoot/jumpbar？

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

### @chatwoot/jumpbar 支持 TypeScript 吗？

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

### @chatwoot/jumpbar 支持 ESM 还是 CommonJS？

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

### @chatwoot/jumpbar 可以商用吗？

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

### @chatwoot/jumpbar 的下载量有多少？

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

### @chatwoot/jumpbar 还在维护吗？

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