企业官网建设流程全解析

• 前端
• UI组件

Kbd 是 rsuite 组件库中用于展示键盘按键的小型提示组件，适合在文档、快捷键说明、表单提示等场景中标记物理按键（如Command、Ctrl、Enter）。本文以 Kbd 组件文档 为主体，结合仓库源码、样式与测试用例，完整讲解 Kbd 的导入方式、四种尺寸、文本内嵌用法、Props 参数以及底层渲染与样式实现，帮助你快速上手并深入理解其工作原理。

Kbd 是什么

Kbd（键盘提示符，Keyboard Key 的缩写）用于在界面上表示键盘上的按键。它渲染为语义化的<kbd>元素，并带有键盘按键风格的视觉样式（边框、内阴影、等宽字体），让用户一眼就能识别出"这里描述的是一个物理按键"。

在 rsuite 中，Kbd 是一个轻量级组件，常用于：

• 快捷键提示文案，例如"按Command + K打开命令面板"；
• 表单输入框下方的操作指引；
• 文档或帮助中心中的按键说明。

获取组件

Kbd 与其他 rsuite 组件一样，可以通过两种方式引入。

方式一：从 rsuite 主包整体引入

import { Kbd } from 'rsuite';

方式二：按需引入

import Kbd from 'rsuite/Kbd';

组件从 src/Kbd/index.tsx 导出，同时导出了Kbd组件与KbdProps类型，便于 TypeScript 用户获取完整的类型定义。

基础用法

最简单的用法是直接把按键文本作为子节点传入：

import { Kbd } from 'rsuite'; const App = () => <Kbd>Command + K</Kbd>; ReactDOM.render(<App />, document.getElementById('root'));

渲染效果为一个按键样式的<kbd>元素，完整示例可参考 basic.md。

需要表示组合键时，可以将多个<Kbd>用+连接（参考 Storybook 中的 Combination 示例）：

<Kbd>Ctrl</Kbd> + <Kbd>Shift</Kbd> + <Kbd>P</Kbd>

仓库中还提供了功能键组合的示例片段 function-keys.md，可用于 F1~F12 等功能键的展示场景。

尺寸

Kbd 支持lg、md、sm、xs四种尺寸，默认尺寸为md。通过size属性即可切换：

import { Kbd, VStack } from 'rsuite'; const App = () => ( <VStack> <Kbd size="lg">Command + K</Kbd> <Kbd size="md">Command + K</Kbd> <Kbd size="sm">Command + K</Kbd> <Kbd size="xs">Command + K</Kbd> </VStack> ); ReactDOM.render(<App />, document.getElementById('root'));

完整示例见 size.md。

从样式源码看，尺寸差异由 CSS 变量驱动。在 src/Kbd/styles/index.scss 中，四个尺寸分别映射了对应的字体大小与字距变量：

