RSUITE Divider 分割线组件完全指南:从基础用法到源码级原理剖析

原创2026-09-26 21:50:201,937 阅读
文章标签:前端UI组件

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 的 color prop 转换为对应的主题色变量 --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 示例。

登录后查看全文
rsuite