快捷键 - Semi Design Next

使用场景

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

代码演示

如何引入

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

自定义内容

通过content传入渲染的字符

Ctrl+Shift+B

代码

<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>

通过默认插槽传入代替渲染的元素。传入空的默认插槽时不渲染任何元素，快捷键仍然有效。

Press Ctrl+R to Open Modal

代码

<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>

阻止默认事件

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

meta+s

control+s

代码

<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>

修改监听挂载DOM

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

Control+q

代码

<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 参考

HotKeys

Props

属性	说明	类型	默认值
hotKeys	快捷键组合：任意个修饰键加一个普通键，取值参考 KeyboardEvent.key。组合不合法时抛错，更新后同样校验。	`string[]`	`undefined`
content	显示的按键文字，缺省显示 hotKeys。	`string[]`	`semiGlobalDefault("HotKeys", "content")`
preventDefault	是否阻止快捷键的默认行为。	`boolean`	`semiDefault("HotKeys", "preventDefault", false)`
getListenerTarget	返回监听 keydown 的元素；缺省或返回 null、undefined 时使用 document.body。	`Type`	`undefined`

Events

事件	说明	回调参数
hotKey	按下完整的快捷键组合时触发，参数为原生 KeyboardEvent。	`[event: KeyboardEvent]`

Slots

插槽	说明	作用域参数
default	替换按键提示的渲染。传入空插槽时不渲染任何元素，快捷键仍然有效。	`any`

Exposes

名称	说明	类型
无

class、style 与原生属性（包括 @click）落在根元素上。默认插槽为空时不渲染根元素，这些属性无处可落。

设计变量

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