🚀 v2からv3へのアップグレード
🎯 紹介
Vant 3の世界へようこそ！🎉 このドキュメントは、Vant 2からVant 3へのアップグレードの旅をご案内します。プロジェクトにまったく新しいエンジンを搭載するようなもので、より速く、より安定し、より強力に動作するようになります！
🛠️ アップグレード手順
1. 🔄 Vue 3へのアップグレード
まず、プロジェクトにVue 3という強力な新しいエンジンを搭載する必要があります！Vant 3はVue 3のために特別に設計されており、鍵と鍵穴のように完璧にフィットします。Vant 3の素晴らしい旅を始める前に、プロジェクトがVue 3.0以上のバージョンにアップグレードされていることを確認してください。
2. 🔧 非互換アップデートの処理
アップグレードの道のりでは「障害物」に遭遇する可能性がありますが、心配しないでください！詳細な「クリアガイド」を用意しました。以下の非互換アップデートの内容を注意深く読み、ガイドに従って1つずつ処理すれば、すぐにプロジェクトを新鮮な状態にすることができます！
⚠️ 非互換アップデート
🏷️ コンポーネント命名の調整
良い知らせです！より適切な名前をコンポーネントに付けました！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>🎭 ポップアップ型コンポーネント v-model 変更
Vue 3はまったく新しいv-model APIをもたらし、データバインディングにターボチャージャーを搭載したようなものです！🚗💨 この強力な新機能と完璧に連携するために、私たちのポップアップコンポーネントも優雅にアップグレードされました。以下のポップアップ型コンポーネントの 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 変更
フォーム系コンポーネントは Vue 3 に合わせて内部仕様を再設計しました。prop は value から modelValue に、イベントは input から 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 調整
各コンポーネント固有の調整があります：
- 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
内部で使用している Info コンポーネントも Badge にリネームされます。
<!-- Vant 2 -->
<van-icon info="5" />
<!-- Vant 3 -->
<van-icon badge="5" />🚀 get-container のリネーム
Vue 3 の Teleport に合わせ、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 調整
各コンポーネントの API が整理されています：
🗺️ Area
changeイベントはインスタンスを渡さず、純粋なデータに集中します
🔘 Button
- 色の意味付けを明確化：青は
info→primary、緑はprimary→success native-typeのデフォルトをsubmit→buttonに変更
☑️ Checkbox
- Cell 内で使用する場合は
@click.stopを付与してバブリングを抑制
💬 Dialog
allow-htmlをデフォルトで無効化before-closeを Promise ベースに刷新
📅 DatetimePicker
changeは純粋なデータ変更イベントに
🖼️ ImagePreview
async-closeを廃止しbefore-closeを導入
🎛️ Picker
changeイベントの引数を簡潔化allow-htmlをデフォルト無効化show-toolbarをデフォルト有効化- カスケード選択は完全なオプションオブジェクトを返却
💭 Popover
triggerのデフォルトをclickに変更
🔢 Stepper
async-change→before-change
📱 SwipeCell
openのdetailをnameに変更on-close→before-closebefore-closeでインスタンスを渡さない
🍞 Toast
mask→overlay
🌳 TreeSelect
- イベント名の規範化：
navclick→click-navitemclick→click-item
🌍 グローバルメソッドの登録
Vue 3 ではプロトタイプへの直接登録は推奨されません。$toast・$dialog などを使用する前に app.use で登録します。
import { Toast, Dialog, Notify } from 'vant';
// Toast などを app に登録
app.use(Toast);
app.use(Dialog);
app.use(Notify);
// 子コンポーネントは `$toast` などを利用可能
export default {
mounted() {
this.$toast('メッセージ');
},
};