Ant Design Divider 带文字分割线完全指南：orientation 与 orientationMargin 的实战用法

Ant Design Divider 带文字分割线完全指南：orientation 与 orientationMargin 的实战用法

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design

本文以 Ant Design（antd）Divider 组件的「带文字分割线」能力为核心，系统讲解orientation（文字位置）、orientationMargin（文字与边缘间距）两大核心参数的用法、底层实现原理与踩坑细节。阅读完本文，你将掌握如何在段落之间插入带标题的水平分割线、将文字对齐到左/中/右三个方向，并能精准控制文字与分割线边缘的距离，同时理解这些能力在源码中的实现机制。

一、功能概述：什么时候需要带文字的分割线

Divider（分割线）用于区隔不同内容。官方文档（组件总览）给出的适用场景是：

• 对不同章节的文本段落进行分割；
• 对行内文字/链接进行分割，例如表格的操作列。

而「带文字的分割线」则是在水平分割线的中间（或两侧）嵌入一段标题文字，常用于文章小标题、表单分组标题、卡片分区块标题等场景。本仓库中的官方演示位于 components/divider/demo/with-text.tsx，其配套说明文档正是 components/divider/demo/with-text.md，核心要点只有一句话：

分割线中带有文字，可以用orientation指定文字位置；设置orientation="left/right"即可对齐到两侧。

orientation共有三个取值：left、right、center，默认值为center（见 API 表格）。

二、最小可运行示例：插入带文字的分割线

把任意 ReactNode 作为 Divider 的children传入，即可在分割线中嵌入文字。官方 demo 的完整代码如下：

import React from 'react'; import { Divider } from 'antd'; const App: React.FC = () => ( <> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista probare, quae sunt a te dicta? Refert tamen, quo modo. </p> <Divider>Text</Divider> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista probare, quae sunt a te dicta? Refert tamen, quo modo. </p> <Divider orientation="left">Left Text</Divider> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista probare, quae sunt a te dicta? Refert tamen, quo modo. </p> <Divider orientation="right">Right Text</Divider> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nonne merninisti licere mihi ista probare, quae sunt a te dicta? Refert tamen, quo modo. </p> </> ); export default App;

运行效果：

• <Divider>Text</Divider>：文字居中，两侧各占 50% 的分割线；
• <Divider orientation="left">Left Text</Divider>：文字靠左，左侧短线、右侧长线；
• <Divider orientation="right">Right Text</Divider>：文字靠右，左侧长线、右侧短线。

从组件源码（components/divider/index.tsx）可以印证：只要children存在，组件就会生成.ant-divider-with-text与.ant-divider-with-text-${orientation}两个组合类名（第 57-58 行），并将文字渲染进<span class="ant-divider-inner-text">中（第 104-108 行）：

const hasChildren = !!children; // ... { [`${prefixCls}-with-text`]: hasChildren, [`${prefixCls}-with-text-${orientation}`]: hasChildren, // ... } // ... {children && type !== 'vertical' && ( <span className={`${prefixCls}-inner-text`} style={innerStyle}> {children} </span> )}

三、orientation：文字位置的三种布局及其样式原理

orientation决定文字在分割线上的位置，类型为'left' | 'right' | 'center'，默认'center'。

其视觉实现的底层逻辑位于样式文件 components/divider/style/index.ts：带文字的横向分割线被设置为display: flex; align-items: center，文字两侧由::before与::after两个伪元素撑起分割线段：

• 居中（默认）：::before与::after各占width: 50%；
• left：::before占calc(0.05 * 100%)（即默认orientationMargintoken），::after占剩余宽度；
• right：::before占剩余宽度，::after占calc(0.05 * 100%)。

对应源码（style/index.ts 第 95-111 行）：

[`&-horizontal${componentCls}-with-text-left`]: { '&::before': { width: `calc(${orientationMargin} * 100%)` }, '&::after': { width: `calc(100% - ${orientationMargin} * 100%)` }, }, [`&-horizontal${componentCls}-with-text-right`]: { '&::before': { width: `calc(100% - ${orientationMargin} * 100%)` }, '&::after': { width: `calc(${orientationMargin} * 100%)` }, },

这里出现的orientationMargin是组件级 Design Token，默认值为0.05（见 style/index.ts 第 198-202 行的prepareComponentToken），它表示文字与最近边缘之间的默认间距比例，与下方要讲的 proporientationMargin相互配合。

四、orientationMargin：精细控制文字与边缘的距离

