企业官网建设流程全解析

Vant 4.0 版本全解析：深色模式、新组件体系与工程化升级指南

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant

本文基于 Vant 官方《4.0 版本介绍》文档，结合当前仓库源码，系统梳理 Vant 4.0 的核心变化：深色模式、五个新组件、安装体积与包体积优化、主色调统一、按需引入方式调整、Picker 重构、工具函数与事件命名调整，以及配套的 Vant Cli 5.0 与升级路径。读完本文，你将完整掌握 Vant 4.0 相比 Vant 3 的破坏性变更清单、新 API 的正确用法，以及从 v3 平滑迁移到 v4 的实操方案。

引言：Vant 的第四个重要版本

历经一年迭代，Vant 4.0 已正式发布，这是 Vant 自 2017 年开源以来发布的第四个重要版本。本次迭代的核心工作包括：支持深色模式、新增五个组件、改善工具函数 API、重构 Picker 等组件，并继续在轻量化和易用性两个方向上做出改进。

从当前仓库的组件目录（packages/vant/src）可以看到，Vant 4 的组件体系由 action-bar、back-top、calendar、picker、picker-group、skeleton 等 60 余个模块构成，其中back-top、date-picker、time-picker、picker-group及skeleton-*系列子组件正是 4.0 新增能力的落点。

支持深色模式

Vant 4.0 支持将全部组件一键切换为深色模式。你只需要把ConfigProvider组件的theme属性设置为dark，即可让页面上的所有 Vant 组件变成深色风格：

<van-config-provider theme="dark"> <!-- child components --> </van-config-provider>

从源码实现看，这一能力由 ConfigProvider.tsx 提供：组件通过makeStringProp<ConfigProviderTheme>('light')声明theme属性，取值类型为'light' | 'dark'，默认light。在setup中，它会在浏览器环境下监听theme变化，动态向document.documentElement添加或移除van-theme-${theme}类名：

const addTheme = () => { document.documentElement.classList.add(`van-theme-${props.theme}`); }; const removeTheme = (theme = props.theme) => { document.documentElement.classList.remove(`van-theme-${theme}`); };

（见 ConfigProvider.tsx）也就是说，深色模式本质上是向根元素注入主题类名，配合样式文件中定义在van-theme-dark作用域下的深色 CSS 变量族生效。文档网站本身同样支持深色模式切换。

关于深色模式下主题变量的精细控制，4.0 还额外提供了themeVarsDark与themeVarsLight两个属性，配合themeVarsScope（'local' | 'global'，默认local）决定样式变量是作用于局部容器还是同步到根节点，详见下文"样式变量类型提示"一节。

几个新组件

Vant 4.0 包含以下新组件：

其中TimePicker 和 DatePicker 由旧版的 DatetimePicker 组件拆分而来，DatetimePicker 组件在 4.0 中不再提供。你可以通过 PickerGroup 来实现"同时选择日期和时间"的交互效果。

以 DatePicker 为例，DatePicker.tsx 在 Picker 之上声明了columnsType（默认['year', 'month', 'day']）、minDate（默认当前年份减 10 年的 1 月 1 日）、maxDate（默认当前年份加 10 年的 12 月 31 日）等属性，内部复用 Picker 渲染滚动列，并通过formatValueRange、getMonthEndDay等工具（见 utils.ts）处理每月的天数边界，避免旧版 DatetimePicker 在跨月、闰年等边界场景下的历史 bug。

同时，Skeleton 从单一组件扩展为骨架屏组件族：skeleton、skeleton-avatar、skeleton-image、skeleton-paragraph、skeleton-title在仓库中均有独立模块（见 packages/vant/src），允许开发者像拼积木一样自由组合骨架屏。

保持轻量

Vant 4.0 的安装体积降低约 30%，包体积保持轻量。随着 npm 生态的发展，node_modules 正在吞噬磁盘空间。为了缓解 node_modules 黑洞、加快安装速度，Vant 对 npm 依赖和构建产物进行了优化。

• 安装体积：相较于 Vant 3.6.2，Vant 4.0.0 的安装体积由 7MB 下降至 5MB。作为对比，社区中主流组件库的安装体积普遍在 15MB ~ 80MB。你可以通过 packagephobia 网站查询 npm 包的安装体积。
• 包体积：本次更新"加量不加价"，Minified + Gzipped 后的体积保持在 70KB 以下。

需要说明的是，以上数据来自 Vant 官方 4.0 发布文档，用于描述 4.0.0 版本发布时的实测结果；具体数值会随版本迭代波动，建议以实际安装测量为准。

统一主色调

Vant 4.0 统一了所有组件的主色调。在之前的版本中，Vant 组件存在两种主色调：部分组件采用蓝色#1989fa，另一部分采用红色#ee0a24。为保持色彩规范的一致性，Vant 4 将所有组件统一为蓝色主色调。

这一点在源码中可以直接验证：css-variables.less 中定义：

--van-primary-color: var(--van-blue);

其中--van-blue: #1989fa（css-variables.less），即所有组件通过--van-primary-color间接引用统一的蓝色，而不再有组件直接引用红色变量作为主色。

