Vant 3 是基于 Vue 3 开发的,在使用 Vant 3 前,请将项目中的 Vue 升级到 3.0 以上版本。
Vant 2 到 Vant 3 存在一些不兼容更新,请仔细阅读下方的不兼容更新内容,并依次处理。
组件命名调整
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>
为了适配 Vue 3 的 v-model API 用法变更,所有提供 v-model 属性的组件在用法上有一定调整。以下弹窗类组件的 v-model 被重命名为 v-model:show:
<!-- Vant 2 -->
<van-popup v-model="show" />
<!-- Vant 3 -->
<van-popup v-model:show="show" />
以下表单型组件 v-model 对应的 prop 重命名为 modelValue,event 重命名为 update:modelValue:
<!-- Vant 2 -->
<van-field :value="value" @input="onInput" />
<!-- Vant 3 -->
<van-field :model-value="value" @update:model-value="onInput" />
在之前的版本中,我们通过 info 属性来展示图标右上角的徽标信息,为了更符合社区的命名习惯,我们将这个属性重命名为 badge,影响以下组件:
同时内部使用的 Info 组件也会重命名为 Badge。
<!-- Vant 2 -->
<van-icon info="5" />
<!-- Vant 3 -->
<van-icon badge="5" />
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>
Vant 2 中默认提供了 $toast、$dialog 等全局方法,但 Vue 3.0 不再支持直接在 Vue 的原型链上挂载方法,因此从 Vant 3.0 开始,使用全局方法前必须先通过 app.use 将组件注册到对应的 app 上。
import { Toast, Dialog, Notify } from 'vant';
// 将 Toast 等组件注册到 app 上
app.use(Toast);
app.use(Dialog);
app.use(Notify);
// app 内的子组件可以直接调用 $toast 等方法
export default {
mounted() {
this.$toast('提示文案');
},
};