# @fluentui-contrib/react-keytips 中文文档

规范地址：https://npmcn.com/package/%40fluentui-contrib/react-keytips/

版本：0\.4\.4
npm 元数据更新时间：2026-07-29T20:47:17.224Z
中文译文更新时间：2026-11-15T01:12:44.647Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：383 kB，170 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react \>=16\.8\.0 \<20\.0\.0，react-dom \>=16\.8\.0 \<20\.0\.0，@types/react \>=16\.8\.0 \<20\.0\.0，@types/react-dom \>=16\.8\.0 \<20\.0\.0，@fluentui/react-components \>=9\.70\.0 \<10\.0\.0
- 首次发布：2024-10-16T11:04:27.694Z
- 最新版本发布：2026-06-03T12:03:47.419Z
- 近 30 天下载量：8843（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 3 个）

## 中文简介

## 安装

## 安装

```sh
npm install @fluentui-contrib/react-keytips
```

也可以使用：`pnpm add @fluentui-contrib/react-keytips`、`yarn add @fluentui-contrib/react-keytips`、`bun add @fluentui-contrib/react-keytips`

## README

# @ fluentui-contrib/ react- keytips (英语)

## 安装

```bash
npm install @fluentui-contrib/react-keytips
```

或者说

```bash
yarn add @fluentui-contrib/react-keytips
```

一个键提示是一个在UI组件附近显示的小弹出,表示一个可以用来导航并触发该组件的键序列. 不同于键盘快捷键, Keytips 引导用户通过一系列密钥来穿越UI的分级级别.

从技术角度看,"键盘"(Keytip)是一个围绕"工具"(Toltip)组件的包装.

要启用密钥提示,请包括 `Keytips` 组件在应用程序的根层。 使用 `useKeytipRef` 勾勾将键提示附加到特定的目标组件上.

当用户输入一组特定的密钥时会出现密钥提示. 输入序列是 `Alt-Meta` 在窗口和 `Option-Control` 在macOS上. 用户可以通过 `startSequence` 属性.

`returnSequence` 应当用于导航回溯到之前的密钥提示级别(`Esc` (默认情况下). 按键 `Esc` (或不同的热键传递给 `returnSequence`)将关闭密钥提示模式,并仅在它是根级密钥提示(一个没有父关并被先显示)的情况下将其删除.

## 最佳做法

### 执行

-   只要他们的兄弟姐妹没有同样的序列,键盘序列就可以被复制.

### 别

-   别多加一个 `Keytips` 每个应用程序组件.
-   不要将密钥提示附加到可以使你的页面滚动的组件上 。 键提示模式自动退出滚动.

## 使用量

```tsx
import * as React from 'react';
import { Keytips, useKeytipRef } from '@fluentui-contrib/react-keytips';
import { Button } from '@fluentui/react-components';

export const App = () => {
  const onExecute = (_, ({ targetElement })) => {
    targetElement.click();
  };

  const keytipRefA = useKeytipRef({ keySequences: ['a'], content: 'A', onExecute });
  const keytipRefB = useKeytipRef({ keySequences: ['b'], content: 'B', onExecute });
  const keytipRefC = useKeytipRef({ keySequences: ['c'], content: 'C', onExecute });

  return (
    <>
      {/* Keytips must be added once under the root-most FluentProvider of the app */}
      <Keytips />
      <Button ref={keytipRefA}>Button A</Button>
      <Button ref={keytipRefB}>Button B</Button>
      <Button ref={keytipRefC}>Button C</Button>
    </>
  );
};
```

## 手动发送密钥事件

在某些情况下,您可能想要手动触发按键提示事件 。 例如,您可能需要根据动作在程序上输入或退出密钥提示模式. 这个 [使用 Keytips 管理器](https://github.com/microsoft/fluentui-contrib/blob/main/packages/react-keytips/src/hooks/useKeytipsManager.ts) 钩子提供发送权限 方法,允许您手动发送密钥提示事件.

```tsx
import * as React from 'react';
import { Button } from '@fluentui/react-components';
import { useKeytipsManager } from '@fluentui-contrib/react-keytips';

export const App = () => {
  const { enterKeytipMode } = useKeytipsManager();

  return (
    <>
      <Button onClick={enterKeytipMode}>Show Keytips</Button>
    </>
  );
};
```

```tsx

Follow up on the [Storybook](https://microsoft.github.io/fluentui-contrib/react-keytips) for examples on how to use the components provided by this package.
```

## 常见问题

### @fluentui-contrib/react-keytips 是什么？

安装

### 如何安装 @fluentui-contrib/react-keytips？

在项目目录运行 npm install @fluentui-contrib/react-keytips，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0 \<20\.0\.0）、react-dom（\>=16\.8\.0 \<20\.0\.0）、@types/react（\>=16\.8\.0 \<20\.0\.0）、@types/react-dom（\>=16\.8\.0 \<20\.0\.0）、@fluentui/react-components（\>=9\.70\.0 \<10\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fluentui-contrib/react-keytips 支持 TypeScript 吗？

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

### @fluentui-contrib/react-keytips 支持 ESM 还是 CommonJS？

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

### @fluentui-contrib/react-keytips 可以商用吗？

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

### @fluentui-contrib/react-keytips 的下载量有多少？

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

### @fluentui-contrib/react-keytips 还在维护吗？

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