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

<script setup lang="ts">
    import { HotKeys } from '@fibrous/semi-ui-vue';
</script>

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

<script setup lang="ts">
    import { ref } from 'vue';
    import { HotKeys, Modal } from '@fibrous/semi-ui-vue';

    const visible = ref(false);
    const close = () => {
        visible.value = false;
    };
    const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.A];
</script>

<template>
    <div>
        <HotKeys :hotKeys="hotKeys" @hotKey="visible = true" />
        <Modal v-model:visible="visible" title="Dialog" @ok="close"> This is the Modal opened by hotkey: {{ hotKeys.join('+') }}. </Modal>
    </div>
</template>

Custom content

Set the characters through content

Ctrl+Shift+B

Code

<script setup lang="ts">
    import { ref } from 'vue';
    import { HotKeys, Modal } from '@fibrous/semi-ui-vue';

    const visible = ref(false);
    const close = () => {
        visible.value = false;
    };
    const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B];
</script>

<template>
    <div>
        <HotKeys :content="['Ctrl', 'Shift', 'B']" :hotKeys="hotKeys" @hotKey="visible = true" />
        <Modal v-model:visible="visible" title="Dialog" @ok="close"> This is the Modal opened by hotkey: {{ hotKeys.join('+') }}. </Modal>
    </div>
</template>

Replace the element through the default slot. An empty default slot renders nothing and the hot keys stay active.

Press Ctrl+R to Open Modal

Code

<script setup lang="ts">
    import { ref } from 'vue';
    import { HotKeys, Modal, Tag } from '@fibrous/semi-ui-vue';

    const visible = ref(false);
    const close = () => {
        visible.value = false;
    };
    const hotKeys = [HotKeys.Keys.Control, HotKeys.Keys.R];
</script>

<template>
    <div>
        <HotKeys :hotKeys="hotKeys" @hotKey="visible = true">
            <Tag>Press Ctrl+R to Open Modal</Tag>
        </HotKeys>
        <Modal v-model:visible="visible" title="Dialog" @ok="close"> This is the Modal opened by hotkey: {{ hotKeys.join('+') }}. </Modal>
    </div>
</template>

prevent Default event

Control the default event by setting preventDefault.

meta+s

control+s

Code

<script setup lang="ts">
    import { ref } from 'vue';
    import { HotKeys, Modal } from '@fibrous/semi-ui-vue';

    const visible = ref(false);
    const close = () => {
        visible.value = false;
    };
    const metaKeys = [HotKeys.Keys.Meta, HotKeys.Keys.S];
    const controlKeys = [HotKeys.Keys.Control, HotKeys.Keys.S];
</script>

<template>
    <div>
        <HotKeys :hotKeys="metaKeys" preventDefault @hotKey="visible = true" />
        <br />
        <HotKeys :hotKeys="controlKeys" preventDefault @hotKey="visible = true" />
        <Modal v-model:visible="visible" title="Dialog" @ok="close"> This is the Modal opened by hotkey: Meta/Control + S. </Modal>
    </div>
</template>

change the DOM element the listener is mounted on

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

Control+q

Code

<script setup lang="ts">
    import { ref, useTemplateRef } from 'vue';
    import { HotKeys, Input, Modal, type InputHandle } from '@fibrous/semi-ui-vue';

    const hotKeys = ['Control', 'q'];
    const visible = ref(false);
    const close = () => {
        visible.value = false;
    };
    const input = useTemplateRef<InputHandle>('input');
    const getListenerTarget = () => input.value?.input;
</script>

<template>
    <div>
        <Input ref="input" placeholder="test for target" />
        <HotKeys :getListenerTarget="getListenerTarget" :hotKeys="hotKeys" @hotKey="visible = true" />
        <Modal v-model:visible="visible" title="Dialog" @ok="close"> This is the Modal opened by hotkey: {{ hotKeys.join('+') }}. </Modal>
    </div>
</template>

API Reference

Props

Property	Description	Type	Default
hotKeys	The key combination: any number of modifiers plus one other key, as KeyboardEvent.key values. An invalid combination throws, including after an update.	`string[]`	`undefined`
content	Key labels to show. Defaults to hotKeys.	`string[]`	`semiGlobalDefault("HotKeys", "content")`
preventDefault	Whether the default behavior of the key combination is prevented.	`boolean`	`semiDefault("HotKeys", "preventDefault", false)`
getListenerTarget	Returns the element that listens for keydown. When omitted, or when it returns null or undefined, document.body is used.	`Type`	`undefined`

Events

Event	Description	Callback parameters
hotKey	Emitted when the full key combination is pressed, with the native KeyboardEvent.	`[event: KeyboardEvent]`

Slots

Slot	Description	Scope parameters
default	Replaces the key hint. An empty slot renders nothing and the hot keys stay active.	`any`

Exposes

Name	Description	Type
None

class, style and native attributes (including @click) land on the root element. With an empty default slot 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