🚀 从 v2 升级到 v3
🎯 介绍
欢迎来到 Vant 3 的世界！🎉 本文档将带您踏上从 Vant 2 到 Vant 3 的升级之旅。就像给您的项目换上了全新的引擎，让它跑得更快、更稳、更强！
🛠️ 升级步骤
1. 🔄 升级 Vue 3
首先，我们需要为您的项目装上 Vue 3 这个强劲的新引擎！Vant 3 是专为 Vue 3 量身定制的，就像钥匙配锁一样完美契合。在开始 Vant 3 的精彩旅程前，请确保您的项目已经升级到 Vue 3.0 以上版本。
2. 🔧 处理不兼容更新
升级路上难免会遇到一些"路障"，但别担心！我们已经为您准备了详细的"通关攻略"。请仔细阅读下方的不兼容更新内容，按照指引逐一处理，很快就能让您的项目焕然一新！
⚠️ 不兼容更新
🏷️ 组件命名调整
好消息！我们给组件起了更贴切的名字！GoodsAction 商品导航组件华丽变身为 ActionBar 行动栏 ✨ —— 名字更简洁，功能更强大！
<!-- Vant 2 -->
<van-goods-action>
<van-goods-action-icon text="图标" />
<van-goods-action-button text="按钮" />
</van-goods-action>
<!-- Vant 3 -->
<van-action-bar>
<van-action-bar-icon text="图标" />
<van-action-bar-button text="按钮" />
</van-action-bar>🗑️ 废弃组件
告别冗余，拥抱简洁！我们移除了 SwitchCell 组件，但这不是结束，而是新的开始！您可以用 Cell 和 Switch 组件的完美组合来实现同样的效果，就像乐高积木一样灵活自由！🧩
<!-- Vant 2 -->
<van-switch-cell title="标题" v-model="checked" />
<!-- Vant 3 -->
<van-cell center title="标题">
<template #right-icon>
<van-switch v-model="checked" size="24" />
</template>
</van-cell>🎭 弹窗型组件 v-model 变更
Vue 3 带来了全新的 v-model API，就像给数据绑定装上了涡轮增压器！🚗💨 为了与这个强大的新特性完美配合，我们的弹窗组件也进行了优雅的升级。以下弹窗类组件的 v-model 华丽转身为 v-model:show：
- ActionSheet
- Calendar
- Dialog
- ImagePreview
- Notify
- Popover
- Popup
- ShareSheet
<!-- Vant 2 -->
<van-popup v-model="show" />
<!-- Vant 3 -->
<van-popup v-model:show="show" />📝 表单型组件 v-model 内部值变更
表单组件也迎来了内在美的提升！✨ 为了与 Vue 3 的设计理念保持一致，以下表单型组件的内部机制进行了优雅的重构。prop 从 value 升级为 modelValue，event 从 input 进化为 update:modelValue：
- Checkbox
- CheckboxGroup
- DatetimePicker
- DropdownItem
- Field
- Radio
- RadioGroup
- Search
- Stepper
- Switch
- Sidebar
- Uploader
<!-- Vant 2 -->
<van-field :value="value" @input="onInput" />
<!-- Vant 3 -->
<van-field :model-value="value" @update:model-value="onInput" />🔄 其他 v-model 调整
每个组件都有自己的专属升级方案，就像量身定制的西装一样合身！👔
- Circle:
v-model→v-model:currentRate🔄 - CouponList:
v-model→v-model:code🎫 - List:
v-model→v-model:loading，error.sync→v-model:error📋 - Tabs:
v-model→v-model:active📑 - TreeSelect:
active-id.sync→v-model:active-id🌳 - TreeSelect:
main-active-index.sync→v-model:main-active-index🌲
🏷️ 徽标属性命名调整
小红点也要与时俱进！🔴 我们将 info 属性优雅地重命名为 badge，这个名字更加直观易懂，就像给小红点换了个更时尚的名字。以下组件都受到了这个贴心的改进：
- Tab
- Icon
- GridItem
- TreeSelect
- TabbarItem
- SidebarItem
- GoodsActionIcon
同时内部使用的 Info 组件也会重命名为 Badge。
<!-- Vant 2 -->
<van-icon info="5" />
<!-- Vant 3 -->
<van-icon badge="5" />🚀 重命名 get-container 属性
Vue 3.0 带来了超酷的 Teleport 组件，就像给组件装上了传送门！🌀 它能让组件瞬间移动到任意 DOM 位置。为了与 Vue 3 的官方 API 完美融合，我们将 get-container 属性华丽升级为 teleport，让您的组件也能享受"瞬间移动"的超能力！
<!-- Vant 2 -->
<template>
<van-popup get-container="body" />
<van-popup :get-container="getContainer" />
</template>
<script>
export default {
methods: {
getContainer() {
return document.querySelector('#container');
},
},
};
</script>
<!-- Vant 3 -->
<template>
<van-popup teleport="body" />
<van-popup :teleport="container" />
</template>
<script>
export default {
beforeCreate() {
this.container = document.querySelector('#container');
},
};
</script>🔧 API 调整
每个组件都经过了精心的调优，就像给爱车做保养一样细致入微！🚗✨
🗺️ Area
change事件更加纯净，不再传入组件实例，让事件处理更加专注！
🔘 Button
- 颜色语义更加清晰：蓝色按钮从
info升级为primary💙 - 绿色按钮从
primary进化为success💚 native-type默认值从submit调整为button，更加安全可控！
☑️ Checkbox
- 在 Cell 内使用时，记得添加
@click.stop来阻止事件冒泡，让点击更加精准！🎯
💬 Dialog
- 默认关闭
allow-html属性，安全第一！🛡️ before-close属性华丽升级，使用 Promise 控制，异步处理更优雅！
📅 DatetimePicker
change事件同样变得更加纯净，专注于数据本身！
🖼️ ImagePreview
- 告别
async-close，拥抱全新的before-close属性，功能更强大！
🎛️ Picker
change事件参数优化，更加简洁明了- 默认关闭
allow-html属性，安全升级！🔒 - 默认开启
show-toolbar属性，用户体验更佳！ - 级联选择返回完整选项对象，数据更丰富！📊
💭 Popover
trigger属性默认值调整为click，点击触发更符合用户习惯！👆
🔢 Stepper
async-change华丽变身为before-change，异步控制更加优雅！
📱 SwipeCell
open事件的detail参数重命名为name，语义更清晰on-close升级为before-close，参数结构更合理before-close不再传入组件实例，保持简洁！
🍞 Toast
mask属性重命名为overlay，与其他组件保持一致！
🌳 TreeSelect
- 事件命名更加规范：
navclick→click-nav🧭itemclick→click-item📋
🌍 注册全局方法
Vue 3.0 带来了更加安全的架构设计！🛡️ 虽然不再支持直接在原型链上挂载方法，但这让我们的应用更加健壮。现在使用 $toast、$dialog 等全局方法前，需要先通过 app.use 进行注册，就像给组件办理"入住手续"一样简单！
import { Toast, Dialog, Notify } from 'vant';
// 将 Toast 等组件注册到 app 上
app.use(Toast);
app.use(Dialog);
app.use(Notify);
// app 内的子组件可以直接调用 $toast 等方法
export default {
mounted() {
this.$toast('提示文案');
},
};📚 相关文档
🔄 迁移指南
- 从 Vant 3 迁移 - 继续您的升级之旅
- 快速上手 - 开始使用 Vant 4
- 进阶用法 - 深入了解高级特性
🏗️ 开发指南
- 主题定制 - 打造专属视觉风格
- 国际化 - 多语言支持
- ConfigProvider 全局配置 - 统一配置管理
🧩 核心组件
- Button 按钮 - 基础交互组件
- Cell 单元格 - 列表展示组件
- Form 表单 - 数据收集组件
- Dialog 弹出框 - 消息确认组件