快捷键 - Semi Design Next

使用场景

需要向用户表达快捷键组合的使用方式时，使用 Hotkeys 组件可快速渲染出对应的 UI 元素且自动获得事件绑定

代码演示

如何引入

import { HotKeys } from '@fibrous/semi-ui-solid';

说明

快捷键由一个普通键加上 0 个或多个修饰键（Shift、Control、Meta、Alt）组成，不带修饰键的单个普通键（如 ['k']）同样有效。监听挂在 document.body（或 getListenerTarget 返回的元素）的 keydown 上，焦点在输入框内时同样会触发；需要避开输入场景时，请在 onHotKey（Vue 为 @hotKey）中自行判断 event.target。修饰键必须与设定完全一致：设定为 ['k'] 时，按住 Ctrl 再按 K 不会触发。

按键按物理按键位置匹配，!、@、? 等需要按住 Shift 才能输入的符号不是有效按键，设置时会抛错。请写成 Shift 加基础键，例如 ['Shift', '1']、['Shift', '/']。

Meta 在MacOS中为Command，在Windows中为Win

当设定快捷键与常用快捷键如Ctrl/Meta + C相同时，可以通过设置preventDefault控制默认事件是否触发。

基本用法

基本使用，通过hotKeys传入快捷键组合，通过 onHotKey（Vue 为 @hotKey）绑定快捷键处理函数，作出响应动作。

按下 Ctrl + Shift + A，唤起modal。默认在 body.document 监听，全局生效。

hotKeys取值参考，也可以使用HotKeys.Keys进行设置

control+Shift+a

代码

import { createSignal } from 'solid-js';
import { HotKeys, Modal } from '@fibrous/semi-ui-solid';

const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.A];

export default function HotKeysDemo() {
    const [visible, setVisible] = createSignal(false);
    const showDialog = () => {
        setVisible(true);
    };
    const handleOk = () => {
        setVisible(false);
    };
    const handleCancel = () => {
        setVisible(false);
    };

    return (
        <div>
            <HotKeys hotKeys={hotKeys} onHotKey={showDialog} />
            <Modal title="Dialog" visible={visible()} onOk={handleOk} onCancel={handleCancel}>
                This is the Modal opened by hotkey: {hotKeys.join('+')}.
            </Modal>
        </div>
    );
}

自定义内容

通过content传入渲染的字符

Ctrl+Shift+B

代码

import { createSignal } from 'solid-js';
import { HotKeys, Modal } from '@fibrous/semi-ui-solid';

const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B];

export default function HotKeysDemo() {
    const [visible, setVisible] = createSignal(false);
    const showDialog = () => {
        setVisible(true);
    };
    const handleOk = () => {
        setVisible(false);
    };
    const handleCancel = () => {
        setVisible(false);
    };

    return (
        <div>
            <HotKeys hotKeys={hotKeys} onHotKey={showDialog} content={['Ctrl', 'Shift', 'B']} />
            <Modal title="Dialog" visible={visible()} onOk={handleOk} onCancel={handleCancel}>
                This is the Modal opened by hotkey: {hotKeys.join('+')}.
            </Modal>
        </div>
    );
}

通过render传入代替渲染的元素，可以是 JSX 元素，也可以是返回 JSX 元素的函数。传入null或返回null时不渲染任何元素，快捷键仍然有效。

Press Ctrl+R to Open Modal

代码

import { createSignal } from 'solid-js';
import { HotKeys, Modal, Tag } from '@fibrous/semi-ui-solid';

const hotKeys = [HotKeys.Keys.Control, HotKeys.Keys.R];

export default function HotKeysDemo() {
    const [visible, setVisible] = createSignal(false);
    const showDialog = () => {
        setVisible(true);
    };
    const handleOk = () => {
        setVisible(false);
    };
    const handleCancel = () => {
        setVisible(false);
    };

    return (
        <div>
            <HotKeys hotKeys={hotKeys} onHotKey={showDialog} render={() => <Tag>Press Ctrl+R to Open Modal</Tag>} />
            <Modal title="Dialog" visible={visible()} onOk={handleOk} onCancel={handleCancel}>
                This is the Modal opened by hotkey: {hotKeys.join('+')}.
            </Modal>
        </div>
    );
}

