Vant 3 升级到 Vant 4 的完整步骤安装、按需引入调整与组件重构【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant如果你的 Vue 3 项目还在使用 Vant 3而需要升级到 Vant 4那么本文的操作路径是把依赖版本换成vant^4并安装兼容包vant/compat移除babel-plugin-import并按 Vant 4 的方式引入样式然后按新 API 重构Picker、Area、DatetimePicker三个组件的用法。Vant 3 已终止支持不再接受 PRVant 4 处于长期支持状态见 4.0 版本介绍 中的版本信息表所以这条迁移路径有明确的收益。完整依据来自官方升级指南 从 v3 升级到 v4。安装 Vant 4 与兼容包 vant/compatvant/compat是官方提供的兼容包用于让 Vant 3 风格的Dialog()、Toast()、Notify()、ImagePreview()函数调用在 Vant 4 中继续工作。升级时两个包需要一起安装# 通过 npm 安装 npm add vant^4 vant/compat^1 # 通过 yarn 安装 yarn add vant^4 vant/compat^1 # 通过 pnpm 安装 pnpm add vant^4 vant/compat^1 # 通过 Bun 安装 bun add vant^4 vant/compat^1也可以直接修改package.json的dependencies字段改完后重新安装依赖{ dependencies: { - vant: ^3.0.0, vant: ^4.0.0, vant/compat: ^1.0.0, } }用兼容包过渡旧的工具函数调用Vant 4 中Dialog、Toast、Notify、ImagePreview的函数调用方式都做了调整如Dialog()变为showDialog()且不再在this上全局注册$toast、$notify。存量代码不必一次改完只需要把引用路径换成vant/compat其余代码保持不变import { Dialog } from vant/compat; Dialog(); Dialog.close();vant/compat中导出的Dialog、Toast、Notify、ImagePreview与 Vant 3 中的同名对象拥有完全一致的 API 和行为参见 vant/compat。官方建议项目完成升级到 Vant 4 后在后续迭代中逐步替换为新的showDialog等方法并最终移除vant/compat包。调整按需引入方式移除 babel-plugin-import从 Vant 4.0 开始不再支持babel-plugin-import需要删除babel.config.js中的对应插件配置module.exports { plugins: [ - [import, { - libraryName: vant, - libraryDirectory: es, - style: true - }, vant] ] };移除它对 JS 体积没有影响因为 Vant 默认支持 Tree Shaking 来移除不需要的 JS 代码。变化主要在 CSS 的引入方式上二选一方式一全量引入样式文件推荐业务对 CSS 体积要求不极致时import vant/lib/index.css;方式二按需引入组件样式配合unplugin-vue-components与 Vant 官方解析器vant/auto-import-resolver详细配置见 快速上手# 通过 npm 安装 npm i vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D以 Vite 项目为例在vite.config.js中配置import vue from vitejs/plugin-vue; import AutoImport from unplugin-auto-import/vite; import Components from unplugin-vue-components/vite; import { VantResolver } from vant/auto-import-resolver; export default { plugins: [ vue(), AutoImport({ resolvers: [VantResolver()], }), Components({ resolvers: [VantResolver()], }), ], };配置完成后可以直接在模板里写van-button typeprimary /插件会自动注册组件并引入对应样式showToast等 API 由unplugin-auto-import自动导入。注意两点不要同时使用「全量引入」和「按需引入」两种方式否则会导致代码重复、样式错乱当unplugin-vue-components版本 0.26.0 时webpack、vue-cli、rspack 项目需要用Components.default注册插件。另外移除babel-plugin-import后不再受 import 写法限制可以从vant导入组件以外的内容import { showToast, buttonProps } from vant;重构 Picker、Area、DatetimePicker 组件Vant 4 中完全重构了三个组件Picker、Area、DatetimePicker。原因是旧版Picker的 columns 数据格式易误解、暴露了过多操作内部数据的实例方法DatetimePicker逻辑过于复杂且在边界场景下经常出现 bug。如果你的项目用到了这三个组件需要按下述变更逐一调整。Picker 的主要变更支持通过v-model绑定当前选中的值移除default-index属性重新定义了columns属性的结构移除了操作内部数据的实例方法仅保留confirm方法新增getSelectedOptions实例方法调整了confirm、cancel、change事件的参数重命名item-height属性为option-height重命名visible-item-count属性为visible-option-num详细用法参见 Picker 组件文档。新版示例中columns是{ text, value }数组确认事件通过selectedValues/selectedOptions取值const columns [ { text: Delaware, value: Delaware }, { text: Florida, value: Florida }, ]; const onConfirm ({ selectedValues }) { showToast(Value: ${selectedValues.join(,)}); };DatetimePicker 拆分为三个组件Vant 4 不再提供旧版的DatetimePicker组件它被拆分为TimePicker用于时间选择包括时、分、秒。DatePicker用于日期选择包括年、月、日。PickerGroup用于结合多个 Picker 选择器组件在一次交互中完成多个值的选择。TimePicker 和 DatePicker 基于新版 Picker 重构主要 API 变化v-model绑定的值调整为数组格式新增columns-type属性用于控制选项类型和顺序移除type属性和columns-order属性移除getPicker方法调整confirm、cancel、change事件的参数与 Picker 组件保持一致需要日期 时间一次选完的场景用PickerGroup把DatePicker和TimePicker放在一起即可。PickerGroup会渲染统一工具栏title、confirm、cancel等工具栏相关的属性和事件要设置在PickerGroup上van-picker-group titleTitle :tabs[Date, Time] confirmonConfirm cancelonCancel van-date-picker v-modelcurrentDate :min-dateminDate :max-datemaxDate / van-time-picker v-modelcurrentTime / /van-picker-groupconst currentDate ref([2022, 06, 01]); const currentTime ref([12, 00]);Area 的主要变更Area基于Picker封装本次一并重构完整用法见 Area 组件文档支持通过v-model绑定当前选中的值移除reset方法现在可以通过修改v-model来进行重置移除is-oversea-code属性调整confirm、cancel、change事件的参数与 Picker 组件保持一致重命名value属性为modelValue重命名item-height属性为option-height重命名visible-item-count属性为visible-option-num升级后需要检查的破坏性改动除上述三组件外以下改动同样来自 从 v3 升级到 v4在升级后逐一检查事件命名改为驼峰格式emit(click-input)变为emit(clickInput)。模板代码不受影响Vue 会自动转换事件名van-field click-inputonClick /可照常运行但如果项目使用 JSX监听事件名必须改为驼峰格式如Field onClickInput{onClick} /中划线写法不再生效。AddressEdit移除show-postal、postal-validator属性change-area事件参数调整为PickerOption[]类型移除未在文档中标注的getArea实例方法。Popup CSS 调整默认添加了box-sizing: border-boxpositioncenter时的水平居中方式由left: 50% translate3d改为left: 0; right: 0; width: fit-content; margin: 0 auto。如果给 Popup 写过自定义 CSS需要确认这次升级是否对 UI 产生影响。主色调统一为蓝色#1989faCard、Calendar、Tabs、Dialog 等原红色#ee0a24主色调的组件统一改为蓝色视觉回归时重点关注这些组件。不再提供 Less 变量定制npm 包中不再包含.less源文件只提供编译后的.css。如果项目在用 Less 主题定制改用 ConfigProvider 全局配置替换。CSS 变量名简化如animation-duration→duration、border-radius→radius、background-color→background等完整对照表见升级指南。建议在代码仓库中对旧变量名做全局匹配和替换TypeScript 项目可以用新增的ConfigProviderThemeVars类型获得变量名的类型提示import type { ConfigProviderThemeVars } from vant; const themeVars: ConfigProviderThemeVars { sliderBarHeight: 4px, };验证与收尾文档给出的判断点集中在编译和 UI 两处移除babel-plugin-import后项目可以脱离 Babel 强依赖可使用 SWC、esbuild 等编译工具并且import { showToast } from vant这类非组件导入应当可以正常编译运行UI 层面重点回归 Popup 相关自定义样式和主色调由红变蓝的组件。完成升级、项目稳定运行后收尾动作按官方建议执行在迭代中逐步把vant/compat中的Dialog()、Toast()等旧调用替换为showDialog()、showToast()等新 API确认没有引用后再从依赖中移除vant/compat包。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考