RSUITE Divider 分割线组件完全指南:从基础用法到源码级原理剖析
RSUITE Divider 分割线组件完全指南:从基础用法到源码级原理剖析
分割线(Divider)是界面设计中用于将内容在水平或垂直方向上分组的基础视觉组件。本指南以 rsuite 官方文档中 Divider 组件的全部演示片段(basic、with-label、appearance、size、color、vertical)与 Props 表格为核心骨架,结合 Divider 源码、样式实现 与 单元测试 进行纵深解读,帮助你从「会调用」进阶到「懂原理」,能够按需定制分组线的外观、尺寸、颜色、标签与方向。
组件定位与核心能力
rsuite 的 Divider 组件用于将内容水平或垂直地分组(官方英文文档描述为 "Divider are used to group content horizontally or vertically")。它并不复杂,却承担着内容节奏划分的重任:在表单区块之间、卡片内部、列表分隔等场景中,一条恰到好处的分割线能让界面层次一目了然。
从源码结构看,Divider 基于 StyledBox 构建,并复用了 rsuite 内部统一的尺寸(Size)、颜色(Color)与样式工具函数(见 Divider.tsx 的 getSizeStyle、useStyles),这意味着它的尺寸、颜色语义与 rsuite 其他组件(如 Button、Text)保持一致的 Design Token 体系。
基础用法:最小可运行示例
basic 示例展示了 Divider 最典型的应用场景——在两个内容块之间插入水平分割线:
import { Divider, Placeholder } from 'rsuite';
const App = () => (
<>
<Placeholder.Paragraph type="media" />
<Divider spacing="md" />
<Placeholder.Paragraph type="media" />
</>
);
ReactDOM.render(<App />, document.getElementById('root'));
关键点说明:
spacing="md":控制分割线与上下内容之间的间距,可选xs | sm | md | lg | xl,也支持数字或任意 CSS 字符串(详见下文「间距(spacing)」小节)。Placeholder.Paragraph:rsuite 的占位组件,仅用于模拟真实内容,实际项目中应替换为你的业务内容块。- 不传任何属性时,Divider 渲染为一条默认实线(solid)、默认尺寸(xs)的水平分割线,并带有
role="separator"无障碍语义(由源码StyledBox的role="separator"注入,见 Divider.tsx)。
带标签的分割线(label 与 labelPlacement)
很多时候我们希望分割线上附带文字或交互元素,例如「更多设置」「分隔说明」。带标签功能自 rsuite 6.0.0 起正式提供,通过 label 与 labelPlacement 两个属性实现。
文本标签与三种位置
import { Divider, Placeholder, Button } from 'rsuite';
const App = () => (
<>
<Divider spacing="md" label="Label (start)" labelPlacement="start" />
<Divider spacing="md" label="Label (center)" labelPlacement="center" />
<Divider spacing="md" label="Label (end)" labelPlacement="end" />
<Divider spacing="md" label={<Button>Button</Button>} />
</>
);
ReactDOM.render(<App />, document.getElementById('root'));
labelPlacement接受'start' | 'center' | 'end',分别表示标签位于分割线起始端、正中间、结束端。默认值为center(不传该属性时居中,测试中渲染的 DOM 不含data-placement属性,见 Divider.spec.tsx)。label类型为ReactNode,因此不仅可以传字符串,还可以传任意 React 组件,如上面的<Button>Button</Button>——这为「分割线旁放一个操作按钮」的常见设计提供了零成本实现。
源码级实现:伪元素画线
带标签的分割线并不是「先画一条线再叠上文字」,而是由样式层用伪元素绘制:
- 水平 + 带标签时,容器变为
display: flex; align-items: center,::before与::after两个伪元素各承担一侧线段(见 index.scss 中[data-orientation='horizontal'][data-with-label='true']规则); data-placement='start'时隐藏::before(左侧无线),data-placement='end'时隐藏::after(右侧无线),从而实现三种标签位置;- 这些数据属性(
data-orientation、data-with-label、data-placement)均由源码根据 props 动态写入 DOM(见 Divider.tsx)。
对应的单元测试也逐一验证了该行为(Divider.spec.tsx):
- 文本标签
label="Test Label"时,容器带有data-with-label="true"且文本正确渲染; - 组件标签
label={<Button>Click Me</Button>}时,可正常渲染出按钮; labelPlacement="start"/"end"分别产生data-placement属性,默认居中时不输出该属性。
外观(appearance):solid / dashed / dotted
appearance 属性控制分割线的线型,取值 'solid' | 'dashed' | 'dotted',默认 solid:
import { Divider } from 'rsuite';
const App = () => (
<>
<Divider spacing="md" label="Solid(default)" />
<Divider spacing="md" appearance="dashed" label="Dashed" />
<Divider spacing="md" appearance="dotted" label="Dotted" />
</>
);
ReactDOM.render(<App />, document.getElementById('root'));
实现层面,线型并非直接写死在样式里,而是通过 CSS 变量 --rs-divider-border-style 驱动:源码中 appearance 被映射为 data-appearance 属性,样式层用 :where([data-appearance='dashed']) / :where([data-appearance='dotted']) 覆盖该变量(见 index.scss)。这也解释了为什么「带标签模式」下的伪元素线段同样能跟随线型变化——它们统一读取 --rs-divider-border-style。测试用例通过断言 data-appearance 属性验证 dashed、dotted 两种外观的渲染(Divider.spec.tsx)。
尺寸(size):预设档位与任意数值
size 控制分割线的粗细,支持预设档位 xs | sm | md | lg | xl,也支持任意数字或 CSS 字符串:
import { Divider } from 'rsuite';
const App = () => (
<>
<Divider size="xs" label="xs" />
<Divider size="sm" label="sm" />
<Divider size="md" label="md" />
<Divider size="lg" label="lg" />
<Divider size={6} label={6} />
<Divider size="0.5rem" label="0.5rem" />
</>
);
ReactDOM.render(<App />, document.getElementById('root'));
关于预设档位,可以结合源码得到精确换算关系:
| size 取值 | 实际线宽(CSS 变量) | 换算值 |
|---|---|---|
xs(默认) |
--rs-divider-size-xs |
0.0625rem × --rs-scale |
sm |
--rs-divider-size-sm |
0.125rem × --rs-scale |
md |
--rs-divider-size-md |
0.1875rem × --rs-scale |
lg |
--rs-divider-size-lg |
0.25rem × --rs-scale |
xl |
--rs-divider-size-xl |
0.3125rem × --rs-scale |
换算表依据 index.scss 第 4-9 行整理。
--rs-scale是 rsuite 主题体系中的全局缩放变量,因此分割线粗细会随主题缩放同步变化。
水平分割线将 size 应用于 border-top-width,垂直分割线则应用于 border-inline-start-width(见 index.scss 中两个 data-orientation 规则)。
注意:Props 表中
size的类型为'xs' | 'sm' | 'md' | 'lg' | number | string,但垂直示例中还使用了xl档位;而testStyleProps测试对sizes同样传入了['xs', 'sm', 'md', 'lg', 'xl'](Divider.spec.tsx),说明xl也是受支持的尺寸档位。
颜色(color):预设色与自定义色
color 属性接受 rsuite 的预设颜色(Color 类型)或任意 CSS 颜色值:
import { Divider } from 'rsuite';
const App = () => (
<>
<Divider color="red" label="Red" />
<Divider color="orange" label="Orange" />
<Divider color="yellow" label="Yellow" />
<Divider color="green" label="Green" />
<Divider color="cyan" label="Cyan" />
<Divider color="blue" label="Blue" />
<Divider color="violet" label="Violet" />
<Divider color="#000" label="Custom Color" />
</>
);
ReactDOM.render(<App />, document.getElementById('root'));
实现细节:
- 预设色(
red、green、blue、violet等)经由StyledBox的colorprop 转换为对应的主题色变量--rs-divider-color,再透传到边框颜色变量--rs-divider-border-color: var(--rs-divider-color, var(--rs-divider-border))(见 index.scss 第 19 行); - 任意自定义值(如
"#000")会作为 CSS 颜色直接生效; - 标签文字颜色同样使用
color: var(--rs-divider-color, inherit),因此标签颜色会与分割线颜色保持语义一致; - 测试用例通过
testStyleProps的colors选项验证了多组预设色的样式渲染(Divider.spec.tsx)。
垂直分割线(vertical)
vertical 为布尔属性,开启后分割线变为垂直方向,常用于水平排布的内容组(如操作栏、导航项)之间。注意:官方 Props 表明确标注「不能与 label 同时使用」。
import { Divider, Button, HStack } from 'rsuite';
const App = () => (
<HStack spacing={0}>
<Divider vertical size="xs" />
<label>Xsmall</label>
<Divider vertical size="sm" />
<label>Small</label>
<Divider vertical size="md" />
<label>Medium</label>
<Divider vertical size="lg" />
<label>Large</label>
<Divider vertical size="xl" />
<label>Extra Large</label>
</HStack>
);
ReactDOM.render(<App />, document.getElementById('root'));
垂直模式的关键样式(index.scss 中 [data-orientation='vertical'] 规则):
display: inline-block+height: 100%,可随父容器高度拉伸;min-height: 1em,确保内容很少时仍保持可见;width: 1px,线宽由border-inline-start-width: var(--rs-divider-size)决定;- 使用
margin-inline控制左右间距(水平模式则用margin-block控制上下间距)。
测试通过断言 data-orientation="vertical" 属性验证垂直渲染(Divider.spec.tsx)。示例中与 HStack(水平堆叠布局组件)搭配,实现了「标签 + 垂直分割线」交替排列的紧凑工具栏分隔效果。
Props 完整参考表
以下为官方文档 Props 表(合并 en-US 与 zh-CN 两版)的完整内容:
| 属性 | 类型 | 描述 | 版本 |
|---|---|---|---|
appearance |
'solid' | 'dashed' | 'dotted' |
分割线的外观样式 | — |
as |
ElementType (div) |
自定义元素类型,可将分割线渲染为其他标签 | — |
classPrefix |
string ('divider') |
组件 CSS 类的前缀,默认 divider(渲染为 rs-divider) |
— |
color |
Color | CSSProperties['color'] |
分割线的颜色,支持预设主题色与任意 CSS 颜色 | — |
label |
ReactNode |
标签内容,可为文本或任意 React 组件 | 6.0.0 |
labelPlacement |
'start' | 'center' | 'end' |
标签位置,默认居中 | 6.0.0 |
size |
'xs' | 'sm' | 'md' | 'lg' | number | string |
分割线的粗细 | — |
spacing |
'xs' | 'sm' | 'md' | 'lg' | number | string |
分割线与内容之间的间距 | — |
vertical |
boolean |
垂直分割线,不能与 label 同时使用 | — |
补充说明(基于源码):
as:Divider 继承自BoxProps,as支持自定义渲染标签,源码中as原样传递给StyledBox(Divider.tsx)。label与children的等价关系:源码中label = children,即未显式传label时,<Divider>text</Divider>的子节点会被当作标签渲染(测试也验证了children即标签的行为,见 Divider.spec.tsx)。spacing的实现:spacing经getSizeStyle(spacing, 'divider', 'spacing')转译为 CSS 变量--rs-divider-spacing,预设档位换算如下(index.scss 第 11-16 行):
| spacing 取值 | 实际间距(CSS 变量) |
|---|---|
xs |
--rs-spacing × 2 |
sm |
--rs-spacing × 3 |
md |
--rs-spacing × 4 |
lg |
--rs-spacing × 5 |
xl |
--rs-spacing × 6 |
其中 --rs-spacing 是 rsuite 全局间距变量,因此间距同样会随主题配置联动。
无障碍与语义
Divider 的源码中硬编码了 role="separator"(Divider.tsx),这是 WAI-ARIA 中用于分割内容的语义角色。单元测试的第一条用例即是验证渲染结果具备 rs-divider 类且可通过 getByRole('separator') 查询到(Divider.spec.tsx)。这意味着:
- 屏幕阅读器能够正确识别分割线并跳过其内容;
- 在测试与自动化工具中,可通过标准角色查询分割线节点,而无需依赖脆弱的选择器。
组合实践:一条分割线搞定多种场景
基于上述能力,可将 Divider 灵活组合进真实页面:
// 表单分区 + 操作按钮标签 + 自定义线宽
<Divider label="账户信息" labelPlacement="start" spacing="lg" />
<Divider appearance="dashed" size={2} color="#e0e0e0" />
// 工具栏中的垂直分隔
<HStack spacing={0}>
<Button>新建</Button>
<Divider vertical size="sm" />
<Button>导入</Button>
<Divider vertical size="sm" />
<Button>导出</Button>
</HStack>
小结
本指南覆盖了 rsuite Divider 的全部官方演示与 Props,并下钻到源码与测试层面:
- 基础用法:
<Divider spacing="md" />在内容块之间插入分组线; - 标签与位置:
label(可传任意 ReactNode)+labelPlacement(start/center/end),由伪元素实现两侧线段; - 外观/尺寸/颜色:
appearance映射为 CSS 变量--rs-divider-border-style;size与spacing均可使用预设档位或任意数值/CSS 字符串,并通过--rs-scale、--rs-spacing与主题联动;color支持预设主题色与任意 CSS 颜色; - 垂直模式:
vertical属性配合HStack可构建紧凑的工具栏分隔; - 工程化细节:
role="separator"无障碍语义、children即标签的等价行为,以及testStyleProps对尺寸/颜色/间距预设档位的系统性测试保障。
想要深入阅读实现细节,可以继续探索以下仓库路径:组件源码、样式实现、单元测试、Storybook 示例。