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

安装

npm install @fluentui-contrib/react-keytips

或者说

yarn add @fluentui-contrib/react-keytips

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

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

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

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

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

最佳做法

执行

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

别

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

使用量

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 管理器 钩子提供发送权限 方法,允许您手动发送密钥提示事件.

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>
    </>
  );
};

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.