Ant Design Divider（分割线）组件完全指南：API、变体与语义化定制

导读

Divider 是 Ant Design 布局体系中的基础组件，用于在页面中区隔不同内容区块，也常用于表格操作列、导航栏等场景下行内文本与链接之间的分隔。本文基于当前仓库中 components/divider/index.zh-CN.md 文档，结合 Divider 组件实现源码 与 样式 Token 定义，系统讲解 Divider 的全部 API、水平/垂直两种形态、虚线/点线/实线变体、5.25.0 引入的尺寸控制，以及 6.0.0 新增的 Semantic DOM 与 classNames/styles 精细定制能力，帮助你在真实项目中按需选用并精准定制分割线外观。

何时使用

Divider 的核心职责是"区隔"，官方文档给出的典型场景有两条：

• 对不同章节的文本段落进行分割——例如长文章、表单分区之间的水平分隔条；
• 对行内文字/链接进行分割——例如表格的操作列、工具栏按钮之间的垂直分隔竖线。

本质上，水平分割线面向"块级内容分层"，垂直分割线面向"行内元素分组"，二者正好对应文档中 orientation 的两种取值（horizontal / vertical）。

API 总览

Divider 同时支持 通用属性（如 className、style、prefixCls 等）。下表为组件专属属性，全部按当前中文文档继承整理：

参数	说明	类型	默认值	版本	全局配置
children	嵌套的标题	ReactNode	-		×
classNames	用于自定义组件内部各语义化结构的 class，支持对象或函数	Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string>	-		6.0.0
dashed	是否虚线	boolean	false		×
orientation	水平或垂直类型	horizontal | vertical	horizontal	-	×
orientationMargin	标题和最近 left/right 边框之间的距离，去除了分割线，同时 titlePlacement 不能为 center。如果传入 string 类型的数字且不带单位，默认单位是 px	string | number	-		×
plain	文字是否显示为普通正文样式	boolean	false	4.2.0	×
styles	用于自定义组件内部各语义化结构的行内 style，支持对象或函数	Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties>	-		6.0.0
size	间距大小，仅对水平布局有效	small | medium | large	-	5.25.0	×
titlePlacement	分割线标题的位置	start | end | center	center	-	×
type	水平还是垂直类型	horizontal | vertical	horizontal	-	×
variant	分割线是虚线、点线还是实线	dashed | dotted | solid	solid	5.20.0	×
vertical	是否垂直，和 orientation 同时配置以 orientation 优先	boolean	false	-	×

上表中"全局配置"一列标记为 ×，说明这些属性不可通过 ConfigProvider 的 component config 统一注入默认值，只能逐组件传入。

水平分割线：基础用法与标题

最简用法

不传任何子节点时渲染为一条通栏实线。其容器样式定义于 样式源码：水平方向为 flex 布局、width: 100%、min-width: 100%，四周外边距 margin 使用 marginLG。最简示例参考官方 demo horizontal.tsx：

import { Divider } from 'antd';

const App = () => (
  <>
    <p>段落内容一……</p>
    <Divider />
    <p>段落内容二……</p>
    <Divider dashed />
    <p>段落内容三……</p>
  </>
);

带文字（标题）的水平分割线

当传入 children 时，组件不再渲染单条边框，而是拆成"左轨 + 文本 + 右轨"三段结构（见 index.tsx），标题默认居中显示，且容器采用 align-items: center 配合 whiteSpace: nowrap，样式源码见 style/index.ts。

<Divider>Text</Divider>                       {/* 居中标题 */}
<Divider titlePlacement="start">Left Text</Divider>  {/* 靠左 */}
<Divider titlePlacement="end">Right Text</Divider>    {/* 靠右 */}

通过 titlePlacement 可以控制标题位于分割线起点（start）、终点（end）还是正中（center，默认）。完整示例可参考 with-text.tsx。

从实现层面看，index.tsx 会对 titlePlacement 做一次合并与归一化：left/right 是历史遗留写法，会被按 direction 自动换算——RTL 环境下 left 归一为 end、right 归一为 start，逻辑书写方向（Logical Direction）语义由此保证。

标题样式：plain

带标题的水平分割线默认会应用"小标题"样式：标题字号为 fontSizeLG、字重 500、颜色为 colorTextHeading（见 style/index.ts）。如果希望标题文字采用与正文一致的普通样式（正常字号 fontSize、font-weight: normal、colorText 颜色），传入 plain（自 4.2.0 起支持）：

<Divider plain>Text</Divider>
<Divider titlePlacement="start" plain>Left Text</Divider>
<Divider titlePlacement="end" plain>Right Text</Divider>

对应样式分支见 style/index.ts，完整 demo 见 plain.tsx。

