antd Divider 分割线组件完全指南：从基础用法到主题定制

antd Divider 分割线组件完全指南从基础用法到主题定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读Divider是 Ant Designantd组件库中用于内容视觉分隔的基础布局组件在Layout布局分组中扮演着组织界面信息层级的关键角色。本文以 components/divider/index.en-US.md 官方文档为核心骨架结合 组件实现源码、样式生成逻辑 与 单元测试系统讲解 Divider 的水平/垂直分割、带标题分割、线条样式变体、标题方位控制等全部 API以及基于 Design Token 的主题定制方法帮助你在一篇文章内掌握该组件的完整使用与深度定制能力。When To Use什么时候使用 Divider官方文档给出了两个最典型的使用场景分割文章段落sections当一篇文章或内容块需要划分为不同章节时使用水平分割线让读者在视觉上明确感知内容的边界。分割行内文本与链接例如表格操作列中编辑 / 删除 / 更多等相邻操作项之间用垂直分割线进行区隔避免视觉拥挤。示例 A段落间水平分割┌──────────────────────────────┐│ 第一段正文内容 │├──────────────────────────────┤│ 第二段正文内容 │└──────────────────────────────┘示例 B表格操作列行内分割编辑 │ 删除 │ 更多前者对应水平分割线typehorizontal后者对应垂直分割线typevertical。两条线分别对应 horizontal.tsx 与 vertical.tsx 两个官方示例。快速上手五种基础用法示例官方文档通过 7 个 Demo 展示了 Divider 的能力其中 5 个为基础用法另有 2 个debug标记的调试示例仅用于验证定制能力1. 水平分割线Horizontal最基础的用法直接渲染Divider /即可在内容块之间插入一条横线。配合dashed属性可输出虚线import React from react; import { Divider } from antd; const App: React.FC () ( pLorem ipsum dolor sit amet, consectetur adipiscing elit. .../p Divider / pLorem ipsum dolor sit amet, consectetur adipiscing elit. .../p Divider dashed / pLorem ipsum dolor sit amet, consectetur adipiscing elit. .../p / ); export default App;完整代码见 components/divider/demo/horizontal.tsx。2. 带标题的分割线Divider with title在分割线中间嵌入文字标题通过orientation控制标题位置left/right/center默认centerDividerText/Divider {/* 居中标题 */} Divider orientationleftLeft Text/Divider {/* 标题靠左 */} Divider orientationrightRight Text/Divider {/* 标题靠右 */}完整代码见 components/divider/demo/with-text.tsx。3. 无标题样式文本Text without heading style通过plain属性默认true自 4.2.0 起支持可以让标题文本不再使用标题样式即取消加粗与大字号视觉上更接近普通正文Divider plainText/Divider Divider orientationleft plainLeft Text/Divider Divider orientationright plainRight Text/Divider完整代码见 components/divider/demo/plain.tsx。4. 垂直分割线Verticaltypevertical让 Divider 变成行内元素适合分隔文本、链接等行内内容Text Divider typevertical / a href#Link/a Divider typevertical / a href#Link/a完整代码见 components/divider/demo/vertical.tsx。注意从源码 index.tsx 可以看到vertical模式下 children 不生效。开发环境下组件会通过devUseWarning输出children not working in vertical mode.的警告测试用例 index.test.tsx 也验证了typevertical时不会渲染.ant-divider-inner-text元素。5. 线条样式变体Variant自5.20.0起新增variant属性支持dashed | dotted | solid三种线条样式默认solid。它比布尔型的dashed表达能力更强Divider style{{ borderColor: #7cb305 }}Solid/Divider Divider variantdotted style{{ borderColor: #7cb305 }}Dotted/Divider Divider variantdashed style{{ borderColor: #7cb305 }} dashedDashed/Divider完整代码见 components/divider/demo/variant.tsx。在 样式实现 中-dashed与-dotted分别设置borderStyle: dashed与borderStyle: dotted并且对水平带文本与垂直两种形态都做了伪元素::before/::after的边框样式适配。测试用例 index.test.tsx 验证了variantdotted时元素会获得borderStyle: dotted样式。完整 API 参考官方文档 API 表定义了以下全部属性通用属性可参考 Common propsPropertyDescriptionTypeDefaultVersionchildrenThe wrapped titleReactNode-classNameThe className of containerstring-dashedWhether line is dashedbooleanfalsevariantWhether line is dashed, dotted or soliddashed|dotted|solidsolid5.20.0orientationThe position of title inside dividerleft|right|centercenterorientationMarginThe margin-left/right between the title and its closest border, while theorientationmust beleftorright, If a numeric value of typestringis provided without a unit, it is assumed to be in pixels (px) by default.string | number-plainDivider text show as plain stylebooleantrue4.2.0styleThe style object of containerCSSProperties-typeThe direction type of dividerhorizontal|verticalhorizontal与源码中的 DividerProps 接口 对照组件还额外接收prefixCls与rootClassName二者未出现在文档表中但类型定义与实现均支持。API 属性逐一深度解读children —— 分割线内嵌标题传入 ReactNode 后组件会渲染ant-divider-inner-text内层 span 包裹标题。从 源码 看只有children存在且type ! vertical时才会渲染该 span。type —— 方向类型horizontal默认块级横线display: flex、width: 100%、clear: both垂直方向外边距由 token 控制详见下文 Design Token 一节vertical行内竖线样式定义见 style/index.tsdisplay: inline-block、height: 0.9em、top: -0.06em、vertical-align: middle从而与相邻文本基线对齐。dashed / variant —— 虚线样式dashed布尔开关为true时附加ant-divider-dashed类variant三值枚举从源码看默认值为solid且仅在variant ! solid时附加${prefixCls}-${variant}类index.tsx。注意二者可同时使用demo 中variantdashed dashed同时出现效果一致。orientation —— 标题方位left | right | center默认center。当有 children 时会附加ant-divider-with-text-left/right/center类。样式上标题两侧的::before与::after伪元素按比例分配 50% 宽度style/index.ts实现分割线从两侧延伸的效果。orientationMargin —— 标题与边缘的间距仅在orientation为left或right时生效控制标题与最近一侧边框之间的 margin。特别地当传入不带单位的数字字符串如10时默认按像素px处理。其内部处理逻辑位于 index.tsx数字类型直接返回纯数字字符串/^\d$/匹配会被Number()转为数字再写入marginLeft/marginRight内联样式。测试用例 index.test.tsx 验证了orientationMargin10会得到marginRight: 10。官方 demo 中还有两个典型用法Divider orientationleft orientationMargin0Left Text with 0 orientationMargin/Divider Divider orientationright orientationMargin{50}Right Text with 50px orientationMargin/Divider当显式传入orientationMargin时组件会附加ant-divider-no-default-orientation-margin-left/right类index.tsx样式层面对应::before宽度归零、::after占满 100%同时给文本补上sizePaddingEdgeHorizontal的paddingInlineStart/Endstyle/index.ts从而精确控制标题与边缘距离。plain —— 纯文本样式plain默认true时标题不再套用标题样式样式层面对应color: token.colorText、fontWeight: normal、fontSize: token.fontSizestyle/index.ts即与普通正文同字号、不加粗。style / className —— 样式定制入口style直接作用到容器 div 上源码中与 ConfigProvider 注入的divider?.style合并见 index.tsxclassName追加到容器类名末尾rootClassName同理二者均被合并进最终 classString。样式定制Style Customization由于 Divider 的线条本质是 CSS borderborderBlockStart可以直接通过style覆盖边框宽度与颜色来实现样式定制。官方 customize-style.tsx 给出了完整示例Divider style{{ borderWidth: 2, borderColor: #7cb305 }} / Divider style{{ borderColor: #7cb305 }} dashed / Divider style{{ borderColor: #7cb305 }} dashedText/Divider Divider typevertical style{{ height: 60, borderColor: #7cb305 }} / Divider typevertical style{{ height: 60, borderColor: #7cb305 }} dashed / {/* 用 flex 容器 orientation 组合实现自定义布局 */} div style{{ display: flex, flexDirection: column, height: 50, boxShadow: 0 0 1px red }} Divider style{{ background: rgba(0,255,0,0.05) }} orientationleftText/Divider /div可覆盖的维度包括borderWidth线条粗细、borderColor线条颜色、height垂直分割线高度、background标题文本底色等。这是 Divider 最直接的定制手段无需引入主题体系。基于 Design Token 的主题定制Divider 深度接入 antd v5 的 CSS-in-JS 主题体系通过ConfigProvider的theme.components.Divider可以整体定制组件外观。官方 component-token.tsx 示例import { ConfigProvider, Divider } from antd; const App: React.FC () ( ConfigProvider theme{{ token: { margin: 24, // 影响带文本分割线垂直间距 marginLG: 48, // 影响普通分割线垂直间距 lineWidth: 5, // 线条粗细默认 1px colorSplit: #1677ff, // 分割线颜色默认主题色灰 }, components: { Divider: { verticalMarginInline: 16, // 垂直分割线横向外边距 textPaddingInline: 16, // 文本横向内边距 orientationMargin: 0.2, // 文本与边缘距离比例0 ~ 1 }, }, }} pLorem ipsum dolor sit amet .../p DividerText/Divider Divider orientationleftLeft Text/Divider Divider orientationrightRight Text/Divider Divider orientationleft orientationMargin0Left Text with 0 orientationMargin/Divider Divider orientationright orientationMargin{50}Right Text with 50px orientationMargin/Divider /ConfigProvider );Divider 组件级 Token 一览从 style/index.ts 的ComponentToken接口与prepareComponentToken第 198-202 行可知Divider 共提供 3 个组件级 TokenToken说明默认值textPaddingInline文本横向内边距Horizontal padding of text1emorientationMargin文本与边缘距离取值为 0 ~ 1Distance between text and edge, number between 0 and 10.05verticalMarginInline垂直分割线的横向外间距Horizontal margin of vertical Dividertoken.marginXS其中orientationMargin被声明为unitlessstyle/index.ts意味着它不带单位、作为比例系数参与calc(${orientationMargin} * 100%)的宽度计算style/index.ts用于分配标题左右两侧分割线伪元素的宽度占比。全局 Token 的联动效果从 genSharedDividerStyle 的 token 解构可以看到Divider 还依赖以下全局 TokenlineWidth控制分割线粗细borderBlockStart/borderInlineStart的宽度默认 1pxcolorSplit分割线颜色默认取全局分割色margin带文本分割线的垂直外边距dividerHorizontalWithTextGutterMarginstyle/index.tsmarginLG普通水平分割线的垂直外边距dividerHorizontalGutterMargincolorTextHeading/fontSizeLG/fontWeight带文本分割线的标题颜色、字号fontSizeLG与字重500colorText/fontSizeplain模式下文本的常规样式sizePaddingEdgeHorizontal显式指定orientationMargin时文本的边缘内边距内部合并为0。常见问题与最佳实践1. 垂直分割线与文本基线对齐typevertical时组件通过top: -0.06em、vertical-align: middle、height: 0.9em的组合实现与行内文本的中线对齐。若在 flex 布局中使用可能需配合自身style微调height与alignSelf。2. 不要给垂直分割线传 children源码会在开发环境输出children not working in vertical mode.警告且 children 会被忽略index.tsx。若确需竖线 文字的组合请用style自行定制或改用其他布局方案。3. 标题边缘间距的两种指定方式传orientationMargin数字/无单位数字字符串按 px 处理完全接管边缘间距不传orientationMargin时使用组件 TokenorientationMargin0 ~ 1 比例控制标题距边缘的距离比例。4. 线条样式的优先级与兼容variant5.20.0是更完整的线条样式方案dashed作为历史布尔 API 继续可用。二者同时传入时以各自生成的类叠加生效最终边框样式由 CSS 中后声明的规则决定。5. 表格操作列行内分隔推荐组合使用typevertical与plain无关的轻量写法a编辑/aDivider typevertical /a删除/a与 vertical.tsx 示例保持一致。深入阅读组件入口与类型定义components/divider/index.tsx样式与 Token 生成逻辑components/divider/style/index.ts全部官方 Demohorizontal / with-text / plain / vertical / customize-style / component-token / variant位于 components/divider/demo单元测试覆盖 vertical 隐藏 children、字符串 orientationMargin、dashed 与 variant 样式components/divider/tests/index.test.tsx官方文档中/英components/divider/index.zh-CN.md / components/divider/index.en-US.md通用组件属性说明components/_util如 type.ts 中的类型工具【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考