Vant

繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

🚀 从 v3 升级到 v4 ​

🌟 介绍 ​

欢迎踏上 Vant 4 的升级之旅！✨ 这不仅仅是一次版本更新，更是一次华丽的蜕变！本文档将作为您的专属导航，带您轻松完成从 Vant 3 到 Vant 4 的完美升级。

📦 安装 Vant 4 ​

让我们从安装开始这场激动人心的升级之旅！首先需要安装 Vant 4 以及我们的贴心小助手 @vant/compat。

@vant/compat 就像一座连接新旧世界的桥梁 🌉，它能帮助您平滑地从 Vant 3 过渡到 Vant 4，让升级过程如丝般顺滑！

bash
# 通过 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 字段中的版本号，修改完成后需要重新安装依赖。

diff
{
  "dependencies": {
-    "vant": "^3.0.0",
+    "vant": "^4.0.0",
+    "@vant/compat": "^1.0.0",
  }
}

🔧 调整按需引入方式 ​

🗑️ 移除 babel-plugin-import ​

告别过去，拥抱未来！🎉 从 Vant 4.0 开始，我们将不再支持 babel-plugin-import，这意味着您可以享受更现代、更高效的开发体验！

只需要在 babel.config.js 中删除以下代码，就能完成这个简单的"断舍离"：

diff
module.exports = {
  plugins: [
-    ['import', {
-      libraryName: 'vant',
-      libraryDirectory: 'es',
-      style: true
-    }, 'vant']
  ]
};

🎁 收益 ​

移除 babel-plugin-import 就像给您的项目装上了涡轮增压器！🚗💨 主要收益包括：

  • 编译效率飞跃：摆脱 Babel 的束缚，拥抱 SWC、esbuild 等现代编译工具，编译速度快如闪电！⚡
  • 导入自由度提升：不再受到 import 限制，可以自由导入 Vant 的各种宝藏，比如全新的 showToast 方法，或是实用的 buttonProps 对象：
ts
import { showToast, buttonProps } from 'vant';

🎨 样式引入方案 ​

别担心！移除 babel-plugin-import 不会让您的 JS 体积变胖，因为 Vant 内置了强大的 Tree Shaking 功能，就像一个智能的"瘦身专家"，自动帮您移除不需要的代码！🌳✂️

对于 CSS 样式，我们为您准备了两种贴心的引入方案：

  • 全量引入：一次性引入所有样式，简单粗暴！💪
js
import 'vant/lib/index.css';

🔄 组件重构 ​

🌟 介绍 ​

Vant 4 带来了三个组件的华丽重生！✨ 它们是我们精心重构的明星组件：

  • Area 🗺️ - 地区选择器
  • Picker 🎛️ - 选择器
  • DatetimePicker 📅 - 时间选择器

🤔 为什么要重构？ ​

这三个组件的重构并非心血来潮，而是为了解决一些长期困扰开发者的痛点：

  • 数据格式混乱：Picker columns 数据格式定义不够清晰，容易让人摸不着头脑 😵
  • 数据流不清晰：暴露了太多实例方法，就像一个杂乱的工具箱，找个工具都费劲 🧰
  • 逻辑过于复杂：DatetimePicker 在边界场景下经常出现意想不到的 bug，让人头疼不已 🤯

🎯 重构目标 ​

为了彻底解决这些问题，我们在 v4 版本中对这三个组件进行了"外科手术式"的重构，让它们变得更加：

  • 简洁易用 📝
  • 逻辑清晰 🧠
  • 稳定可靠 🛡️

如果您的项目中使用了这三个组件，请跟随我们的升级指南，一起体验它们的全新魅力！

🎛️ Picker 组件重构 ​

✨ 主要变更 ​

Picker 组件经过了彻底的重新设计，就像给老爷车换上了全新的引擎！🚗💨

  • 数据绑定升级：支持通过 v-model 绑定当前选中的值，告别繁琐的 default-index 属性 🎯
  • 数据结构优化：重新定义了 columns 属性结构，更加清晰直观 📊
  • 方法精简：移除了复杂的实例方法，仅保留核心的 confirm 方法，简洁就是美！✨
  • 新增实用方法：新增 getSelectedOptions 实例方法，获取选中项更方便 🎁
  • 事件参数优化：调整了 confirm、cancel、change 事件的参数，使用更顺手 🔧
  • 属性命名优化：
    • item-height → option-height 📏
    • visible-item-count → visible-option-num 👀

想了解更多精彩用法？请查看 Picker 组件文档 📖

📅 DatetimePicker 组件重构 ​

