HotKeys

使用场景

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

代码演示

如何引入

import { HotKeys } from '@chenzy-design/svelte';

说明

快捷键仅支持修饰键组合 Shift、Control、Meta、Alt 与其他键的组合。

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

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

基本用法

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

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

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

自定义内容

通过 content 传入渲染的字符

通过 render 传入代替渲染的元素

阻止默认事件

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

修改监听挂载 DOM

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

API 参考

HotKeys

属性	说明	类型	默认值
class	类名	string	-
content	设置显示内容	(string | Snippet)[]	-
getListenerTarget	用于设置监听器挂载的 DOM	() => HTMLElement | null	document.body
hotKeys	设置快捷键组合，取值参考	KeyboardEvent.key[]	-
mergeMetaCtrl	跨平台把 Cmd(Meta) 与 Ctrl 视为同一修饰键	boolean	false
onClick	点击回调函数	() => void	-
onHotKey	快捷键回调函数	(e: KeyboardEvent) => void	-
preventDefault	是否阻止快捷键默认行为	boolean	false
render	覆盖组件渲染；传 null 则不渲染提示，仅保留监听	Snippet | null	-
style	样式	string	-

静态属性

名称	说明	类型
HotKeys.Keys	键名常量枚举（Keys.Control / Keys.Meta / Keys.A 等），覆盖字母、数字、修饰键、符号、方向键、F1-F12、编辑键与小键盘	Record<string, string>

无障碍

• 键位提示的 DOM 结构与 Semi 一致（div.cd-hotKeys > span > span.cd-hotKeys-content，分隔符 span.cd-hotKeys-split），是纯展示元素，不引入焦点陷阱
• 快捷键匹配用 event.code（物理键位）而非 event.key，天然规避输入法、大小写与 Shift 干扰
• 键位块文字与背景对比度 ≥ 4.5:1
• 与常用浏览器快捷键冲突时，用 preventDefault 明确接管，避免用户预期落空

设计变量

color

height

radius

spacing

width

变量	默认值	用法
--cd-color-hotkeys-bg	var(--cd-color-fill-0)	单个键位块背景（对齐 Semi fill-0）
--cd-color-hotkeys-split	var(--cd-color-text-0)	键位之间 + 分隔符颜色（对齐 Semi text-0）
--cd-color-hotkeys-text	var(--cd-color-text-2)	键位块内文字/符号颜色（对齐 Semi text-2）

显示第 1 条-第 3 条，共 3 条

• 1