4.0 バージョンの紹介

序文

一年にわたるイテレーションを経て、Vant 4.0 が正式リリースされました。2017 年のオープンソース以来、4 つ目の重要なメジャーバージョンです。

今回の更新では、ダークモードへの対応、5 つの新コンポーネントの追加、ユーティリティ関数 API の改善、Picker などのコンポーネントのリファクタリングを行い、軽量化と使いやすさも引き続き強化しました。

ダークモード対応

Vant 4.0 はすべてのコンポーネントをダークモードに切り替え可能です。

ConfigProvider コンポーネント の theme を dark に設定するだけで、ページ上のすべての Vant コンポーネントがダークスタイルになります。

<van-config-provider theme="dark">
  <!-- child components -->
</van-config-provider>

ドキュメントもダークモード切り替えに対応しています：

新コンポーネント

Vant 4.0 には以下の新コンポーネントが含まれます：

• BackTop ページトップへ：ページ上部へ戻るボタン。
• TimePicker 時刻選択：時・分・秒の選択。
• DatePicker 日付選択：年・月・日の選択。
• PickerGroup ピッカーグループ：複数の Picker を組み合わせ、1 回の操作で複数値を選択。
• Skeleton スケルトン子コンポーネント：SkeletonTitle、SkeletonImage、SkeletonAvatar などで骨組み画面をカスタマイズ。

TimePicker と DatePicker は旧 DatetimePicker を分割したもので、DatetimePicker は提供を終了します。PickerGroup で日付と時刻の同時選択が可能です。

軽量性の維持

Vant 4.0 のインストールサイズは 30% 削減され、軽量性を維持します。

npm エコシステムの発展に伴い、node_modules はディスクを圧迫します。これを軽減しインストールを高速化するため、依存関係とビルド成果物を最適化しました。

Vant 3.6.2 と比較して、Vant 4.0.0 のインストールサイズは 7MB から 5MB に低下。参考までに、一般的なコンポーネントライブラリは 15MB〜80MB 程度です。packagephobia で確認できます。

バンドルサイズでも、Minified + Gzipped で 70KB 以下を維持しています：

プライマリカラーの統一

Vant 4.0 は全コンポーネントの主色を統一しました。

以前のバージョンでは、主色が青 #1989fa と赤 #ee0a24 に分かれていました。

デザイン体系の一貫性のため、主色を青に統一しました。

主色統一により、テーマのカスタマイズが容易になります。例えば --van-primary-color を上書きして、主色を緑に変更できます：

:root {
  --van-primary-color: #07c160;
}

按需導入方式の調整

Vant 4.0 では babel-plugin-import による按需導入を使用しません。

以前は多くのライブラリが babel-plugin-import に依存していましたが、Vant 4.0 では非対応とし、以下の利点があります：

• Babel に強依存しなくなり、SWC や esbuild などの最新ツールを利用可能。コンパイル効率が向上します。

• babel-plugin-import の import 制約から解放され、コンポーネント以外（例：showToast、buttonProps）も直接インポート可能：

import { showToast, buttonProps } from 'vant';

バンドルサイズについては、Tree Shaking により不要な JS が除去されるため影響はありません。CSS は unplugin-vue-components により按需導入が可能です。詳しくはクイックスタートを参照ください。

スタイル変数の型補完

Vant 4.0 はスタイル変数の型補完を提供します。

Vant は 700 以上のスタイル変数を提供し、CSS や ConfigProvider で変更できます。Vant 4.0 では ConfigProviderThemeVars 型を追加し、変数名の型補完を提供します。

TypeScript コードでは、テーマ変数名を型補完できます：

Picker のリファクタリング

Vant 4.0 は Picker および派生の Area と DatetimePicker をリファクタリングしました。

以前の Picker の API 設計は分かりにくく、以下のような問題がありました：

• columns のデータ形式が誤解を招きやすい
• データフローが不明瞭で、過剰なインスタンスメソッドが公開されている
• DatetimePicker のロジックが複雑で境界ケースに不具合が発生

