This document provides an upgrade guide from Vant 2 to Vant 3.
\nVant 3 is developed based on Vue 3. Before using Vant 3, please upgrade the Vue in the project to version 3.0 or above.
\nThere are some incompatible changes from Vant 2 to Vant 3, please read the incompatible changes below carefully and deal with them in order.
\nThe GoodsAction component is renamed to ActionBar.
\n<!-- Vant 2 -->\n<van-goods-action>\n <van-goods-action-icon text="icon" />\n <van-goods-action-button text="button" />\n</van-goods-action>\n\n<!-- Vant 3 -->\n<van-action-bar>\n <van-action-bar-icon text="icon" />\n <van-action-bar-button text="button" />\n</van-action-bar>\nVant v3 removed the SwitchCell component, you can use the Cell and Switch components instead.
\n<!-- Vant 2 -->\n<van-switch-cell title="title" v-model="checked" />\n\n<!-- Vant 3 -->\n<van-cell center title="title">\n <template #right-icon>\n <van-switch v-model="checked" size="24" />\n </template>\n</van-cell>\nIn order to adapt to Vue 3\'s v-model API usage changes, all components that provide v-model have some adjustments in usage. v-model for the following popup components has been renamed to v-model:show:
<!-- Vant 2 -->\n<van-popup v-model="show" />\n\n<!-- Vant 3 -->\n<van-popup v-model:show="show" />\nThe prop corresponding to the following form component v-model is renamed to modelValue, and the event is renamed to update:modelValue:
-Checkbox
\n<!-- Vant 2 -->\n<van-field :value="value" @input="onInput" />\n\n<!-- Vant 3 -->\n<van-field :model-value="value" @update:model-value="onInput" />\nv-model renamed to v-model:currentRatev-model renamed to v-model:codev-model renamed to v-model:loading, error.sync renamed to v-model:errorv-model renamed to v-model:activeactive-id.sync renamed to v-model:active-idmain-active-index.sync renamed to v-model:main-active-indexIn the previous version, we used the info prop to display the badge in the upper right corner of the icon. In order to better meet the naming habits of the community, we renamed this prop to badge, which affects the following components:
At the same time, the Info component will also be renamed to Badge.
\n<!-- Vant 2 -->\n<van-icon info="5" />\n\n<!-- Vant 3 -->\n<van-icon badge="5" />\nVue 3.0 added a new Teleport component, which provides the ability to render the component to any DOM position, and Vant 2 also provides similar capabilities through the get-container prop. For consistency with the official API, the get-container prop in Vant 3 will be renamed to teleport.
<!-- Vant 2 -->\n<template>\n <van-popup get-container="body" />\n <van-popup :get-container="getContainer" />\n</template>\n<script>\n export default {\n methods: {\n getContainer() {\n return document.querySelector('#container');\n },\n },\n };\n</script>\n\n<!-- Vant 3 -->\n<template>\n <van-popup teleport="body" />\n <van-popup :teleport="container" />\n</template>\n<script>\n export default {\n beforeCreate() {\n this.container = document.querySelector('#container');\n },\n };\n</script>\nchange event parameter is no longer passed to the component instanceinfo to primaryprimary to successnative-type changed from submit to button@click.stop to prevent event bubblingallow-html prop is disabled by default.before-close prop usage adjustment, no longer pass in the done function, but return Promise to control.change event parameter is no longer passed to the component instanceasync-close prop, you can use the new before-close prop instead.change event parameter is no longer passed to the component instance.allow-html prop is turned off by default.show-toolbar prop is enabled by default.confirm and change events will contain a complete option object.trigger prop adjusted to click.async-change prop is renamed to before-change, and the usage method is adjusted.detail parameter of open event renamed to name.on-close prop renamed to before-close, and parameter structure adjusted.before-close prop is no longer passed to the component instance.mask prop renamed to overlay.navclick event renamed to click-nav.itemclick event renamed to click-item.Global methods such as $toast and $dialog are provided by default in Vant 2, but Vue 3.0 no longer supports directly mounting methods on Vue\'s prototype chain, so starting from Vant 3.0, you must first pass app.use registers the component to the corresponding app.
import { Toast, Dialog, Notify } from 'vant';\n\n// Register components such as Toast to the app\napp.use(Toast);\napp.use(Dialog);\napp.use(Notify);\n\n// Subcomponents in the app can directly call methods such as $toast\nexport default {\n mounted() {\n this.$toast('prompt text');\n },\n};\n