wui
组件

键盘提示 Kbd

用紧凑、高对比度且克制的按键样式展示快捷键与键盘操作提示。

第三方依赖 · class-variance-authority

基础用法

使用 Kbd 展示单个物理按键,使用 KbdGroup 将组合快捷键紧凑组合排列:

Loading…

安装与引入

通过 CLI 自动添加组件,或手动复制源码至项目中:

pnpm dlx @wui-design/cli@latest add @wui/kbd
安装样式辅助依赖
pnpm add class-variance-authority clsx tailwind-merge
复制组件源码到 components/ui/kbd.tsx
components/ui/kbd.tsx
import * 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,适用于紧凑下拉菜单与搜索输入框)。
pressedbooleanfalse以主色高亮并轻微下沉,表示该键正被按下。适合在新手引导、快捷键设置中实时映射用户的键盘输入;系统开启“减少动态效果”时仅变色不位移。
classNamestring—应用于 <kbd> 标签的额外 CSS 类名。

KbdGroup Props

继承原生 <span> 元素的全部 HTML 属性,内部自动应用 gap-1 保持按键之间的规整间隙。

事件 Events

属性类型默认值说明
className / styleReact.HTMLAttributes<HTMLElement>—继承原生 <kbd> 与 <span> 容器属性。注意:键盘提示组件属于说明型视觉标签(非按钮),不应在其上绑定点击交互;需触发操作请使用 Button 并在内部嵌套 Kbd 作为快捷键提示。

使用场景与设计规范

Kbd 用于界面操作提示、命令面板、全局搜索框与快捷键说明:

  • 提示而非交互实体:Kbd 本身不是按钮,不可点击。例如“新建文件”是操作入口,右侧附带的 ⌘ + N 是键盘提示,两者各司其职。
  • 跨平台符号规范:
    • macOS 推荐使用紧凑符号:⌘ (Command)、⌥ (Option)、⇧ (Shift)、⌃ (Control)、⌫ (Delete)、↵ (Enter)。
    • Windows/Linux 推荐使用清晰缩写:Ctrl、Alt、Shift、Enter、Esc。
  • 与输入框与菜单集成:在输入框内(如全局搜索 ⌘K)或下拉菜单项右侧,推荐使用 size="sm" 以保持行高和谐。

场景示例

尺寸对比 (Default vs Small)

对比标准尺寸与紧凑小尺寸在不同修饰键下的视觉呈现:

Loading…

实时按键反馈(pressed)

在输入框中按下 Enter 或 Shift + Enter,对应的按键提示会实时高亮并轻微下沉,帮助用户建立快捷键记忆:

Loading…

下拉菜单与命令面板中的快捷键提示

在命令面板、搜索框与下拉菜单条目右侧集成 KbdGroup 提示:

Loading…

无障碍与交互 Accessibility

  • 原生 <kbd> 语义:底层使用 HTML5 标准 <kbd> 标签,屏幕阅读器与辅助技术可准确识别按键文本。
  • 组合键无障碍标注:当快捷键使用纯符号(如 ⌘ K)呈现时,建议在父级容器上添加 aria-label="快捷键:Command K",以便盲人读屏软件播报出完整发音。
  • 高对比度显示:背景使用高辨识度微底色配合细边框,在深色和浅色模式下均拥有清晰的键位边界。