DatetimePicker 组件经历了一次"分身术"！🪄 原本的单一组件现在变身为三个专业的子组件：

  • TimePicker ⏰：专注时间选择，包括时、分、秒，时间管理大师！
  • DatePicker 📆：专注日期选择，包括年、月、日，日期选择专家！
  • PickerGroup 🎛️：组合多个 Picker，一次交互完成多个值的选择，团队合作典范！

这三个组件都基于全新的 Picker 组件重构，API 设计更加合理，使用体验更加流畅！

✨ 主要变更 ​

TimePicker 和 DatePicker 的主要变化如下，更多精彩细节请查看对应文档：

  • 数据格式升级：v-model 绑定值调整为数组格式，数据结构更清晰 📊
  • 新增控制属性：新增 columns-type 属性，让您自由控制选项类型和顺序 🎮
  • 精简属性：移除 type 和 columns-order 属性，告别冗余配置 🗑️
  • 方法优化：移除 getPicker 方法，API 更加简洁 ✨
  • 事件统一：调整事件参数，与 Picker 组件保持一致，学习成本更低 🎯

💡 重要提醒：Vant 4 不再提供旧版的 DatetimePicker 组件，但别担心！使用 PickerGroup 组件可以实现更灵活、更丰富的交互效果。详细用法请参考 PickerGroup 组件文档。

🗺️ Area 组件重构 ​

Area 组件作为 Picker 组件的得意门生，也迎来了全面的内部重构！🔧 就像给地图导航系统升级了全新的算法，让地区选择变得更加智能和流畅。

✨ 主要变更 ​

  • 数据绑定现代化：支持通过 v-model 绑定当前选中的值，数据流更清晰 🎯
  • 方法简化：移除 reset 方法，现在通过修改 v-model 就能轻松重置，一步到位！🔄
  • 属性精简：移除 is-oversea-code 属性，告别冗余配置 🗑️
  • 事件统一：调整事件参数，与 Picker 组件保持一致，学习成本更低 📚
  • 属性命名优化：
    • value → modelValue 📝
    • item-height → option-height 📏
    • visible-item-count → visible-option-num 👀

想探索更多地区选择的奥秘？请查看 Area 组件文档 🗺️

API 调整 ​

💬 Dialog 调用方式调整 ​

在 Vant 3 中，Dialog 的设计有点"身份混乱"！🤔 它既是函数又是组件，Dialog() 是函数调用，而 Dialog.Component 才是真正的组件对象。这种设计让很多开发者感到困惑，就像一个人有两个身份证一样！

为了让 API 更加直观易懂，Vant 4 进行了"正名"行动！✨ 我们将 Dialog() 函数重命名为 showDialog()，让 Dialog 直接指向组件对象，身份明确，职责清晰！

js
// Vant 3 - 身份混乱时代 😵
Dialog(); // 函数调用
Dialog.Component; // 组件对象

// Vant 4 - 身份明确时代 ✨
showDialog(); // 函数调用
Dialog; // 组件对象

随着 Dialog 身份的明确，相关方法也进行了重命名，新旧 API 映射关系如下：

js
Dialog(); // -> showDialog() 🎭
Dialog.alert(); // -> showDialog() 🚨
Dialog.confirm(); // -> showConfirmDialog() ✅
Dialog.close(); // -> closeDialog() ❌
Dialog.setDefaultOptions(); // -> setDialogDefaultOptions() ⚙️
Dialog.resetDefaultOptions(); // -> resetDialogDefaultOptions() 🔄

🛡️ 兼容方案 ​

别担心！我们为您准备了贴心的"时光机"！⏰ 为了让旧版本代码能够平滑迁移到 v4，我们提供了 @vant/compat 兼容包，让您的代码能够无缝过渡。

从 @vant/compat 中引用 Dialog 方法：

js
import { Dialog } from '@vant/compat';

Dialog(); // 依然可以这样调用！
Dialog.close(); // 原有方法照常工作！

@vant/compat 中的 Dialog 与 Vant 3 中的 Dialog 拥有完全一致的 API 和行为，就像一个完美的替身演员！🎭 您只需要修改引用路径，其他代码可以保持不变。

💡 升级建议：项目完成升级后，建议在后续迭代中逐步替换为新的 showDialog 等方法，并最终移除 @vant/compat 包，拥抱更现代的 API 设计！

🍞 Toast 调用方式调整 ​

Toast 组件也跟随 Dialog 的脚步，进行了同样的"正名"行动！🎯 让 API 调用更加清晰明了，告别身份混乱的时代。

js
// Vant 3 - 旧时代 📱
Toast(); // 函数调用

// Vant 4 - 新时代 ✨
showToast(); // 函数调用
Toast; // 组件对象

Toast 家族的所有方法都进行了重命名，新旧 API 映射关系如下：

