🚀 v3 から v4 への移行

🌟 概要

Vant 4 へのアップグレードへようこそ！✨ これは単なるバージョン更新ではなく、アーキテクチャと体験の進化です。本ドキュメントは v3 から v4 への移行ガイドとして、スムーズなアップグレードを支援します。

📦 Vant 4 のインストール

まずは Vant 4 と互換パッケージ @vant/compat をインストールします。

@vant/compat は v3 と v4 を橋渡しする互換レイヤー 🌉 で、段階的な移行をサポートします。

bash

# npm
npm add vant@^4 @vant/compat@^1

# yarn
yarn add vant@^4 @vant/compat@^1

# pnpm
pnpm add vant@^4 @vant/compat@^1

# Bun
bun add vant@^4 @vant/compat@^1

package.json の dependencies を直接更新してから依存関係を再インストールする方法でも構いません。

diff

{
  "dependencies": {
-    "vant": "^3.0.0",
+    "vant": "^4.0.0",
+    "@vant/compat": "^1.0.0",
  }
}

🔧 按需導入の調整

🗑️ babel-plugin-import の廃止

Vant 4.0 からは babel-plugin-import をサポートしません。よりモダンで高速なビルドツールへの移行を推奨します。

babel.config.js から下記設定を削除してください：

diff

module.exports = {
  plugins: [
-    ['import', {
-      libraryName: 'vant',
-      libraryDirectory: 'es',
-      style: true
-    }, 'vant']
  ]
};

🎁 メリット

babel-plugin-import を外すことで得られる主なメリット：

ビルド高速化：SWC・esbuild などのモダンツールの活用で高速化 ⚡
インポートの自由度：関数や props を自由にインポート可能。例えば showToast や buttonProps：

import { showToast, buttonProps } from 'vant';

🎨 スタイルの導入方法

Vant は強力な Tree Shaking に対応しており、JS のサイズ増加は発生しません。

CSS の導入は以下のいずれかを選択します：

全量導入：ライブラリの全スタイルを一括で読み込み 💪

import 'vant/lib/index.css';

按需導入：unplugin-vue-components を利用して必要なスタイルのみを読み込み。詳細はクイックスタートを参照。

🔄 コンポーネントの再設計

🌟 概要

Vant 4 では以下 3 コンポーネントを再設計しました：

Area 🗺️ - 地域選択
Picker 🎛️ - オプション選択
DatetimePicker 📅 - 日時選択

🤔 再設計の目的

長年の課題を解決し、データ構造と API を整理するためです：

データ形式が曖昧：columns の定義が不明瞭 😵
データフローが複雑：インスタンスメソッドが過剰 🧰
境界ケースで不安定：DatetimePicker が複雑でバグを誘発 🤯

🎯 目標

v4 では以下を重視して再設計しました：

簡潔で使いやすい 📝
ロジックが明確 🧠
安定で信頼性が高い 🛡️

該当コンポーネントを使用している場合は、以下の移行ガイドに従ってください。

🎛️ Picker の再設計

✨ 主な変更点

Picker は内部設計を全面的に見直しました。

データバインディング：v-model による選択値のバインドをサポート 🎯
データ構造：columns を再定義し、より明確に 📊
メソッド整理：インスタンスメソッドを整理し、confirm を中心に簡潔化 ✨
ユーティリティの追加：getSelectedOptions を追加 🎁
イベントパラメータ：confirm・cancel・change の引数を調整 🔧
プロパティ名の調整：
- item-height → option-height 📏
- visible-item-count → visible-option-num 👀

詳細は Picker ドキュメントを参照してください 📖

📅 DatetimePicker の再設計

DatetimePicker は 3 つの専門コンポーネントに分割されました：

TimePicker ⏰：時間（時・分・秒）に特化
DatePicker 📆：日付（年・月・日）に特化
PickerGroup 🎛️：複数 Picker の組み合わせにより一括選択

いずれも新しい Picker を基盤としており、API と体験が向上しています。

✨ 主な変更点

TimePicker / DatePicker の主な変更は以下の通りです：

データ形式：v-model 値を配列形式へ 📊
制御属性：columns-type を追加し並びを制御 🎮
属性整理：type・columns-order を削除 🗑️
メソッド整理：getPicker を削除 ✨
イベント統一：Picker と統一されたイベント引数 🎯

💡 重要：v4 では旧 DatetimePicker は提供されません。代わりに PickerGroup を使用してください。詳細は PickerGroup ドキュメントを参照。

