Vant4 從 v2 升級到 v3

介紹

本文檔提供了從 Vant 2 到 Vant 3 的升級指南。

升級步驟

1. 升級 Vue 3

Vant 3 是基于 Vue 3 開發(fā)的，在使用 Vant 3 前，請將項目中的 Vue 升級到 3.0 以上版本。

2. 處理不兼容更新

Vant 2 到 Vant 3 存在一些不兼容更新，請仔細閱讀下方的不兼容更新內(nèi)容，并依次處理。

不兼容更新

組件命名調(diào)整

GoodsAction 商品導(dǎo)航組件重命名為 ActionBar 行動欄。

<!-- Vant 2 -->
<van-goods-action>
  <van-goods-action-icon text="圖標(biāo)" />
  <van-goods-action-button text="按鈕" />
</van-goods-action>

<!-- Vant 3 -->
<van-action-bar>
  <van-action-bar-icon text="圖標(biāo)" />
  <van-action-bar-button text="按鈕" />
</van-action-bar>

廢棄組件

移除 SwitchCell 組件，可以直接使用 Cell 和 Switch 組件代替。

<!-- Vant 2 -->
<van-switch-cell title="標(biāo)題" v-model="checked" />

<!-- Vant 3 -->
<van-cell center title="標(biāo)題">
  <template #right-icon>
    <van-switch v-model="checked" size="24" />
  </template>
</van-cell>

彈窗型組件 v-model 變更

為了適配 Vue 3 的 v-model API 用法變更，所有提供 v-model 屬性的組件在用法上有一定調(diào)整。以下彈窗類組件的 ?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 內(nèi)部值變更

以下表單型組件 v-model 對應(yīng)的 prop 重命名為 ?modelValue?，event 重命名為 ?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 調(diào)整

• 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?

徽標(biāo)屬性命名調(diào)整

在之前的版本中，我們通過 info 屬性來展示圖標(biāo)右上角的徽標(biāo)信息，為了更符合社區(qū)的命名習(xí)慣，我們將這個屬性重命名為 badge，影響以下組件：

• Tab
• Icon
• GridItem
• TreeSelect
• TabbarItem
• SidebarItem
• GoodsActionIcon

同時內(nèi)部使用的 Info 組件也會重命名為 Badge。

<!-- Vant 2 -->
<van-icon info="5" />

<!-- Vant 3 -->
<van-icon badge="5" />

重命名 get-container 屬性

Vue 3.0 中增加了 ?Teleport? 組件，提供將組件渲染到任意 DOM 位置的能力，Vant 2 也通過 ?get-container? 屬性提供了類似的能力。為了與官方的 API 保持一致，Vant 中的 ?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 調(diào)整

Area

• ?change? 事件參數(shù)不再傳入組件實例

Button

• 藍色按鈕對應(yīng)的類型由 ?info? 調(diào)整為 ?primary?
• 綠色按鈕對應(yīng)的類型由 ?primary? 調(diào)整為 ?success?
• ?native-type? 的默認值由 ?submit? 調(diào)整為 ?button?

Checkbox

• 在 Cell 內(nèi)部使用時，現(xiàn)在需要手動添加 ?@click.stop? 來阻止事件冒泡

Dialog

• 默認關(guān)閉 ?allow-html? 屬性
• ?before-close? 屬性用法調(diào)整，不再傳入 done 函數(shù)，而是通過返回 Promise 來控制

DatetimePicker

• ?change? 事件參數(shù)不再傳入組件實例

ImagePreview

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

Picker

• ?change? 事件參數(shù)不再傳入組件實例
• 默認關(guān)閉 ?allow-html? 屬性
• 默認開啟 ?show-toolbar? 屬性
• 級聯(lián)選擇下，?confirm?、?change? 事件返回的回調(diào)參數(shù)將包含為完整的選項對象。

Popover

• ?trigger? 屬性的默認值調(diào)整為 ?click?

Stepper

• ?async-change? 屬性重命名為 ?before-change?，并調(diào)整使用方法

SwipeCell

• ?open? 事件的 ?detail? 參數(shù)重命名為 ?name?
• ?on-close? 屬性重命名為 ?before-close?，并調(diào)整參數(shù)結(jié)構(gòu)
• ?before-close? 屬性不再傳入組件實例

Toast

• ?mask? 屬性重命名為 ?overlay?

TreeSelect

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

注冊全局方法

Vant 2 中默認提供了 ?$toast?、?$dialog? 等全局方法，但 Vue 3.0 不再支持直接在 Vue 的原型鏈上掛載方法，因此從 Vant 3.0 開始，使用全局方法前必須先通過 ?app.use? 將組件注冊到對應(yīng)的 app 上。

import { Toast, Dialog, Notify } from 'vant';

// 將 Toast 等組件注冊到 app 上
app.use(Toast);
app.use(Dialog);
app.use(Notify);

// app 內(nèi)的子組件可以直接調(diào)用 $toast 等方法
export default {
  mounted() {
    this.$toast('提示文案');
  },
};