js
Toast(); // -> showToast() 🍞
Toast.fail(); // -> showFailToast() ❌
Toast.success(); // -> showSuccessToast() ✅
Toast.loading(); // -> showLoadingToast() ⏳
Toast.clear(); // -> closeToast() 🧹
Toast.setDefaultOptions(); // -> setToastDefaultOptions() ⚙️
Toast.resetDefaultOptions(); // -> resetToastDefaultOptions() 🔄

重要变化：Vant 4 不再在 this 对象上全局注册 $toast 方法，这意味着您无法通过 this.$toast 来调用 Toast 了。🚫

🛡️ 兼容方案 ​

同样地，我们为 Toast 也准备了贴心的兼容方案！🎁 使用 @vant/compat 中的 Toast 对象来兼容原有代码。

js
import { Toast } from '@vant/compat';

Toast(); // 继续享受熟悉的调用方式！
Toast.clear(); // 原有方法依然可用！

@vant/compat 中的 Toast 与 Vant 3 中的 Toast 拥有完全一致的 API 和行为，您只需要修改引用路径，其他代码可以保持不变。

📢 Notify 调用方式调整 ​

Notify 组件也加入了"正名"大军！🎺 与 Dialog 和 Toast 保持一致的调用方式，让整个 API 体系更加统一和谐。

js
// Vant 3 - 身份混乱时代 📢
Notify(); // 函数调用
Notify.Component; // 组件对象

// Vant 4 - 身份明确时代 ✨
showNotify(); // 函数调用
Notify; // 组件对象

Notify 家族的方法也进行了重命名，新旧 API 映射关系如下：

js
Notify(); // -> showNotify() 📢
Notify.clear(); // -> closeNotify() 🧹
Notify.setDefaultOptions(); // -> setNotifyDefaultOptions() ⚙️
Notify.resetDefaultOptions(); // -> resetNotifyDefaultOptions() 🔄

重要变化：Vant 4 不再在 this 对象上全局注册 $notify 方法，这意味着您无法通过 this.$notify 来调用 Notify 了。🚫

🛡️ 兼容方案 ​

Notify 也有专属的兼容方案！🎁 使用 @vant/compat 中的 Notify 对象来兼容原有代码。

js
import { Notify } from '@vant/compat';

Notify(); // 熟悉的调用方式依然可用！
Notify.clear(); // 原有方法继续工作！

@vant/compat 中的 Notify 与 Vant 3 中的 Notify 拥有完全一致的 API 和行为，您只需要修改引用路径，其他代码可以保持不变。

🖼️ ImagePreview 调用方式调整 ​

ImagePreview 组件也完成了华丽转身！📸 与其他组件保持一致的调用方式，让图片预览功能更加优雅。

js
// Vant 3 - 旧时代 🖼️
ImagePreview(); // 函数调用
ImagePreview.Component; // 组件对象

// Vant 4 - 新时代 ✨
showImagePreview(); // 函数调用
ImagePreview; // 组件对象

🛡️ 兼容方案 ​

ImagePreview 同样提供了贴心的兼容方案！🎁 使用 @vant/compat 中的 ImagePreview 对象来兼容原有代码。

js
import { ImagePreview } from '@vant/compat';

ImagePreview(); // 继续使用熟悉的调用方式！

@vant/compat 中的 ImagePreview 与 Vant 3 中的 ImagePreview 拥有完全一致的 API 和行为，您只需要修改引用路径，其他代码可以保持不变。

🎯 事件命名调整 ​

从 Vant 4 开始，所有事件都穿上了"驼峰装"！🐪 采用 Vue 官方推荐的驼峰格式进行命名，让代码风格更加统一优雅。

js
// Vant 3 - 中划线时代 ➖
emit('click-input');

// Vant 4 - 驼峰时代 🐪
emit('clickInput');

好消息：这项改动不影响原有的模板代码！✨ Vue 会自动在模板中对事件名进行格式转换，您的现有代码无须做任何更改。

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

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

jsx
// Vant 3 - 旧格式 📱
<Field onClick-input={onClick} />

// Vant 4 - 新格式 ✨
<Field onClickInput={onClick} />

🔧 其他 API 调整 ​

在 Vant 4.0 版本中，以下组件也进行了精心的优化调整：

📍 AddressEdit ​

地址编辑组件迎来了几项重要调整：

  • 移除冗余属性：移除 show-postal 和 postal-validator 属性，简化配置 🗑️
  • 事件参数优化：change-area 事件的参数调整为 PickerOption[] 类型，类型更明确 📊
  • 方法清理：移除未在文档中标注的 getArea 实例方法，API 更纯净 ✨

🎭 Popup ​

