组件
键盘提示 Kbd
用紧凑、高对比度且克制的按键样式展示快捷键与键盘操作提示。
基础用法
使用 Kbd 展示单个物理按键,使用 KbdGroup 将组合快捷键紧凑组合排列:
Loading…
安装与引入
通过 CLI 自动添加组件,或手动复制源码至项目中:
pnpm dlx @wui-design/cli@latest add @wui/kbd安装样式辅助依赖
pnpm add class-variance-authority clsx tailwind-merge复制组件源码到
components/ui/kbd.tsximport * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"
const kbdVariants = cva(
"inline-flex shrink-0 items-center justify-center rounded-sm border border-border bg-muted/70 font-sans font-medium leading-none text-muted-foreground select-none transition-[color,background-color,border-color,translate] duration-150 ease-out data-[pressed]:translate-y-px data-[pressed]:border-primary data-[pressed]:bg-primary data-[pressed]:text-primary-foreground motion-reduce:transition-none motion-reduce:data-[pressed]:translate-y-0",
{
variants: {
size: {
sm: "min-h-5 min-w-5 px-1 text-[10px]",
default: "min-h-6 min-w-6 px-1.5 text-[11px]",
},
},
defaultVariants: {
size: "default",
},
}
)
export interface KbdProps
extends React.ComponentProps<"kbd">,
VariantProps<typeof kbdVariants> {
/** Physical size of the key hint. @default "default" */
size?: "sm" | "default"
/**
* Highlight the key as physically held down, e.g. to mirror live keyboard
* input in onboarding or shortcut settings. @default false
*/
pressed?: boolean
}
/** A compact visual hint for one keyboard key. */
function Kbd({ className, size = "default", pressed = false, ...props }: KbdProps) {
return (
<kbd
data-slot="kbd"
data-size={size}
data-pressed={pressed || undefined}
className={cn(kbdVariants({ size }), className)}
{...props}
/>
)
}
/** Keeps multiple key hints aligned as one shortcut. */
function KbdGroup({ className, ...props }: React.ComponentProps<"span">) {
return (
<span
data-slot="kbd-group"
className={cn("inline-flex items-center gap-1", className)}
{...props}
/>
)
}
export { Kbd, KbdGroup, kbdVariants }
属性 Props
Kbd Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| size | "sm" | "default" | "default" | 按键提示的物理尺寸密度。default(高度 24px),sm(高度 20px,适用于紧凑下拉菜单与搜索输入框)。 |
| pressed | boolean | false | 以主色高亮并轻微下沉,表示该键正被按下。适合在新手引导、快捷键设置中实时映射用户的键盘输入;系统开启“减少动态效果”时仅变色不位移。 |
| className | string | — | 应用于 <kbd> 标签的额外 CSS 类名。 |
KbdGroup Props
继承原生 <span> 元素的全部 HTML 属性,内部自动应用 gap-1 保持按键之间的规整间隙。
事件 Events
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| className / style | React.HTMLAttributes<HTMLElement> | — | 继承原生 <kbd> 与 <span> 容器属性。注意:键盘提示组件属于说明型视觉标签(非按钮),不应在其上绑定点击交互;需触发操作请使用 Button 并在内部嵌套 Kbd 作为快捷键提示。 |
使用场景与设计规范
Kbd 用于界面操作提示、命令面板、全局搜索框与快捷键说明:
- 提示而非交互实体:
Kbd本身不是按钮,不可点击。例如“新建文件”是操作入口,右侧附带的⌘ + N是键盘提示,两者各司其职。 - 跨平台符号规范:
- macOS 推荐使用紧凑符号:
⌘(Command)、⌥(Option)、⇧(Shift)、⌃(Control)、⌫(Delete)、↵(Enter)。 - Windows/Linux 推荐使用清晰缩写:
Ctrl、Alt、Shift、Enter、Esc。
- macOS 推荐使用紧凑符号:
- 与输入框与菜单集成:在输入框内(如全局搜索
⌘K)或下拉菜单项右侧,推荐使用size="sm"以保持行高和谐。
场景示例
尺寸对比 (Default vs Small)
对比标准尺寸与紧凑小尺寸在不同修饰键下的视觉呈现:
Loading…
实时按键反馈(pressed)
在输入框中按下 Enter 或 Shift + Enter,对应的按键提示会实时高亮并轻微下沉,帮助用户建立快捷键记忆:
Loading…
下拉菜单与命令面板中的快捷键提示
在命令面板、搜索框与下拉菜单条目右侧集成 KbdGroup 提示:
Loading…
无障碍与交互 Accessibility
- 原生
<kbd>语义:底层使用 HTML5 标准<kbd>标签,屏幕阅读器与辅助技术可准确识别按键文本。 - 组合键无障碍标注:当快捷键使用纯符号(如
⌘K)呈现时,建议在父级容器上添加aria-label="快捷键:Command K",以便盲人读屏软件播报出完整发音。 - 高对比度显示:背景使用高辨识度微底色配合细边框,在深色和浅色模式下均拥有清晰的键位边界。