🗺️ Area の再設計

Area も内部構造を刷新し、選択体験を向上しました。

✨ 主な変更点

v-model によるバインド：選択値を双方向バインド 🎯
メソッド簡素化：reset を削除し、v-model の更新でリセット 🔄
属性整理：is-oversea-code を削除 🗑️
イベント統一：Picker と統一 📚
命名調整：
- value → modelValue
- item-height → option-height
- visible-item-count → visible-option-num

詳細は Area ドキュメントを参照 🗺️

API の調整

💬 Dialog の呼び出し方法の変更

v3 では Dialog が関数兼コンポーネントという設計でした。

v4 では Dialog() を showDialog() に改名し、Dialog はコンポーネントオブジェクトを指します。

// Vant 3
Dialog(); // 関数呼び出し
Dialog.Component; // コンポーネントオブジェクト

// Vant 4
showDialog(); // 関数呼び出し
Dialog; // コンポーネントオブジェクト

関連メソッドの新旧対応は以下の通り：

Dialog(); // -> showDialog() 🎭
Dialog.alert(); // -> showDialog() 🚨
Dialog.confirm(); // -> showConfirmDialog() ✅
Dialog.close(); // -> closeDialog() ❌
Dialog.setDefaultOptions(); // -> setDialogDefaultOptions() ⚙️
Dialog.resetDefaultOptions(); // -> resetDialogDefaultOptions() 🔄

🛡️ 互換策

段階的移行のために @vant/compat を提供しています。

@vant/compat から Dialog をインポート：

import { Dialog } from '@vant/compat';

Dialog();
Dialog.close();

@vant/compat の Dialog は v3 と同一 API・挙動です。参照パスのみ変更すれば他のコードはそのままで利用できます。

💡 移行完了後は新 API（showDialog 等）へ段階的に置換し、最終的に @vant/compat を削除することを推奨します。

🍞 Toast の呼び出し方法の変更

Toast も同様に関数名を整理しました。

// Vant 3
Toast(); // 関数呼び出し

// Vant 4
showToast(); // 関数呼び出し
Toast; // コンポーネントオブジェクト

Toast の新旧対応は以下の通り：

Toast(); // -> showToast() 🍞
Toast.fail(); // -> showFailToast() ❌
Toast.success(); // -> showSuccessToast() ✅
Toast.loading(); // -> showLoadingToast() ⏳
Toast.clear(); // -> closeToast() 🧹
Toast.setDefaultOptions(); // -> setToastDefaultOptions() ⚙️
Toast.resetDefaultOptions(); // -> resetToastDefaultOptions() 🔄

重要：v4 では this.$toast のグローバル登録はありません。

🛡️ 互換策

Toast についても @vant/compat の Toast で互換利用が可能です。

import { Toast } from '@vant/compat';

Toast();
Toast.clear();

@vant/compat の Toast は v3 と同一 API・挙動です。

📢 Notify の呼び出し方法の変更

Notify も同様に整理されました。

// Vant 3
Notify(); // 関数呼び出し
Notify.Component; // コンポーネントオブジェクト

// Vant 4
showNotify(); // 関数呼び出し
Notify; // コンポーネントオブジェクト

Notify の新旧対応は以下の通り：

Notify(); // -> showNotify() 📢
Notify.clear(); // -> closeNotify() 🧹
Notify.setDefaultOptions(); // -> setNotifyDefaultOptions() ⚙️
Notify.resetDefaultOptions(); // -> resetNotifyDefaultOptions() 🔄

重要：v4 では this.$notify のグローバル登録はありません。

🛡️ 互換策

@vant/compat の Notify で互換利用が可能です。

import { Notify } from '@vant/compat';

Notify();
Notify.clear();

@vant/compat の Notify は v3 と同一 API・挙動です。

🖼️ ImagePreview の呼び出し方法の変更

ImagePreview も同様に整理されました。

// Vant 3
ImagePreview(); // 関数呼び出し
ImagePreview.Component; // コンポーネントオブジェクト

// Vant 4
showImagePreview(); // 関数呼び出し
ImagePreview; // コンポーネントオブジェクト

🛡️ 互換策

@vant/compat の ImagePreview で互換利用が可能です。

import { ImagePreview } from '@vant/compat';

ImagePreview();

@vant/compat の ImagePreview は v3 と同一 API・挙動です。

🎯 イベント名の調整

