企业官网建设流程全解析

• 前端
• UI组件

ProseKbd 是 Nuxt UI（gh_mirrors/ui4/ui 仓库）中负责在富文本内容里渲染键盘按键的排版组件，它把 Markdown/MDC 中写下的:kbd{value="meta"}这类指令转换成带统一样式的<kbd>元素，并自动适配不同操作系统上的按键符号。本文以 docs/content/docs/4.typography/kbd.md 为主线，结合底层组件 Kbd.vue、按键映射 composable useKbd.ts 与主题配置 kbd.ts，完整讲解在文档、博客等排版内容中展示快捷键组合的用法、API 与主题定制方案。

组件定位：排版内容里的 Prose 组件

在 Nuxt UI 的排版（Typography）体系中，所有 Markdown 内容默认渲染的 HTML 元素都会映射为对应的 Prose 组件（如ProseH1、ProseP、ProseCode等）。ProseKbd正是其中的一员，它负责在.md或.mdc内容文件中将键盘按键渲染为带样式的kbd元素，用于文档中说明快捷键、热键（hotkey）与按键组合。

ProseKbd 本身是一个轻量包装组件：源码 src/runtime/components/prose/Kbd.vue 在内部直接复用了通用组件库中的UKbd（即 src/runtime/components/Kbd.vue），并叠加了 Prose 场景专属的主题样式。这意味着你在排版内容中得到的渲染效果，与在模板里直接使用<UKbd>是完全一致的，只是外层额外套了一层.align-text-top对齐修正，让按键符号与相邻文字的对齐更协调（见 src/theme/prose/kbd.ts）。

Usage：在 MDC 内容中使用 kbd 组件

在 docs/content/docs/4.typography/kbd.md 中给出的核心用法是：在 Markdown 内容中通过 MDC（Markdown Components）内联组件语法使用kbd组件，配合value属性传入要展示的按键。

原始示例：

:kbd{value="meta"} :kbd{value="K"}

渲染结果即为一个带样式的键盘按键组合，例如在 macOS 上显示为⌘ K，在其他平台上则显示为Ctrl K。这种写法可以直接嵌入段落文字中，例如：

复制快捷键为 :kbd{value="ctrl"} + :kbd{value="C"}，在 macOS 上则是 :kbd{value="meta"} + :kbd{value="C"}。

在实际渲染时，MDC 语法中的:kbd会解析到 Prose 命名空间下的kbd组件。此外你完全可以在模板中使用等价的<UKbd value="meta" />，二者的渲染路径最终都收敛到同一个底层组件。

特殊按键与平台自适应：useKbd 的按键映射机制

value属性不仅支持普通字符（如K、C），还支持一批特殊按键名。这些按键名会经过useKbdcomposable 的getKbdKey函数转换成对应的 Unicode 按键符号。完整映射表定义在 src/runtime/composables/useKbd.ts 的kbdKeysMap中：

其中meta、alt、ctrl三个按键是平台自适应的：useKbd会通过navigator.userAgent检测当前是否运行在 macOS 上（源码第 39 行的macOS计算属性），并在组件挂载（onMounted）后把这三个键映射为对应平台的符号：

• meta：macOS 上渲染为⌘（command），其他平台渲染为Ctrl；
• ctrl：macOS 上渲染为⌃（control），其他平台渲染为Ctrl；
• alt：macOS 上渲染为⌥（option），其他平台渲染为Alt。

对于不在映射表中的任意字符串，getKbdKey会原样返回该字符串（源码第 62 行），因此你也可以传入F2、Space这类自定义按键文本。这一点也体现在文档 docs/content/docs/2.components/kbd.md 的 Value 示例列表中（meta、win、command、shift、ctrl、option、alt、enter、delete、backspace、escape、tab、capslock、arrowup、arrowright、arrowdown、arrowleft、pageup、pagedown、home、end均可直接使用）。

API 一览：Props 与 Slots

Props

ProseKbd 对外暴露的属性定义在 src/runtime/components/prose/Kbd.vue 的ProseKbdProps接口中：

• value?: string— 要显示的按键名或按键文本，会透传给底层UKbd并经过useKbd映射；
• class?: any— 覆盖或追加自定义类名，作用于根元素；
• ui?: { base?: any }— 针对 base 样式的定向覆盖，与 Nuxt UI 的uiprop 约定一致。

需要说明的是，ProseKbd 将 props 通过useComponentProps('prose.kbd', _props)进行解析（即支持 app.config.ts 中ui.prose.kbd的全局配置合并），而更丰富的样式控制能力来自其底层组件Kbd。若你在模板中直接使用 src/runtime/components/Kbd.vue，则额外支持：