垂直分割线：行内文本/链接的分隔

在表格操作列、导航条中分隔"编辑 | 删除"这类行内元素时，应使用垂直形态。三种写法在效果上等价，官方推荐优先使用 orientation：

Text
<Divider orientation="vertical" />
<a href="#">Link</a>
<Divider vertical />
<a href="#">Link</a>

注意 demo vertical.tsx 中同时出现了 orientation="vertical" 与 vertical 两种写法，而 API 文档明确指出：vertical 与 orientation 同时配置时以 orientation 优先。

从实现看，组件内部通过 useOrientation(orientation, vertical, type) 完成三者的合并（见 index.tsx）。垂直形态的 CSS 也在 style/index.ts：display: inline-block、高度 0.9em、上偏移 -0.06em、vertical-align: middle，并通过 verticalMarginInline token 控制左右间距——这些细节解释了为什么它能和行内文本保持垂直居中对齐。

提示：children 在垂直模式下不生效。组件会在开发环境下给出警告：'children' not working in 'vertical' mode.（见 index.tsx）。

分隔线外观：虚线、点线与实线变体

variant（自 5.20.0 起）取代了仅能表达"虚/实"二态的 dashed，成为控制线条样式的首选，取值为 dashed（虚线）、dotted（点线）、solid（实线，默认）。官方 demo variant.tsx 展示了三种变体配合自定义颜色的写法：

<Divider style={{ borderColor: '#7cb305' }}>Solid</Divider>
<Divider variant="dotted" style={{ borderColor: '#7cb305' }}>Dotted</Divider>
<Divider variant="dashed" style={{ borderColor: '#7cb305' }} dashed>Dashed</Divider>

样式源码中分别对实线、虚线、点线定义了 border 各向规则，并针对"带文字 + dashed/dotted"的场景单独处理左右连接轨（rail）的虚线/点线边框（见 style/index.ts）。

需要特别说明的两点：

1. dashed 与 variant 的关系：dashed 属性相当于 variant="dashed" 的便捷形式。从源码可见 dashed 会追加 -dashed 修饰类，而 variant 非 solid 时会追加 -${variant} 修饰类（见 index.tsx）。官方文案 "Divider text show as plain style" 一类对比示例中两者混用，但新代码建议统一使用 variant。
2. dashed 属性的定位变化：在 variant 引入前它承担"虚线开关"，引入后官方更推荐 variant 表达线型语义；同时从 API 表可见 dashed 仍保留、默认 false。

间距控制：size（5.25.0+）

自 5.25.0 起，Divider 支持通过 size 统一调整水平分割线的垂直外边距，取值 small、medium、large，且仅对水平布局有效：

<Divider size="small" />
<Divider size="medium" />
<Divider size="large" />

对应 demo 见 size.tsx。该属性会接入全局的 ConfigProvider SizeContext——从 index.tsx 看，组件通过 useSize(customSize) 读取合并后的尺寸（未显式传入时继承上下文）。CSS 一侧，small 对应外边距 marginXS、medium/middle 对应 margin（见 style/index.ts 与 index.tsx 的类名映射逻辑），因此它天然与整套间距设计变量对齐，不建议再用内联 margin 覆盖。

已废弃属性的迁移说明

API 表中有两个加删除线的历史属性，引入新代码时应避免使用：

• type：旧的方向属性，请改用 orientation。源码中 useOrientation 的第一参数就是 orientation，type 仅作为兜底参与合并（见 index.tsx）。开发环境下组件会打印 type → orientation 的 deprecated 警告。
• orientationMargin：早期用于调整标题与两侧边界的距离，现已被废弃，官方建议改用 styles.content.margin（见 index.tsx 的告警映射）。代码中仍然保留了纯数字/纯数字字符串自动识别为 px 的处理逻辑（index.tsx），供旧项目平滑升级。

此外还需注意：若给 orientation 传入了 left/right/center 这类"标题位置"取值，开发环境下会提示"orientation is used for direction, please use titlePlacement replace this"（index.tsx），即 orientation 只应承担方向语义。

Semantic DOM 与 classNames/styles（6.0.0）

自 6.0.0 起，Divider 暴露了三层语义化内部结构，使 classNames / styles 可精确命中各层（官方以 SemanticPreview 交互式演示并标注每一层的职责）：

语义节点	对应 DOM	职责说明
root	最外层 <div role="separator">	根容器，承载边框顶部样式与整体分隔线容器基础样式
content	中间的 <span>（带文字时存在）	标题文本内容，行内块显示、内边距等
rail	左右两条连接轨 <div>（无 children 时为根元素本身）	标题两侧的连接线条，边框顶部样式等

其中 content 与 rail 仅在传入 children 时渲染；root 始终存在并带有 role="separator"（无障碍语义，见 index.tsx）。

