从 v2 升级

升级步骤

1. 升级 Vue 3

Vant 3 是基于 Vue 3 开发的，在使用 Vant 3 前，请将项目中的 Vue 升级到 3.0 以上版本。

2. 处理不兼容更新

Vant 2 到 Vant 3 存在一些不兼容更新，请仔细阅读下方的不兼容更新内容，并依次处理。

组件命名调整

GoodsAction 商品导航组件重命名为 ActionBar 行动栏。

  2. <van-switch-cell title="标题" v-model="checked" />
  4. <!-- Vant 3 -->
  5. <van-cell center title="标题">
  6.   <template #right-icon>
  7.     <van-switch v-model="checked" size="24" />
  8.   </template>
  9. </van-cell>

弹窗型组件 v-model 变更

为了适配 Vue 3 的 v-model API 用法变更，所有提供 v-model 属性的组件在用法上有一定调整。以下弹窗类组件的 v-model 被重命名为 v-model:show：

  • ActionSheet
  • Calendar
  • Dialog
  • ImagePreview
  • Notify
  • Popup
  • ShareSheet

表单型组件 v-model 内部值变更

以下表单型组件 v-model 对应的 prop 重命名为 modelValue，event 重命名为 update:modelValue：

  • Checkbox
  • CheckboxGroup
  • DatetimePicker
  • DropdownItem
  • Field
  • Radio
  • RadioGroup
  • Search
  • Stepper
  • Switch
  • Sidebar
  • Uploader
  1. <!-- Vant 2 -->
  2. <van-field :value="value" @input="onInput" />
  4. <!-- Vant 3 -->
  5. <van-field :model-value="value" @update:model-value="onInput" />
  • 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

重命名 get-container 属性

Vue 3.0 中增加了 Teleport 组件，提供将组件渲染到任意 DOM 位置的能力，Vant 2.x 也通过 属性提供了类似的能力。为了与官方的 API 保持一致，Vant 中的 get-container 属性将重命名为 teleport。

  1. <!-- Vant 2 -->
  2. <template>
  3.   <van-popup get-container="body" />
  4.   <van-popup :get-container="getContainer" />
  5. </template>
  6. <script>
  7.   export default {
  8.       getContainer() {
  9.         return document.querySelector('#container');
  10.       },
  11.     },
  12.   };
  13. </script>
  15. <!-- Vant 3 -->
  16. <template>
  17.   <van-popup teleport="body" />
  18.   <van-popup :teleport="container" />
  19. </template>
  20. <script>
  21.   export default {
  22.     beforeCreate() {
  23.       this.container = document.querySelector('#container');
  24.     },
  25.   };
  26. </script>

Area

  • change 事件参数不再传入组件实例

Button

  • 蓝色按钮对应的类型由 info 调整为 primary
  • 绿色按钮对应的类型由 调整为 success
  • native-type 的默认值由 submit 调整为 button

Checkbox

  • 在 Cell 内部使用时，现在需要手动添加 @click.stop 来阻止事件冒泡

Dialog

  • 默认关闭 allow-html 属性
  • before-close 属性用法调整，不再传入 done 函数，而是通过返回 Promise 来控制

DatetimePicker

  • change 事件参数不再传入组件实例

ImagePreview

  • 移除 async-close 属性，可以使用新增的 before-close 属性代替

Picker

  • change 事件参数不再传入组件实例
  • 默认关闭 allow-html 属性
  • 默认开启 show-toolbar 属性
  • 级联选择下，confirm、change 事件返回的回调参数将包含为完整的选项对象。

Popover

  • trigger 属性的默认值调整为 click

SwipeCell

  • open 事件的 detail 参数重命名为 name
  • on-close 属性重命名为 before-close，并调整参数结构
  • before-close 属性不再传入组件实例

Toast

  • mask 属性重命名为 overlay

TreeSelect

  • navclick 事件重命名为 click-nav
  • itemclick 事件重命名为 click-item

注册全局方法

Vant 2.x 中默认提供了 $toast、$dialog 等全局方法，但 Vue 3.0 不再支持直接在 Vue 的原型链上挂载方法，因此从 Vant 3.0 开始，使用全局方法前必须先通过 app.use 将组件注册到对应的 app 上。