Kbd

kbd

展示键位或快捷键，做成键帽的样子

用法

单键

包裹单个按键名，渲染为带边框的键帽样式。

Esc

tsx

<Kbd>Esc</Kbd>

组合键

KbdGroup 收口 gap 与分隔符，默认用 + 连接。

⌘K

tsx

<KbdGroup keys={["⌘", "K"]} />

换分隔符 / 不要分隔符

separator 可换成任意节点；传 null 只留间距。

⌘⇧PGT

tsx

<KbdGroup keys={["⌘", "⇧", "P"]} separator="·" />
<KbdGroup keys={["G", "T"]} separator={null} />

读屏名

label 给整组一个无障碍名，分隔符本身不进无障碍树。

⌘K

tsx

<KbdGroup keys={["⌘", "K"]} label="打开命令面板" />

自己摆键帽

需要给某个键单独加样式或换内容时改用 children，分隔符照插。

⌘S

tsx

<KbdGroup label="保存">
  <Kbd className="min-w-8">⌘</Kbd>
  <Kbd>S</Kbd>
</KbdGroup>

嵌入正文

随文展示快捷键，键帽与文字基线对齐。

按 ⌘S 即可保存

tsx

<span className="text-sm text-muted-foreground">
  按 <KbdGroup keys={["⌘", "S"]} label="保存" /> 即可保存
</span>

何时用

标注单个键位/快捷键（Esc、⌘、K），等宽键帽皮肤。组合键（⌘ + K）用同目录的 KbdGroup 包起来，它统一 gap、画分隔符、并给整组一个读屏名。两者都是 RSC，可在服务端组件直接用。展示代码片段用 CodeBlock/Snippet。

导入

import { Kbd, KbdGroup } from "@hulianui/ui"

Props

名称	类型	默认	说明
...HTMLAttributes	`HTMLAttributes<HTMLElement>`	-	透传 `<kbd>` 原生属性（className、style 等）

KbdGroup Props

名称	类型	默认	说明
keys	`ReactNode[]`	-	键名数组，逐个包成 Kbd。组合键的常规写法
separator	`ReactNode`	`"+"`	键之间的分隔符，装饰性（带 `aria-hidden`，不进无障碍树）。传 `null` 只留间距不画符号
label	`string`	-	整组的无障碍名，如「打开命令面板」。给了才会加 `role="group"`
...HTMLAttributes	`HTMLAttributes<HTMLSpanElement>`	-	透传外层 `<span>` 原生属性。rest 展开在最前，组件自己算出的 `role` / `aria-label` 赢（见「禁忌 / 坑」）

Slots

插槽	类型	说明
children	`ReactNode`	Kbd 的键位内容；KbdGroup 上表示自己摆键帽（给了就忽略 `keys`）

禁忌 / 坑

单个 Kbd 只渲染一个键帽，不内置 + 分隔；组合键请用 KbdGroup，别在调用处手搓 inline-flex + gap + 分隔符 —— 那样每处的间距和分隔符样式都会各写一套。
如果不传 label，KbdGroup 不会加 role="group"，读屏把几个键帽念成互不相干的碎片。视觉上完全看不出差别，所以这一步最容易漏：只要这组键代表一个具体动作，就把动作名写进 label。
children 与 keys 同时给时只用 children，keys 被忽略（两者同时生效没有合理语义）。
传 `role` 顶不掉组件自己的 `role="group"`（rest 展开在根节点属性最前，见 consuming.md §7）。没传 label 时组件不占 role，此时传什么就是什么。
不做符号映射（Meta → ⌘、Ctrl → ⌃ 之类）。键名显示成什么取决于消费方的平台探测与文案口径，库内置一张表在跨平台产品里必然猜错。

相关

Code · CodeBlock · Snippet · CodeDiff · Text · Heading

用法

单键

包裹单个按键名，渲染为带边框的键帽样式。

Esc

tsx

<Kbd>Esc</Kbd>

组合键

KbdGroup 收口 gap 与分隔符，默认用 + 连接。

⌘K

tsx

<KbdGroup keys={["⌘", "K"]} />

换分隔符 / 不要分隔符

separator 可换成任意节点；传 null 只留间距。

⌘⇧PGT

tsx

<KbdGroup keys={["⌘", "⇧", "P"]} separator="·" />
<KbdGroup keys={["G", "T"]} separator={null} />

读屏名

label 给整组一个无障碍名，分隔符本身不进无障碍树。

⌘K

tsx

<KbdGroup keys={["⌘", "K"]} label="打开命令面板" />

自己摆键帽

需要给某个键单独加样式或换内容时改用 children，分隔符照插。

⌘S

tsx

<KbdGroup label="保存">
  <Kbd className="min-w-8">⌘</Kbd>
  <Kbd>S</Kbd>
</KbdGroup>

嵌入正文

随文展示快捷键，键帽与文字基线对齐。

按 ⌘S 即可保存

tsx

<span className="text-sm text-muted-foreground">
  按 <KbdGroup keys={["⌘", "S"]} label="保存" /> 即可保存
</span>

Props

名称	类型	默认	说明
...HTMLAttributes	`HTMLAttributes<HTMLElement>`	-	透传 `<kbd>` 原生属性（className、style 等）

KbdGroup Props

名称	类型	默认	说明
keys	`ReactNode[]`	-	键名数组，逐个包成 Kbd。组合键的常规写法
separator	`ReactNode`	`"+"`	键之间的分隔符，装饰性（带 `aria-hidden`，不进无障碍树）。传 `null` 只留间距不画符号
label	`string`	-	整组的无障碍名，如「打开命令面板」。给了才会加 `role="group"`
...HTMLAttributes	`HTMLAttributes<HTMLSpanElement>`	-	透传外层 `<span>` 原生属性。rest 展开在最前，组件自己算出的 `role` / `aria-label` 赢（见「禁忌 / 坑」）

插槽

类型

说明

children

ReactNode

Kbd 的键位内容；KbdGroup 上表示自己摆键帽（给了就忽略 keys）

禁忌 / 坑

单个 Kbd 只渲染一个键帽，不内置 + 分隔；组合键请用 KbdGroup，别在调用处手搓 inline-flex + gap + 分隔符 —— 那样每处的间距和分隔符样式都会各写一套。

如果不传 label，KbdGroup 不会加 role="group"，读屏把几个键帽念成互不相干的碎片。视觉上完全看不出差别，所以这一步最容易漏：只要这组键代表一个具体动作，就把动作名写进 label。

children 与 keys 同时给时只用 children，keys 被忽略（两者同时生效没有合理语义）。

传 `role` 顶不掉组件自己的 `role="group"`（rest 展开在根节点属性最前，见 consuming.md §7）。没传 label 时组件不占 role，此时传什么就是什么。

不做符号映射（Meta → ⌘、Ctrl → ⌃ 之类）。键名显示成什么取决于消费方的平台探测与文案口径，库内置一张表在跨平台产品里必然猜错。