v4 からは Vue 推奨の camelCase 命名を採用します。

// Vant 3（kebab-case）
emit('click-input');

// Vant 4（camelCase）
emit('clickInput');

テンプレート内のイベント名は自動的に変換されるため、既存のテンプレートコードの変更は不要です。

html

<!-- 以下のコードはそのまま動作します。変更は不要です。 -->
<van-field @click-input="onClick" />

JSX を使用している場合は、イベント名を camelCase に変更してください。

jsx

// Vant 3 - 旧形式 📱
<Field onClick-input={onClick} />

// Vant 4 - 新形式 ✨
<Field onClickInput={onClick} />

🔧 その他の API 調整

v4.0 では以下コンポーネントにも調整があります：

📍 AddressEdit

以下の調整があります：

冗長属性の削除：show-postal・postal-validator を削除 🗑️
イベント引数：change-area の引数を PickerOption[] へ 📊
未公開メソッドの削除：getArea を削除 ✨

Popup の CSS が調整されています。独自 CSS を当てている場合は影響をご確認ください。

ボックスモデル：box-sizing: border-box をデフォルト適用 📦
中央寄せ：position="center" の水平中央寄せを改善し、幅の自動調整問題を解消 🎯

less

// Vant 3 - 旧方式の中央寄せ 📱
.van-popup--center {
  left: 50%;
  transform: translate3d(-50%, -50%, 0);
}

// Vant 4 - 新方式の中央寄せ ✨
.van-popup--center {
  left: 0;
  right: 0;
  width: fit-content;
  max-width: calc(100vw - var(--van-padding-md) * 2);
  margin: 0 auto;
  transform: translateY(-50%);
}

📑 Tabs

イベント整理：click・disabled を削除し、click-tab を使用 🎯

🎨 スタイルの調整

🌈 プライマリーカラーの統一

以前のバージョンでは主色がコンポーネント間で青（#1989fa）と赤（#ee0a24）に分かれていました。

v4 ではすべてのコンポーネントで青を主色に統一しました。

以下のコンポーネントは主色を赤から青へ変更：

AddressEdit 📍 - アドレス編集の配色を統一
AddressList 📋 - アドレス一覧の配色を統一
Card 🃏 - カードの配色を統一
Calendar 📅 - カレンダーの配色を統一
Cascader 🌊 - カスケード選択の配色を統一
ContactList 👥 - 連絡先一覧の配色を統一
ContactEdit ✏️ - 連絡先編集の配色を統一
CouponList 🎫 - クーポン一覧の配色を統一
Dialog 💬 - ダイアログの配色を統一
DropdownMenu 📋 - ドロップダウンの配色を統一
IndexBar 🔤 - インデックスバーの配色を統一
Sidebar 📱 - サイドバーの配色を統一
Steps 👣 - ステップの配色を統一
Tabs 📑 - タブの配色を統一
TreeSelect 🌳 - ツリー選択の配色を統一

🗑️ Less 変数の廃止

v3 では Less 変数と CSS 変数の両方を提供していました。

v4 では Less 変数を廃止し、CSS 変数に一本化しました。利点：

サイズ削減 📦：バンドルサイズの削減
ビルド容易 ⚡：less-loader の不要化
動的柔軟 🎨：実行時にテーマ変数を動的変更可能

Less 変数を使用している場合は ConfigProvider 全局配置を参照して移行してください。

✂️ CSS 変数名の簡略化

コードサイズと使いやすさの観点から、一部の CSS 変数名を短縮しました。

変更例：

less

animation-duration               ->  duration
animation-timing-function-enter  ->  ease-out
animation-timing-function-leave  ->  ease-in
background-color                 ->  background
background-color-light           ->  background-2
border-radius                    ->  radius
border-width-base                ->  border-width
box-shadow                       ->  shadow
font-family                      ->  font
font-weight-bold                 ->  font-bold
price-integer-font               ->  price-font
text-link                        ->  link
transition-duration              ->  duration

変数の数が多いため、リポジトリ全体での一括置換を推奨します。

ConfigProvider には ConfigProviderThemeVars の型定義を追加しました。TypeScript での補完により置換漏れを防げます。

import type { ConfigProviderThemeVars } from 'vant';

const themeVars: ConfigProviderThemeVars = {
  sliderBarHeight: '4px',
};

📚 関連ドキュメント

クイックスタート