Popup 组件的 CSS 样式进行了精心调整，如果您在 Popup 组件上添加了自定义 CSS 样式，请确认本次升级是否对项目中的 UI 产生影响。

  • 盒模型优化：默认添加了 box-sizing: border-box 样式，布局更可控 📦
  • 居中方式改进：调整了 position="center" 时的水平居中方式，解决弹窗宽度无法正确自适应的问题 🎯
less
// Vant 3 - 旧的居中方式 📱
.van-popup--center {
  left: 50%;
  transform: translate3d(-50%, -50%, 0);
}

// Vant 4 - 新的居中方式 ✨
.van-popup--center {
  left: 0;
  right: 0;
  width: fit-content;
  max-width: calc(100vw - var(--van-padding-md) * 2);
  margin: 0 auto;
  transform: translateY(-50%);
}

📑 Tabs ​

  • 事件精简：移除了 click 和 disabled 事件，请使用 click-tab 事件代替，事件命名更清晰 🎯

🎨 样式调整 ​

🌈 主色调统一 ​

在之前的版本中，Vant 组件就像一个"双重人格"的设计师！🎭 部分组件采用蓝色（#1989fa）作为主色调，另一部分则采用红色（#ee0a24），这种不一致让整体视觉体验有些分裂。

为了让 Vant 拥有更加统一和谐的"颜值"，我们在 Vant 4 中进行了"色彩大统一"行动！🎯 所有组件均采用蓝色作为主色调，让整个组件库呈现出一致的视觉风格。

以下组件的主色调由红色华丽转身为蓝色：

  • AddressEdit 📍 - 地址编辑更清新
  • AddressList 📋 - 地址列表更统一
  • Card 🃏 - 卡片组件更和谐
  • Calendar 📅 - 日历界面更舒适
  • Cascader 🌊 - 级联选择更优雅
  • ContactList 👥 - 联系人列表更现代
  • ContactEdit ✏️ - 联系人编辑更美观
  • CouponList 🎫 - 优惠券列表更吸引
  • Dialog 💬 - 对话框更友好
  • DropdownMenu 📋 - 下拉菜单更清晰
  • IndexBar 🔤 - 索引栏更简洁
  • Sidebar 📱 - 侧边栏更统一
  • Steps 👣 - 步骤条更连贯
  • Tabs 📑 - 标签页更协调
  • TreeSelect 🌳 - 树形选择更自然

🗑️ 移除 Less 变量 ​

在 Vant 3 中，我们就像一个"贪心"的管家，同时提供了 Less 变量和 CSS 变量两种主题定制方式。🏠

在 Vant 4 中，我们进行了"断舍离"，移除了 Less 变量，仅保留 CSS 变量。这个决定就像整理房间一样，虽然有些不舍，但带来的好处是显而易见的：

  • 体积瘦身 📦：减少了代码包体积，让你的应用更轻盈
  • 构建友好 ⚡：对构建工具更友好，无需配置 less-loader，告别繁琐配置
  • 动态灵活 🎨：样式变量可以在运行时进行动态修改，实现真正的主题切换

如果您在项目中使用了 Vant 的 Less 变量，别担心！请参考 ConfigProvider 全局配置 来进行平滑迁移。这就像搬家一样，虽然地址变了，但家的温暖依然在！🏡

✂️ 简化 CSS 变量名 ​

考虑到 代码体积 和 使用便捷性，我们对部分 CSS 变量的名称进行了"瘦身计划"，就像给变量名做了一次精简的"发型设计"！✨ 在变量名中使用了更简短的单词，以减小代码体积。

本次升级涉及以下变量名变更：

less
animation-duration               ->  duration
animation-timing-function-enter  ->  ease-out
animation-timing-function-leave  ->  ease-in
background-color                 ->  background
background-color-light           ->  background-2
border-radius                    ->  radius
border-width-base                ->  border-width
box-shadow                       ->  shadow
font-family                      ->  font
font-weight-bold                 ->  font-bold
price-integer-font               ->  price-font
text-link                        ->  link
transition-duration              ->  duration

由于涉及的 CSS 变量较多，建议在代码仓库中进行全局匹配和替换，就像整理房间一样，一次性完成所有的更新！🏠

对于 ConfigProvider 组件，我们新增了 ConfigProviderThemeVars 类型定义，提供完整的类型提示。在 TypeScript 代码中，您可以通过类型提示来确保主题变量被正确替换，就像有了智能助手一样贴心！🤖

ts
import type { ConfigProviderThemeVars } from 'vant';

const themeVars: ConfigProviderThemeVars = {
  sliderBarHeight: '4px',
};

📚 相关文档 ​

快速开始 ​

核心组件文档 ​

反馈组件 ​

开发工具 ​

版本信息 ​

基於Vant構建的企業級移動端解決方案

Copyright © 2025 siex.cn ｜ sitemap