$sizes: lg, md, sm, xs; @each $size in $sizes { &-#{$size} { --rs-kbd-font-size: var(--rs-kbd-font-size-#{$size}); --rs-kbd-letter-spacing: var(--rs-kbd-letter-spacing-#{$size}); } }

变量在 src/Kbd/styles/_variables.scss 中定义，形成自小到大的字号阶梯：

--rs-kbd-font-size-xs: var(--rs-font-size-2xs); --rs-kbd-font-size-sm: var(--rs-font-size-xs); --rs-kbd-font-size-md: var(--rs-font-size-sm); --rs-kbd-font-size-lg: var(--rs-font-size-md);

也就是说，size改变的是按键内文字的字号与字距，而按键的内边距、边框、圆角等结构样式在所有尺寸下保持一致。

在文本中使用

Kbd 常与普通文本混排，用来在句子中提示按键。可以将 Kbd 与 Text 组件搭配使用：

import { Kbd, Text } from 'rsuite'; const App = () => ( <Text> Please press <Kbd>Command</Kbd> + <Kbd>K</Kbd> to open the keyboard. </Text> ); ReactDOM.render(<App />, document.getElementById('root'));

完整示例见 inside-text.md。

由于 Kbd 的底层样式设置了display: inline-flex与vertical-align: middle（见 src/Kbd/styles/_mixin.scss），它能够自然地与行内文本基线对齐，在句子中不会产生突兀的换行或错位。

Props 详解

Kbd 的对外 API 十分精简，官方文档给出的 Props 如下：

<Kbd>

在源码 src/Kbd/Kbd.tsx 中，这些 Props 的具体处理逻辑如下：

• children：任意 ReactNode，作为按键内容渲染；组合键场景下可以传入多个<Kbd>或其他元素。
• classPrefix：CSS 类名前缀，默认'kbd'。实际渲染时通过useStyles('kbd')生成rs-kbd基础类，并叠加尺寸类名rs-kbd-{size}，例如rs-kbd-lg。
• size：接受'lg' | 'md' | 'sm' | 'xs'，默认'md'。其合并逻辑为：

const { as = 'kbd', classPrefix = 'kbd', className, size = 'md', ...rest } = propsWithDefaults; const { withPrefix, merge } = useStyles(classPrefix); const classes = merge(className, withPrefix(size)); return <Box as={as} {...rest} ref={ref} className={classes} />;

值得一提的是，KbdProps扩展自BoxProps（export interface KbdProps extends BoxProps），因此它还继承了 Box 组件的通用能力，例如as（自定义渲染元素）、className、style以及 ref 转发等。as默认为'kbd'，你也可以将其替换为'samp'、'code'等其他语义化标签。

另外，组件内部通过useCustom('Kbd', props)读取CustomProvider提供的默认配置，这意味着你可以通过全局主题配置统一覆盖 Kbd 的默认size等属性。

源码实现剖析

Kbd 的实现非常精简，核心逻辑全部集中在一个约 30 行的组件中（src/Kbd/Kbd.tsx），其本质是基于 internals/Box 的一个封装：

1. useCustom('Kbd', props)合并全局配置与组件 Props；
2. useStyles('kbd')生成带rs-前缀的类名工具；
3. 组合基础类与尺寸类，交给Box渲染为<kbd>元素。

视觉样式由 src/Kbd/styles/_mixin.scss 中的kbdmixin 提供：

display: inline-flex; align-items: center; justify-content: center; vertical-align: middle; border-radius: var(--rs-radius-sm); background-color: var(--rs-kbd-bg); border: solid 1px var(--rs-kbd-border); box-shadow: inset 0 -1px 0 var(--rs-kbd-border); color: var(--rs-kbd-text); font-family: var(--rs-kbd-font-family);

其中按键背景色、边框色、文字色、字体族等均由主题 CSS 变量控制（如--rs-kbd-bg、--rs-kbd-border、--rs-kbd-text、--rs-kbd-font-family），因此 Kbd 的观感会随 rsuite 主题（默认主题、暗色主题等）自动适配，无需额外定制。

测试与验证

仓库为 Kbd 提供了完整的单元测试（src/Kbd/test/Kbd.spec.tsx），覆盖了核心行为：

• 渲染结果为<kbd>元素（expect(container.firstChild).to.have.tagName('kbd')）；
• children 内容正确渲染；
• 各尺寸均生成对应的rs-kbd-{size}类名；
• 通过testStandardProps校验标准属性（className、style、id 等）的透传行为。

此外，Storybook 示例 提供了Default、Sizes、Combination三个交互场景，可以直接在本地运行 Storybook 查看不同尺寸与组合键的实际效果。

小结

Kbd 是 rsuite 中一个"小而美"的组件：API 只有children、classPrefix、size三个核心 Props，却通过语义化的<kbd>标签、主题驱动的 CSS 变量与四种尺寸变体，为快捷键提示场景提供了开箱即用的解决方案。理解其底层"Box 封装 + CSS 变量尺寸体系 + CustomProvider 默认值"的实现思路，也有助于你在阅读 rsuite 其他组件时举一反三。

• 前端
• UI组件