• as?: any（默认'kbd'）— 渲染为的元素或组件，由 reka-ui 的Primitive提供，可改为span、strong等；
• color?（默认'neutral'）— 颜色，默认包含主题配置中的所有颜色与neutral；
• variant?（默认'outline'）— 变体：solid、outline、soft、subtle；
• size?（默认'md'）— 尺寸：sm、md、lg。

Slots

• default— 默认插槽。若提供了插槽内容，则优先渲染插槽内容；否则渲染value经过useKbd映射后的符号（对应Kbd.vue模板中的<slot>{{ getKbdKey(props.value) }}</slot>）。

Theme：主题结构与 Tailwind 实现

ProseKbd 的主题机制与 Nuxt UI 其他组件一致：在运行时通过tv({ extend: theme, ...(appConfig.ui?.prose?.kbd || {}) })将构建期生成的默认主题与用户全局配置合并（src/runtime/components/prose/Kbd.vue 第 35 行）。Prose 场景的默认主题非常克制，仅包含：

// src/theme/prose/kbd.ts export default { base: 'align-text-top' }

真正的视觉样式由底层Kbd主题 src/theme/kbd.ts 提供，其 base 类为：

inline-flex items-center justify-center px-1 rounded-sm font-medium font-sans uppercase

并定义了三种尺寸（size）、四种变体（variant）与颜色（color）的组合：

• size：sm（h-4 min-w-[16px] text-[10px]）、md（h-5 min-w-[20px] text-[11px]）、lg（h-6 min-w-[24px] text-[12px]）；
• variant × color：通过 compoundVariants 组合出完整的按键观感，例如neutral+outline为ring ring-inset ring-accented text-default bg-default，primary+solid为text-inverted bg-primary，neutral+solid为text-inverted bg-inverted等。颜色会依据模块配置options.theme.colors动态生成，因此只要在 Nuxt UI 主题中启用了某种颜色，Kbd就能直接使用。

实际渲染出的 HTML 可参考测试快照 test/components/snapshots/Kbd.spec.ts.snap，例如默认（md+neutral+outline）渲染为：

<kbd class="inline-flex items-center justify-center px-1 rounded-sm font-medium font-sans uppercase h-5 min-w-[20px] text-[11px] ring ring-inset ring-accented text-default bg-default">K</kbd>

从快照可以看出，底层的font-sans uppercase使所有按键文本统一为小尺寸大写样式，视觉上与代码块中的<kbd>风格保持一致的“键盘键”辨识度。

源码实现与测试验证

ProseKbd → Kbd 的调用链

完整调用链如下：

1. MDC 内容中的:kbd{value="meta"}被解析为ProseKbd；
2. ProseKbd通过useComponentProps('prose.kbd', _props)合并全局 app config，计算主题后渲染<UKbd :value="props.value" :class="ui(...)">；
3. 底层Kbd使用 reka-ui 的Primitive渲染为<kbd>（或as指定的元素），并调用useKbd().getKbdKey(props.value)生成按键符号。

测试覆盖

test/components/Kbd.spec.ts 使用 Vitest 对底层组件做了较完整的覆盖：

• 针对所有size、variant（primary/neutral 两种颜色）进行参数化渲染；
• 覆盖as（如渲染为span）、class（如追加font-bold）与默认插槽（如渲染 "Default slot"）等场景；
• 额外通过vitest-axe的axe断言组件通过无障碍测试（toHaveNoViolations），确保键盘按键以原生<kbd>语义输出，便于屏幕阅读器与搜索引擎理解。

kbd组件同样被CommandPalette、DropdownMenu、Tooltip、DashboardSearchButton等组件的快照测试引用（见 test/components/snapshots下的相关.snap文件），说明它是文档、菜单、工具栏等场景中展示快捷键的通用基础单元。

应用建议与 Changelog

• 在文档/博客内容中展示快捷键时，优先使用 MDC 语法:kbd{value="..."}，并搭配+连接多个按键即可构成组合键说明；
• 涉及跨平台快捷键时，使用meta、ctrl、alt等自适应键名，让 macOS 与 Windows/Linux 用户各自看到熟悉的符号，避免硬编码⌘或Ctrl；
• 若需要对按键样式做整体微调（如加大内边距、改为圆角胶囊），可以在app.config.ts中配置ui.prose.kbd与ui.kbd的覆盖，或通过class/ui.baseprop 按实例调整；
• 需要自定义显示文本时直接填充默认插槽即可，例如:kbd{value="meta"}+F无法表达的复杂内容可用插槽兜底。

Changelog 部分（对应文档中的:component-changelog{prefix="prose"}）记录了ProseKbd各版本的变更历史，可在仓库的 CHANGELOG.md 中查阅该组件相关的演进记录，便于在升级 Nuxt UI 时了解行为变化。

• 前端
• UI组件