クイックスタート - インストールと基本使用 🚀
発展的な使い方 - 高度な機能 🎯
テーマ - テーマカスタマイズ 🎨
ローカライズ - 多言語設定 🌍

コアコンポーネント

ConfigProvider グローバル設定 - グローバル設定とテーマ ⚙️
Picker ピッカー - 再設計された選択コンポーネント 🎛️
DatePicker 日付選択 - 日付選択 📅
TimePicker 時間選択 - 時間選択 ⏰
PickerGroup ピッカーグループ - 複合選択 🎯
Area 地域選択 - 地域選択 🗺️

🚀 v3 から v4 への移行

🌟 概要

📦 Vant 4 のインストール

🔧 按需導入の調整

🗑️ babel-plugin-import の廃止

🎁 メリット

🎨 スタイルの導入方法

🔄 コンポーネントの再設計

🌟 概要

🤔 再設計の目的

🎯 目標

🎛️ Picker の再設計

✨ 主な変更点

📅 DatetimePicker の再設計

✨ 主な変更点

🗺️ Area の再設計

✨ 主な変更点

API の調整

💬 Dialog の呼び出し方法の変更

🛡️ 互換策

🍞 Toast の呼び出し方法の変更

🛡️ 互換策

📢 Notify の呼び出し方法の変更

🛡️ 互換策

🖼️ ImagePreview の呼び出し方法の変更

🛡️ 互換策

🎯 イベント名の調整

🔧 その他の API 調整

📍 AddressEdit

📑 Tabs

🎨 スタイルの調整

🌈 プライマリーカラーの統一

🗑️ Less 変数の廃止

✂️ CSS 変数名の簡略化

📚 関連ドキュメント

クイックスタート

コアコンポーネント

フィードバックコンポーネント

開発ツール

バージョン情報

🚀 v3 から v4 への移行 ​

🌟 概要 ​

📦 Vant 4 のインストール ​

🔧 按需導入の調整 ​

🗑️ babel-plugin-import の廃止 ​

🎁 メリット ​

🎨 スタイルの導入方法 ​

🔄 コンポーネントの再設計 ​

🌟 概要 ​

🤔 再設計の目的 ​

🎯 目標 ​

🎛️ Picker の再設計 ​

✨ 主な変更点 ​

📅 DatetimePicker の再設計 ​

✨ 主な変更点 ​

🗺️ Area の再設計 ​

✨ 主な変更点 ​

API の調整 ​

💬 Dialog の呼び出し方法の変更 ​

🛡️ 互換策 ​

🍞 Toast の呼び出し方法の変更 ​

🛡️ 互換策 ​

📢 Notify の呼び出し方法の変更 ​

🛡️ 互換策 ​

🖼️ ImagePreview の呼び出し方法の変更 ​

🛡️ 互換策 ​

🎯 イベント名の調整 ​

🔧 その他の API 調整 ​

📍 AddressEdit ​

🎭 Popup ​

📑 Tabs ​

🎨 スタイルの調整 ​

🌈 プライマリーカラーの統一 ​

🗑️ Less 変数の廃止 ​

✂️ CSS 変数名の簡略化 ​

📚 関連ドキュメント ​

クイックスタート ​

コアコンポーネント ​

フィードバックコンポーネント ​

開発ツール ​

バージョン情報 ​

🚀 v3 から v4 への移行

🌟 概要

📦 Vant 4 のインストール

🔧 按需導入の調整

🗑️ babel-plugin-import の廃止

🎁 メリット

🎨 スタイルの導入方法

🔄 コンポーネントの再設計

🌟 概要

🤔 再設計の目的

🎯 目標

🎛️ Picker の再設計

✨ 主な変更点

📅 DatetimePicker の再設計

✨ 主な変更点

🗺️ Area の再設計

✨ 主な変更点

API の調整

💬 Dialog の呼び出し方法の変更

🛡️ 互換策

🍞 Toast の呼び出し方法の変更

🛡️ 互換策

📢 Notify の呼び出し方法の変更

🛡️ 互換策

🖼️ ImagePreview の呼び出し方法の変更

🛡️ 互換策

🎯 イベント名の調整

🔧 その他の API 調整

📍 AddressEdit

🎭 Popup

📑 Tabs

🎨 スタイルの調整

🌈 プライマリーカラーの統一

🗑️ Less 変数の廃止

✂️ CSS 変数名の簡略化

📚 関連ドキュメント

クイックスタート

コアコンポーネント

フィードバックコンポーネント

開発ツール

バージョン情報