当orientation为left或right时，可通过orientationMargin显式覆盖默认间距。其类型为string | number，默认值-（不传则使用 token 默认比例）。

官方 demo 中展示了两种传法：

{/* 字符串数字，不带单位时按 px 处理 */} <Divider orientation="left" orientationMargin="0"> Left Text with 0 orientationMargin </Divider> {/* 数字，直接按 px 处理 */} <Divider orientation="right" orientationMargin={50}> Right Text with 50px orientationMargin </Divider>

4.1 数字与字符串的解析规则

组件源码（index.tsx 第 70-78 行）通过useMemo对orientationMargin做了归一化处理：

const memoizedOrientationMargin = React.useMemo<string | number>(() => { if (typeof orientationMargin === 'number') { return orientationMargin; } if (/^\d+$/.test(orientationMargin!)) { return Number(orientationMargin); } return orientationMargin!; }, [orientationMargin]);

规则可总结为：

这一规则被单元测试直接覆盖：components/divider/tests/index.test.tsx 中的support string orientationMargin用例断言<Divider orientation="right" orientationMargin="10">渲染出的.ant-divider-inner-text具备marginRight: 10。

4.2 在组件内部如何生效

只有同时满足「orientation为left/right」且「orientationMargin不为空」时，自定义间距才会生效。源码第 48-49 行：

const hasCustomMarginLeft = orientation === 'left' && orientationMargin != null; const hasCustomMarginRight = orientation === 'right' && orientationMargin != null;

随后：

• 组件会追加-no-default-orientation-margin-left/-no-default-orientation-margin-right类名（index.tsx 第 63-64 行）；
• 内部文字节点上直接写入marginLeft/marginRight行内样式（index.tsx 第 80-83 行）；
• 样式表中，带该类名的::before/::after分别收窄为width: 0与width: 100%，同时给文字补上sizePaddingEdgeHorizontal内边距，避免文字贴边（style/index.ts 第 165-193 行）。

也就是说，orientationMargin的本质是：让文字紧贴某一边，同时通过内边距保证可读性。

五、与 plain、dashed、variant 的搭配

带文字分割线可以与其他 Divider 属性自由组合：

• plain：将标题文字从「标题样式」降级为「普通正文样式」。默认带文字时文字使用colorTextHeading颜色、fontWeight: 500、fontSizeLG字号（style/index.ts 第 76-79 行）；设置plain后切换为colorText、正常字重与正文字号（style/index.ts 第 159-163 行）。相关演示见 components/divider/demo/plain.tsx 与 components/divider/demo/plain.md。
• dashed/variant：variant（5.20.0 起支持）可取dashed、dotted、solid，控制分割线线型；带文字时伪元素同样继承对应线型（style/index.ts 第 126-130、146-150 行）。演示见 components/divider/demo/variant.tsx。
• type="vertical"：垂直分割线不支持 children。源码中会给出警告'children' not working in 'vertical' mode.（index.tsx 第 86-94 行），且渲染逻辑上children && type !== 'vertical'才会渲染文字节点（第 104 行），对应测试用例not show children when vertical验证了.ant-divider-inner-text不会被渲染。

六、Design Token 层面的可定制性

除了 prop，带文字分割线还暴露了组件级 Design Token（见 style/index.ts 第 10-26 行与 API 文档的 主题变量章节）：

这意味着即便不写orientationMarginprop，也可以通过主题配置全局调整文字默认贴边比例。需要更极致的样式定制时，可参考仓库中的 样式自定义演示 与 组件 Token 演示。

七、实用建议与注意事项

1. 默认即居中：不传orientation时文字居中，适合作为章节标题；需要贴边时再显式指定left/right。
2. orientationMargin仅在left/right下生效：居中模式下该参数无意义，源码中也不会为center生成自定义边距逻辑。
3. 单位约定：纯数字字符串（如"10"）会被当作 px 处理，这在测试中已确认；如需百分比或 em 等相对单位，请传入带单位的字符串。
4. 垂直模式不要传 children：垂直分割线用于行内区隔（如表格操作列），文字不会渲染并会触发开发环境警告。
5. 批量定制用 Token：多个页面的分割线文字间距希望统一时，优先通过主题 Token 的orientationMargin（比例值）调整，而不是在每个使用处重复传 prop。

综上，带文字分割线是 Divider 组件中高频实用的能力。掌握orientation与orientationMargin的取值语义、字符串解析规则及其背后的样式实现，你就能在文章中、表单分组里、卡片标题区灵活地构建出结构清晰、间距可控的分割标题，并且在使用、排查问题时直达源码本质。

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design