快捷键 HotKeys - Svelte - Semi Design Next

使用场景

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

代码演示

如何引入

<script lang="ts">
    import { HotKeys } from '@fibrae/semi-ui-svelte';
</script>

说明

快捷键由一个普通键加上 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

代码

<script lang="ts">
    import { HotKeys, Modal } from '@fibrae/semi-ui-svelte';

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

<div>
    <HotKeys {hotKeys} onHotKey={() => (visible = true)} />
    <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: {hotKeys.join('+')}.</Modal>
</div>

自定义内容

通过content传入渲染的字符

Ctrl+Shift+B

代码

<script lang="ts">
    import { HotKeys, Modal } from '@fibrae/semi-ui-svelte';

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

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

通过 children snippet（写在 HotKeys 标签内）传入代替渲染的元素，传了就不再渲染默认的按键提示，快捷键仍然有效。

Press Ctrl+R to Open Modal

代码

<script lang="ts">
    import { HotKeys, Modal, Tag } from '@fibrae/semi-ui-svelte';

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

<div>
    <HotKeys {hotKeys} onHotKey={() => (visible = true)}>
        <Tag>Press Ctrl+R to Open Modal</Tag>
    </HotKeys>
    <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: {hotKeys.join('+')}.</Modal>
</div>

阻止默认事件

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

meta+s

control+s

代码

<script lang="ts">
    import { HotKeys, Modal } from '@fibrae/semi-ui-svelte';

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

<div>
    <HotKeys hotKeys={metaKeys} onHotKey={() => (visible = true)} preventDefault />
    <br />
    <HotKeys hotKeys={controlKeys} onHotKey={() => (visible = true)} preventDefault />
    <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: Meta/Control + S.</Modal>
</div>

修改监听挂载DOM

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

Control+q

代码

<script lang="ts">
    import { HotKeys, Input, Modal } from '@fibrae/semi-ui-svelte';

    const hotKeys = ['Control', 'q'];
    let visible = $state(false);
    const close = () => {
        visible = false;
    };
    let input = $state<ReturnType<typeof Input>>();
    const getListenerTarget = () => input?.getInput();
</script>

<div>
    <Input bind:this={input} placeholder="test for target" />
    <HotKeys {getListenerTarget} {hotKeys} onHotKey={() => (visible = true)} />
    <Modal bind:visible onOk={close} title="Dialog">This is the Modal opened by hotkey: {hotKeys.join('+')}.</Modal>
</div>

API 参考

HotKeys

Props

属性	说明	类型	默认值
children	替换按键提示的内容，写在标签内。传了 children 就不渲染默认的按键提示，快捷键仍然有效。	`Snippet`	-
content	显示的按键文字，缺省显示 hotKeys。	`string[]`	-
getListenerTarget	返回监听 keydown 的元素；缺省或返回 null、undefined 时使用 document.body。	`Type`	-
hotKeys	快捷键组合：任意个修饰键加一个普通键，取值参考 KeyboardEvent.key。组合不合法时在挂载或 hotKeys 变化时抛错。	`KeyboardEvent['key'][]`	-
onHotKey	按下完整的快捷键组合时的回调，参数为原生 KeyboardEvent。	`Type`	-
preventDefault	是否阻止快捷键的默认行为。	`boolean`	`false`

class、style（字符串）与原生属性（如 id、aria-*、onclick）落在根元素（div）上。HotKeys.Keys 保留，用法同其他框架。

设计变量

下表是组件内部的 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