Vant3 從v2升級(jí)

升級(jí)步驟

1. 升級(jí) Vue 3

Vant 3 是基于 Vue 3 開(kāi)發(fā)的，在使用 Vant 3 前，請(qǐng)將項(xiàng)目中的 Vue 升級(jí)到 3.0 以上版本。

2. 處理不兼容更新

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

不兼容更新

組件命名調(diào)整

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

<!-- 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)整。以下彈窗類(lèi)組件的 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 對(duì)應(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)整

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

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

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

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

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

重命名 get-container 屬性

Vue 3.0 中增加了 Teleport 組件，提供將組件渲染到任意 DOM 位置的能力，Vant 2 也通過(guò) get-container 屬性提供了類(lèi)似的能力。為了與官方的 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ù)不再傳入組件實(shí)例

Button

• 藍(lán)色按鈕對(duì)應(yīng)的類(lèi)型由 info 調(diào)整為 primary
• 綠色按鈕對(duì)應(yīng)的類(lèi)型由 primary 調(diào)整為 success
• native-type 的默認(rèn)值由 submit 調(diào)整為 button

Checkbox

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

Dialog

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

DatetimePicker

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

ImagePreview

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

Picker

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

Popover

• trigger 屬性的默認(rèn)值調(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 屬性不再傳入組件實(shí)例

Toast

• mask 屬性重命名為 overlay

TreeSelect

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

注冊(cè)全局方法

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

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

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

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