统一主色调后，主题定制变得更加容易。例如，你可以覆盖--van-primary-color这个 CSS 变量，将所有组件的主色调设置为绿色：

:root { --van-primary-color: #07c160; }

由于组件样式统一消费该变量，一处覆盖即可全局生效，这正是 Vant 4 全面转向 CSS 变量主题定制体系的基础。

按需引入方式调整

Vant 4.0 不再使用 babel-plugin-import 实现按需引入。早期组件库大多依赖babel-plugin-import做按需引入，这意味着组件库会强依赖 Babel 编译。从 Vant 4.0 开始不再支持babel-plugin-import，主要带来以下收益：

• 不再强依赖 Babel 编译：项目可以使用 SWC、esbuild 等现代编译工具，进而提升编译效率。
• 不再受 import 限制：可以从 Vant 中导入除组件以外的内容，比如 Vant 4 中新增的showToast方法，或是buttonProps对象：

import { showToast, buttonProps } from 'vant';

在包体积方面，移除babel-plugin-import对项目的 JS 体积没有负面影响，因为 Vant 默认支持通过Tree Shaking移除不需要的 JS 代码；而 CSS 代码可以通过 unplugin-vue-components。

需要提醒的是：由于移除了 Babel 插件路径，Vant 4 的源码采用 ES Module 构建并保留sideEffects元数据，使用 Vite / Rollup / Webpack 等支持 Tree Shaking 的构建工具均可正常摇树优化。

样式变量类型提示

Vant 4.0 提供了样式变量的类型提示。Vant 提供了 700 多个样式变量，你可以通过 CSS 代码或ConfigProvider组件修改这些样式变量。在 Vant 4.0 中，新增了ConfigProviderThemeVars类型，为样式变量提供完整的类型提示。

因此，在编写 TypeScript 代码时，你可以通过类型提示自动补全主题变量名称，避免手写字符串拼错。

从源码结构看，types.ts 将ConfigProviderThemeVars定义为BaseThemeVars与 60 余个组件（ActionBar、Button、Calendar、Field、Picker、Popup、Toast、Uploader 等）各自声明的ThemeVars的交集类型。其中BaseThemeVars覆盖了：

• 色板：black、white、gray1~gray8、red、blue、orange、green等；
• 渐变与组件色：gradientRed、primaryColor、successColor、dangerColor、warningColor、textColor系列、background系列；
• 间距、字体、动画、边框、圆角：paddingBase~paddingXl、fontSizeXs~fontSizeLg、durationBase、borderColor、radiusSm~radiusMax等。

而ConfigProvider在运行时会把驼峰形式的变量名转换为--van-*CSS 变量：mapThemeVarsToCSSVars先通过kebabCase转中划线，再用insertDash把gray1之类的名称规范为gray-1，最终生成--van-${formattedKey}形式的 CSS 变量（见 ConfigProvider.tsx）。这就是"TS 类型提示 → CSS 变量注入"的完整链路。

Picker 组件重构

Vant 4.0 重构了 Picker 组件，以及基于 Picker 的 Area 和 DatetimePicker 组件。在之前的版本中，Picker 的 API 设计不够合理，常见问题包括：

• Picker 的columns数据格式不合理，容易产生误解；
• Picker 的数据流不清晰，暴露了过多实例方法用于操作数据；
• DatetimePicker 逻辑过于复杂，经常在边界场景下出现 bug。

为解决上述问题，Vant 4.0 对Picker进行了重构，同时重构了基于 Picker 派生出的Area与DatetimePicker组件。重构后的 Picker 采用更明确的数据流：通过v-model双向绑定选中值，列数据通过columns传入，并配合PickerColumn、PickerToolbar等内部模块实现渲染与确认逻辑（见 packages/vant/src/picker）。

如果你在项目中使用了 Picker、Area 或旧版 DatetimePicker 这三个组件，请阅读「升级指南」完成迁移。

组件工具函数调整

Vant 4.0 调整了组件工具函数的用法，使其更符合直觉。Vant 3 提供了一些组件工具函数，例如调用Dialog()函数可以快速唤起全局弹窗，而Dialog.Component才是 Dialog 对应的组件对象：

// Vant 3 的函数调用 Dialog({ message: 'Hello World!' }); // Vant 3 的组件注册 app.use('van-dialog', Dialog.Component);

以上 API 设计导致 Dialog 等支持工具函数的组件与常规组件存在用法差异，容易被误用；同时也导致unplugin-vue-components无法自动引入 Dialog 等组件。

为了更符合直觉，Vant 4 调整了组件工具函数的调用方式，受影响的函数包括Dialog()、Toast()、Notify()和ImagePreview()。以 Dialog 为例，Dialog()函数被重命名为showDialog()，并让Dialog直接指向组件对象：

// Vant 4 的函数调用 showDialog({ message: 'Hello World!' }); // Vant 4 的组件注册 app.use('van-dialog', Dialog);

从源码可以验证这一调整：在 function-call.tsx 中，showDialog(options)返回Promise<DialogAction | undefined>，内部通过mountComponent挂载 Dialog 实例；Dialog模块则默认导出了组件对象（见 Dialog.tsx）。同时，4.0 还配套提供了setDialogDefaultOptions、resetDialogDefaultOptions、showConfirmDialog、closeDialog等函数，覆盖全局默认配置与关闭等场景（function-call.tsx）。

存量代码兼容方案：@vant/compat

为了便于存量代码迁移至 Vant 4.0，官方提供了兼容包@vant/compat，其中导出的Dialog()函数可完全兼容原有代码：

import { Dialog } from '@vant/compat'; Dialog({ message: 'Hello World!' });

@vant/compat中导出的Dialog()与 Vant 3 中的Dialog()拥有完全一致的 API 和行为。查看 vant-compat/src/dialog.ts 可以看到，它直接将Dialog包装为showDialog的调用别名，并补齐了Dialog.Component、Dialog.alert、Dialog.confirm、Dialog.close、Dialog.setDefaultOptions、Dialog.resetDefaultOptions及Dialog.install等 Vant 3 的全部挂载属性。因此升级时你只需要修改引用路径，其余代码可以保持不变。

@vant/compat同样为 Toast、Notify、ImagePreview 提供了对应兼容实现（见 vant-compat/src/index.ts）。在项目完成升级到 Vant 4.0 后，建议在后续迭代中逐步替换为新的showToast、showDialog、showNotify、showImagePreview等方法，并最终移除@vant/compat依赖。

事件命名调整

Vant 4.0 将事件名改为驼峰格式。从 Vant 4 开始，所有事件均采用 Vue 官方推荐的驼峰格式命名：

// Vant 3 emit('click-input'); // Vant 4 emit('clickInput');

这项改动不影响原有的模板代码，Vue 会自动在模板中对事件名进行格式转换，因此你无须做任何更改：

<!-- 以下代码可以照常运行，无须做任何更改 --> <van-field @click-input="onClick" />

如果你在JSX中使用 Vant 组件，则需要将监听的事件名调整为驼峰格式，原有的中划线格式不再生效——新的监听方式更符合 JSX 本身的规范：

// Vant 3 <Field onClick-input={onClick} /> // Vant 4 <Field onClickInput={onClick} />

移除 Less 变量

Vant 4.0 不再支持通过 Less 变量定制主题。目前 Vant 已经支持基于 CSS 变量的主题定制，相比 Less 定制更加灵活（运行时可变、无需重新编译）。因此，Vant 4 不再提供基于 Less 的主题定制，npm 包中将不再包含.less样式源文件，仅提供编译后的.css样式文件。

如果你正在使用旧版的 Less 主题定制方式，请改用 ConfigProvider 全局配置 进行替换，例如通过themeVars传入驼峰命名的变量对象，或直接覆盖全局 CSS 变量。

Vant Cli 5.0

本次更新同步发布了 Vant Cli 5.0 版本。Vant Cli 是 Vant 底层的组件库构建工具（基于 Vite，负责组件编译、文档站点生成与发布等），本次更新内容包括：

• 升级 Vite 到 3.0 版本，并对相关的 Vite 插件进行升级；
• 不再默认安装stylelint和@vant/stylelint-config依赖，需要的话可以自行安装：

npm add stylelint@13 @vant/stylelint-config

• 不再默认安装gh-pages依赖，请按照如下方式更新 package.json：

- "release:site": "pnpm build:site && gh-pages -d site-dist", + "release:site": "pnpm build:site && npx gh-pages -d site-dist",

这一调整让组件库开发者可以按需选择 lint 与站点发布工具链，进一步降低默认依赖体积。当前仓库中 Vant Cli 的源码与配置位于 packages/vant-cli（含src/compiler、src/commands等模块），可作为自定义组件库构建的参考实现。

版本信息与维护状态

目前 Vant 官网和 npmlatest标签均已指向 Vant 4.0。官方为 Vant 4.0 准备了完整的升级指南，请阅读「从 v3 升级到 v4」 完成升级。

后续 Vant 各个版本的维护状态如下：

升级检查清单

综合全文，从 Vant 3 迁移到 Vant 4 时建议逐项核对以下变更点：

1. 主题定制：将 Less 变量定制迁移到 CSS 变量或ConfigProvider.themeVars；
2. 按需引入：移除babel-plugin-import配置，改用全量引入 + Tree Shaking，CSS 按需引入改用unplugin-vue-components；
3. 工具函数：将Dialog()/Toast()/Notify()/ImagePreview()函数调用替换为showDialog()/showToast()等新 API，或临时改用@vant/compat兼容包；
4. 组件注册：Dialog.Component改为直接注册Dialog组件对象；
5. 事件命名：模板代码无需改动；JSX 代码需将事件名改为驼峰格式（如onClickInput）；
6. 选择器组件：DatetimePicker已移除，按需拆分使用DatePicker+TimePicker+PickerGroup，并核对 Picker / Area 的columns数据格式与数据流 API 变化。

完成以上核对后，即可平滑升级到长期支持的 Vant 4.0，享受深色模式、更轻量的安装体积、统一的主题体系与现代编译工具链带来的开发体验提升。

【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant