HotKeys

When to use

When it is necessary to express the usage method of shortcut key combinations to users, using the Hotkeys component can quickly render the corresponding UI elements and automatically obtain event bindings.

Demos

How to import

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

Explanation

A hotkey is one regular key plus zero or more modifier keys (Shift, Control, Meta, Alt). A single regular key without modifiers (such as ['k']) is valid too. The listener is a keydown handler on document.body (or the element returned by getListenerTarget), so it also fires while focus is inside an input; check event.target in onHotKey (@hotKey in Vue) to skip typing contexts. Modifiers must match exactly: with ['k'], pressing Ctrl and K does not trigger it.

Keys are matched by physical key position. Symbols that need Shift to type, such as !, @ and ?, are not valid keys and throw when set. Write them as Shift plus the base key instead, for example ['Shift', '1'] or ['Shift', '/'].

Meta corresponds to Command on macOS and Win on Windows.

When setting a shortcut that overlaps with common shortcuts like Ctrl/Meta + C, the preventDefault setting can be used to control whether the default event is triggered.

Basic Usage

Pass in key combinations via hotKeys and bind a shortcut handler function using onHotKey (@hotKey in Vue) to respond to the action.

When pressing Ctrl + Shift + A, it opens the modal. By default, it listens on the body, making it effective globally.

values reference

It's also recommended to use the HotKeys.Keys wrapper to set hotkeys.

control+Shift+a

Code

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

Custom content

Set the characters through content

Ctrl+Shift+B

Code

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

Replace the element through render, which takes a JSX element or a function returning one. null, or a function returning null, renders nothing and the hot keys stay active.

Press Ctrl+R to Open Modal

Code

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

prevent Default event

Control the default event by setting preventDefault.

meta+s

control+s

Code

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

change the DOM element the listener is mounted on

The hotkey is listened to on the body by default, through getListenerTarget

Control+q

Code

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 Reference

Props

Property	Description	Type	Default
content	Key labels to show. Defaults to hotKeys.	`string[]`	-
getListenerTarget	Returns the element that listens for keydown. When omitted, or when it returns null or undefined, document.body is used. Signals read here move the listener when they change.	`Type`	-
hotKeys	The key combination: any number of modifiers plus one other key, as `KeyboardEvent.key` values. An invalid combination throws, including after an update.	`KeyboardEvent['key'][]`	-
onHotKey	Called when the full key combination is pressed, with the native `KeyboardEvent`.	`Type`	-
preventDefault	Whether the default behavior of the key combination is prevented.	`boolean`	`false`
render	Replaces the key hint. Accepts a JSX element or a function returning one. `null`, or a function returning `null`, renders nothing and the hot keys stay active.	`Type`	-

class, style, ref and native attributes (such as id, aria-* and onClick) land on the root element (div). When render is null or returns null there is no root element, so they have nowhere to land.

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.

Sass variable	Value	Usage
$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