classNames 与 styles 均支持对象与函数两种形态，函数可拿到 { props } 并据此返回不同结果。官方 demo style-class.tsx 给出完整示例：

import type { DividerProps, GetProp } from 'antd';

// 对象形态
const classNamesObject: DividerProps['classNames'] = {
  root: 'demo-divider-root',
  content: 'demo-divider-content',
  rail: 'demo-divider-rail',
};

// 函数形态：根据 titlePlacement 返回不同 class
const classNamesFn: DividerProps['classNames'] = (info) =>
  info.props.titlePlacement === 'start'
    ? { root: 'demo-divider-root--start' }
    : { root: 'demo-divider-root--default' };

// styles 对象形态
const stylesObject: DividerProps['styles'] = {
  root: { borderWidth: 2, borderStyle: 'dashed' },
  content: { fontStyle: 'italic' },
  rail: { opacity: 0.85 },
};

// styles 函数形态：按 size 区分
const stylesFn: DividerProps['styles'] = (info) =>
  info.props.size === 'small'
    ? { root: { opacity: 0.6 } }
    : { root: { backgroundColor: '#fafafa', borderColor: '#d9d9d9' } };

<Divider classNames={classNamesObject}>classNames Object</Divider>
<Divider titlePlacement="start" classNames={classNamesFn}>classNames Function</Divider>
<Divider styles={stylesObject}>styles Object</Divider>
<Divider size="small" styles={stylesFn}>styles Function</Divider>

在此基础上，开发环境还通过 useMergeSemantic 将组件级与 ConfigProvider 上下文的语义配置合并（index.tsx），保证高阶场景下样式叠加次序一致。

设计 Token 定制

Divider 支持通过主题算法覆盖的组件级 Design Token 共三个（定义见 style/index.ts，默认值见 prepareComponentToken）：

Token	说明	默认值
textPaddingInline	文本（标题）的横向内边距	1em
orientationMargin	文本与边缘的距离占比，取值 0～1（0.05 即标题处两侧留出约 5% 空余）	0.05
verticalMarginInline	垂直分割线的左右外边距	marginXS

其中 orientationMargin 通过 unitless: true 声明为无单位数值（style/index.ts），在 样式计算 中会以 calc(${orientationMargin} * 100%) 的形式决定 start/end 标题两侧 rail 的宽度占比。注意该 Token 与已废弃属性 orientationMargin 同名但语义不同：前者是主题层面"文本距边缘比例"的配置，后者是逐组件控制间距的旧 API，官方已用 styles.content.margin 替代后者。

若需要在 ConfigProvider 中注入自定义 token，示例写法如下（适用于所有 Ant Design v5+ 组件，Divider 组件本身不支持上述 API 表的全局 component config）：

import { ConfigProvider } from 'antd';

<ConfigProvider
  theme={{
    components: {
      Divider: {
        textPaddingInline: '2em',
        orientationMargin: 0.1,
        verticalMarginInline: 16,
      },
    },
  }}
>
  {/* 页面内容 */}
</ConfigProvider>

样式直接定制（debug 场景）

对于纯视觉调优场景（改颜色、改线宽、改高度），官方提供 customize-style.tsx 作为样式自定义参考。核心思路是直接对内联样式/根类打补丁：

<Divider style={{ borderWidth: 2, borderColor: '#7cb305' }} />
<Divider style={{ borderColor: '#7cb305' }} dashed>Text</Divider>
<Divider vertical style={{ height: 60, borderColor: '#7cb305' }} />
<Divider vertical dashed style={{ height: 60, borderColor: '#7cb305' }} />

这种"debug 级"写法适合一次性视觉稿还原；需要长期复用、跟随主题变化的定制，更推荐上文的设计 Token 与 Semantic DOM 方案。组件仓库内配套的 image.test.ts、semantic.test.tsx 与 a11y.test.ts 也从视觉回归、语义结构、无障碍三个维度固化了上述行为，可作为了解组件契约的补充阅读。

小结

• 区块分层用默认水平分割线，或 children + titlePlacement 带标题；
• 行内元素分隔用 orientation="vertical"（避免与 vertical 同时使用产生歧义）；
• 线型选择统一用 variant（solid/dashed/dotted），dashed 保留为兼容写法；
• 统一间距节奏交给 size（5.25.0+）与主题 Token，而不是手写 margin；
• 精细化定制优先走 Semantic DOM 的 classNames/styles（6.0.0+）与组件 Token；写新代码时不要使用 type 与 orientationMargin。

相关实现均位于仓库 components/divider 目录，官方演示代码在 demo 下与组件源码一一对应，可在本地运行 demo 观察每种属性组合的实际渲染效果。