これらを解決するため、Picker を全面的に再設計し、Area と DatetimePicker も合わせて刷新しました。

これらを使用している場合は、アップグレードガイド を参照してください。

ツール関数の取り扱い調整

Vant 4.0 ではツール関数の使い方を直感的な形に調整しました。

Vant 3 では Dialog() 関数を呼ぶとグローバルダイアログが起動し、Dialog.Component がコンポーネント本体でした。

// 函数调用
Dialog({ message: 'Hello World!' });

// 组件注册
app.use('van-dialog', Dialog.Component);

この API 設計により、ツール関数対応のコンポーネントと通常コンポーネントで使い方が異なり、誤用の原因にもなっていました。また unplugin-vue-components による自動導入も困難でした。

直感的な使い方にするため、Dialog()、Toast()、Notify()、ImagePreview() の呼び出し方式を見直しました。例えば Dialog は関数を showDialog() に改名し、Dialog はコンポーネント本体を指すようにしました。

// 函数调用
showDialog({ message: 'Hello World!' });

// 组件注册
app.use('van-dialog', Dialog);

既存コードの移行を容易にするため、@vant/compat の Dialog() 関数で従来コードを互換実行できます。

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

Dialog({ message: 'Hello World!' });

@vant/compat の Dialog() は Vant 3 と同じ API と挙動です。移行時は参照パスのみ変更し、他のコードはそのままで構いません。アップグレード後は徐々に showDialog() などへ置き換え、@vant/compat を削除することを推奨します。

イベント命名の調整

Vant 4.0 ではイベント名をキャメルケースに統一しました。

Vant 4 から、すべてのイベントは Vue 公式推奨のキャメルケースで命名します。

// Vant 3
emit('click-input');

// Vant 4
emit('clickInput');

この変更は既存のテンプレートコードに影響しません。Vue がテンプレート内でイベント名を自動変換するため、変更は不要です。

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

JSX で使用する場合は、イベント名をキャメルケースに変更してください。従来のハイフン形式は無効となり、JSX の規約に沿った記述になります：

// Vant 3
<Field onClick-input={onClick} />

// Vant 4
<Field onClickInput={onClick} />

Less 変数の廃止

Vant 4.0 では Less 変数によるテーマカスタマイズを廃止しました。

Vant は CSS 変数による柔軟なテーマカスタマイズに対応しているため、Less ベースのカスタマイズは提供しません。npm パッケージには .less のソースは含まれず、コンパイル済みの .css のみが提供されます。

旧来の Less テーマを使用している場合は、ConfigProvider グローバル設定 に置き換えてください。

Vant CLI 5.0

Vant CLI 5.0 も同時にリリースしました。

Vant CLI は Vant のコンポーネントビルドツールで、以下を更新しました：

• Vite を 3.0 にアップグレードし、関連プラグインも更新
• stylelint と @vant/stylelint-config はデフォルトインストールしない方針に。必要なら手動で：

npm add stylelint@13 @vant/stylelint-config

• gh-pages もデフォルトインストール対象外。package.json を次のように更新：

- "release:site": "pnpm build:site && gh-pages -d site-dist",
+ "release:site": "pnpm build:site && npx gh-pages -d site-dist",

バージョン情報

現在、Vant 公式サイト と npm latest は Vant 4.0 を指しています。

Vant 4.0 への完全なアップグレードガイドを用意しています。v3 から v4 への移行 を参照してください。

今後の各バージョンのメンテナンス状況：

名称	フレームワーク	リリース	メンテ状況
Vant 4	Vue 3	2022.12	長期サポート
Vant 3	Vue 3	2020.12	サポート終了（PR 受理なし）
Vant 2	Vue 2	2019.06	サポート終了（PR 受理なし）
Vant 1	Vue 2	2018.03	サポート終了（PR 受理なし）

最後に

Vant 4.0 の開発に貢献してくださった皆さま、そして Vant をご利用のすべての開発者の皆さまに感謝します。オープンソースの道をともに歩み続けましょう。