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

原创2026-09-12 12:16:151,764 阅读
文章标签:前端UI组件移动开发

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 项目中首选的分割线方案。

登录后查看全文
vant