阻止默认事件

通过设置preventDefault控制默认事件是否触发。

meta+s

control+s

代码

import { createSignal } from 'solid-js';
import { HotKeys, Modal } from '@fibrous/semi-ui-solid';

const metaKeys = [HotKeys.Keys.Meta, HotKeys.Keys.S];
const controlKeys = [HotKeys.Keys.Control, HotKeys.Keys.S];

export default function HotKeysDemo() {
    const [visible, setVisible] = createSignal(false);
    const showDialog = () => {
        setVisible(true);
    };
    const handleOk = () => {
        setVisible(false);
    };
    const handleCancel = () => {
        setVisible(false);
    };

    return (
        <div>
            <HotKeys hotKeys={metaKeys} onHotKey={showDialog} preventDefault />
            <br />
            <HotKeys hotKeys={controlKeys} onHotKey={showDialog} preventDefault />
            <Modal title="Dialog" visible={visible()} onOk={handleOk} onCancel={handleCancel}>
                This is the Modal opened by hotkey: Meta/Control + S.
            </Modal>
        </div>
    );
}

修改监听挂载DOM

快捷键默认在 body 监听，通过getListenerTarget修改快捷键监听挂载的DOM

Control+q

代码

import { createSignal } from 'solid-js';
import { HotKeys, Input, Modal } from '@fibrous/semi-ui-solid';

const hotKeys = ['Control', 'q'];

export default function HotKeysDemo() {
    const [visible, setVisible] = createSignal(false);
    const [input, setInput] = createSignal<HTMLInputElement>();
    const showDialog = () => {
        setVisible(true);
    };
    const handleOk = () => {
        setVisible(false);
    };
    const handleCancel = () => {
        setVisible(false);
    };

    return (
        <div>
            <Input inputRef={(node) => setInput(node)} placeholder="test for target" />
            <HotKeys hotKeys={hotKeys} onHotKey={showDialog} getListenerTarget={() => input()} />
            <Modal title="Dialog" visible={visible()} onOk={handleOk} onCancel={handleCancel}>
                This is the Modal opened by hotkey: {hotKeys.join('+')}.
            </Modal>
        </div>
    );
}

API 参考

HotKeys

Props

属性	说明	类型	默认值
content	显示的按键文字，缺省显示 hotKeys。	`string[]`	-
getListenerTarget	返回监听 keydown 的元素；缺省或返回 null、undefined 时使用 document.body。读取的信号变化时，监听目标随之切换。	`Type`	-
hotKeys	快捷键组合：任意个修饰键加一个普通键，取值参考 `KeyboardEvent.key`。组合不合法时抛错，更新后同样校验。	`KeyboardEvent['key'][]`	-
onHotKey	按下完整的快捷键组合时触发，参数为原生 `KeyboardEvent`。	`Type`	-
preventDefault	是否阻止快捷键的默认行为。	`boolean`	`false`
render	替换按键提示的渲染，可以是 JSX 元素或返回 JSX 元素的函数。传入 `null` 或返回 `null` 时不渲染任何元素，快捷键仍然有效。	`Type`	-

class、style、ref 与原生属性（如 id、aria-*、onClick）落在根元素（div）上。render 为 null 或返回 null 时不渲染根元素，这些属性无处可落。

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$color-hotKeys-bg	var(--semi-color-fill-0)	快捷键背景颜色
$color-hotKeys-text	var(--semi-color-text-2)	快捷键文字颜色
$color-hotKeys-split	var(--semi-color-text-0)	快捷键文字颜色
$width-hotKeys-border	1px	快捷键描边宽度
$radius-hotKeys	2px	边框半径
$height-hotKeys	20px	快捷键高度
$spacing-hotKeys-paddingY	2px
$spacing-hotKeys-paddingX	$spacing-tight