Vant 4 Divider 分割线组件完全指南:从基础用法到主题定制
Vant 4 Divider 分割线组件完全指南:从基础用法到主题定制
Divider(分割线)是 Vant 4 移动端组件库中用于将内容分隔为多个区域的轻量级组件。本文以 packages/vant/src/divider/README.md 文档为核心,结合组件源码、样式与测试用例,系统讲解其引入方式、全部用法(含 v4.4.0 新增的垂直模式)、API 参数、插槽以及基于 CSS 变量的主题定制方案。阅读完成后,你将能够在 Vant 项目中熟练使用水平/垂直分割线,并掌握通过主题变量深度定制其外观的方法。
组件定位与设计思路
Vant 的分割线组件核心职责非常聚焦:将页面内容视觉分隔为多个区域。它不承载业务逻辑,仅负责渲染一条可定制样式的分隔线,是典型的展示型(Presentational)组件。
从源码结构看,Divider.tsx 的实现极为精简——整个组件仅由一个 div 元素构成,并通过 role="separator" 声明其可访问性语义,配合 createNamespace('divider') 生成 van-divider 的 BEM 类名前缀。组件共暴露 4 个布尔/字符串类型的 props,加上默认插槽即可覆盖全部使用场景:
export const dividerProps = {
dashed: Boolean,
hairline: truthProp,
vertical: Boolean,
contentPosition: makeStringProp<DividerContentPosition>('center'),
};
其中 hairline 使用 Vant 工具函数 truthProp(见 packages/vant/src/utils/props.ts),即 { type: Boolean, default: true },与普通 Boolean 类型的区别在于默认值为 true;contentPosition 则通过 makeStringProp<DividerContentPosition>('center') 声明为字符串类型并默认 'center'。
引入组件
Divider 支持按需引入与全量引入。推荐通过 app.use 进行全局注册:
import { createApp } from 'vue';
import { Divider } from 'vant';
const app = createApp();
app.use(Divider);
注册后即可在模板中使用 <van-divider /> 标签。从 index.ts 可以看到,组件通过 withInstall 包装导出,并声明了 Vue 的全局组件类型 VanDivider,因此在使用 TypeScript 的工程中无需额外类型声明即可获得模板类型提示。更多注册方式(按需引入、unplugin-vue-components 自动导入等)可参考 组件注册指南。
代码演示
基础用法
默认情况下,组件渲染一条水平分割线,直接使用即可:
<van-divider />
从 index.less 的实现可以看到,水平分割线由 div 的 ::before 与 ::after 两个伪元素绘制:容器使用 display: flex; align-items: center,两个伪元素各占 flex: 1,通过 border-width: var(--van-border-width) 0 0 在顶部画出一条 1px 的实线,从而在无文本时构成一条完整的水平线。
展示文本
通过默认插槽,可以在分割线中间插入内容:
<van-divider>文本</van-divider>
组件在渲染时会判断:只有存在 slots.default 且非垂直模式时,才会渲染插槽内容并追加 van-divider--content-* 修饰类(见 Divider.tsx)。样式层面对应地会给两个伪元素设置外边距(margin-right / margin-left: var(--van-divider-content-padding)),让文本与两侧线段自然留白。
内容位置
通过 content-position 属性指定内容在分割线中的位置,可选值为 left、right,默认 center:
<van-divider content-position="left">文本</van-divider>
<van-divider content-position="right">文本</van-divider>
位置效果的实现基于 CSS 变量的组合控制(见 index.less):
--van-divider-content-left-width(默认10%):限制左侧::before伪元素的最大宽度,使文本靠左;--van-divider-content-right-width(默认10%):限制右侧::after伪元素的最大宽度,使文本靠右。
因此在 content-position="left" 时,左侧线段被压缩为 10% 宽度,文本与较长的右侧线段相邻;right 时对称反转。
虚线
添加 dashed 属性使分割线渲染为虚线:
<van-divider dashed>文本</van-divider>
样式实现上,van-divider--dashed 修饰类仅将 border-style 切换为 dashed(index.less),由于伪元素通过 border-style: inherit 继承容器边框样式,整条分割线即呈现虚线效果。注意:在官方演示(demo/index.vue)中虚线示例通常配合 :hairline="false" 使用,使虚线更明显。
自定义样式
可以直接通过 style 属性设置分割线的颜色与内边距:
<van-divider
:style="{ color: '#1989fa', borderColor: '#1989fa', padding: '0 16px' }"
>
文本
</van-divider>
由于容器的 color 控制文本与伪元素颜色(border-color: inherit 使线段跟随 border-color),borderColor 控制线段颜色,padding 控制整体内边距,三者结合即可快速实现品牌色定制,无需编写额外 CSS。
垂直分割线(v4.4.0 起)
自 v4.4.0 起,组件支持垂直模式,适用于同一行内分隔相邻的文本、图标或操作项:
<van-divider vertical />
文本
<van-divider vertical dashed />
文本
<van-divider vertical :hairline="false" />
文本
<van-divider vertical :style="{ borderColor: '#1989fa' }" />
垂直模式下,组件会忽略插槽内容(Divider.tsx 仅 !props.vertical 时渲染 slots.default)。样式上,van-divider--vertical 将容器切换为 display: inline-block,宽度为 var(--van-border-width)、高度 1em(与相邻文本行高一致),并通过 vertical-align: middle 实现与文本基线对齐(index.less);::after 被 display: none 隐藏,仅由 ::before 以左边框形式绘制垂直线;hairline 模式下则对 ::before 施加 scaleX(0.5) 实现 0.5px 细线。
API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| dashed | 是否使用虚线 | boolean | false |
| hairline | 是否使用 0.5px 线 | boolean | true |
| content-position | 内容位置,可选值为 left right |
string | center |
vertical v4.4.0 |
是否使用垂直 | boolean | false |
关于 hairline 需要特别说明:其类型定义位于 Divider.tsx,由 truthProp(默认 true)生成,因此不传该属性时默认启用 0.5px 细线。水平模式下通过 scaleY(0.5) 将 1px 线段纵向压缩为物理 0.5px(index.less),垂直模式下则为 scaleX(0.5),兼顾了移动端高 DPI 屏幕的显示细腻度。
Slots
| 名称 | 说明 |
|---|---|
| default | 内容(仅水平模式渲染) |
类型定义
组件导出以下 TypeScript 类型,便于在开发中约束变量类型:
import type { DividerProps, DividerContentPosition } from 'vant';
其中 DividerContentPosition 在源码中被定义为联合类型:
export type DividerContentPosition = 'left' | 'center' | 'right';
此外 index.ts 还导出了 dividerProps 对象本身,可供需要透传或二次封装组件的场景复用;主题变量类型 DividerThemeVars 定义于 types.ts,为类型安全的主题定制提供支持。
主题定制
CSS 变量
组件提供了下列 CSS 变量用于自定义样式。由于 Vant 的 CSS 变量体系支持运行时切换(如深色模式、品牌换肤),建议优先通过 ConfigProvider 组件 在应用顶层统一配置,而非逐处硬编码样式。
| 名称 | 默认值 | 描述 |
|---|---|---|
--van-divider-margin |
var(--van-padding-md) 0 |
水平分割线外边距 |
--van-divider-vertical-margin |
0 var(--van-padding-xs) |
垂直分割线左右外边距 |
--van-divider-text-color |
var(--van-text-color-2) |
文本颜色 |
--van-divider-font-size |
var(--van-font-size-md) |
文本字号 |
--van-divider-line-height |
24px |
行高 |
--van-divider-border-color |
var(--van-border-color) |
分割线颜色 |
--van-divider-content-padding |
var(--van-padding-md) |
内容与线段间距 |
--van-divider-content-left-width |
10% |
内容靠左时左侧线段宽度 |
--van-divider-content-right-width |
10% |
内容靠右时右侧线段宽度 |
这些变量的默认值定义在 index.less 中,大量复用 Vant 全局设计令牌(如 --van-padding-md、--van-text-color-2、--van-border-color),保证与组件库整体视觉规范一致。需要全局覆盖时,可在根节点或 ConfigProvider 的 theme-vars 中重新声明,例如:
// 通过 ConfigProvider 定制
<van-config-provider :theme-vars="{
dividerTextColor: '#1989fa',
dividerBorderColor: '#1989fa',
dividerContentPadding: '24px',
}">
<van-divider>定制后的分割线</van-divider>
</van-config-provider>
定制效果速查
- 修改线段颜色:覆盖
--van-divider-border-color(容器border-color: inherit机制会同步作用于::before/::after); - 修改文本颜色与字号:覆盖
--van-divider-text-color、--van-divider-font-size; - 调整内容两侧留白:覆盖
--van-divider-content-padding; - 调整靠左/靠右时短侧线段的长度:覆盖
--van-divider-content-left-width/--van-divider-content-right-width; - 调整垂直分割线与相邻内容的间距:覆盖
--van-divider-vertical-margin。
测试与质量保障
组件通过快照测试保证渲染结构与演示示例的一致性。测试文件 demo.spec.ts 调用 snapshotDemo 对 demo/index.vue 的全部演示场景(基础用法、展示文本、内容位置、虚线、自定义样式、垂直)生成快照;demo-ssr.spec.ts 则额外以 SSR 模式运行同一套演示,确保组件在服务端渲染场景下输出稳定。若你修改了组件源码或演示代码,需要同步执行快照更新以通过 CI 校验。
小结
Divider 组件以极小的代码体积提供了完整的水平/垂直分割能力:4 个 props 覆盖虚线、0.5px 细线、内容位置与垂直模式;默认插槽支持在分割线中嵌入任意内容;CSS 变量体系则让分割线的颜色、间距、文本样式都可以在运行时被 ConfigProvider 统一接管。无论是页面区块分隔、表单分组,还是行内操作项间的视觉区隔,<van-divider> 都是 Vant 4 项目中首选的分割线方案。