Toast 轻提示 - Vant 4
Toast トースト
🎯 紹介
Toast はアプリの小さな妖精のような存在です。画面中央にそっと現れ、半透明のブラックで各種情報を上品に伝えます。成功の喜び、失敗の通知、読み込み中の待機など、ユーザーを妨げずに役目を果たし、スマートに消えます。
📦 取り込み
以下の方法でコンポーネントをグローバル登録します。詳細はコンポーネント登録を参照してください。
import { createApp } from 'vue';
import { Toast } from 'vant';
const app = createApp();
app.use(Toast);🚀 関数呼び出し
開発体験をよりスムーズにするため、Vant は便利な補助関数群を提供します。これらの関数でグローバルな Toast を簡単に呼び出せます。
例えば showToast を使えば、1 行で美しいトーストを表示できます。
import { showToast } from 'vant';
showToast('操作成功！');🎨 コード例
📝 テキストトースト
最も基本でよく使われる機能です。showToast で画面中央に簡潔なテキストを表示し、結果を素早く伝えます。
import { showToast } from 'vant';
// シンプルなテキストトースト
showToast('保存成功');
// => 保存に成功しました
// やや長めのテキスト
showToast('設定は保存され、次回起動時に有効になります');
// 複数行テキスト
showToast('1 行目の内容\n2 行目の内容\n3 行目の内容');
// 表示時間をカスタマイズ
showToast({
message: 'このメッセージは 5 秒間表示されます',
duration: 5000
});⏳ ローディングトースト
showLoadingToast で読み込み中のトーストを表示します。forbidClick で背景クリックを無効化し、処理中の誤操作を防ぎます。
import { showLoadingToast, closeToast } from 'vant';
// 基本的なローディング
showLoadingToast({
message: '読み込み中...',
forbidClick: true,
});
// テキストなしのローディング
showLoadingToast({
forbidClick: true,
duration: 0, // 不自动关闭
});
// 擬似的な非同期処理
showLoadingToast({
message: 'データを送信中...',
forbidClick: true,
duration: 0,
});
// 3 秒後に閉じる
setTimeout(() => {
closeToast();
}, 3000);✅ 成功/失敗トースト
showSuccessToast で成功、showFailToast で失敗を表示し、結果を直感的に伝えます。
import { showSuccessToast, showFailToast } from 'vant';
// 成功トースト
showSuccessToast('操作成功');
showSuccessToast({
message: '数据保存成功！',
duration: 3000
});
// 失敗トースト
showFailToast('操作失败');
showFailToast({
message: 'ネットワーク接続に失敗しました。再試行してください',
duration: 4000
});🎨 カスタムアイコン
icon オプションでアイコンをカスタマイズできます。アイコン名や画像 URL を指定可能です。
import { showToast, showLoadingToast } from 'vant';
// 既存アイコンを使用
showToast({
message: 'いいねしました',
icon: 'like-o',
});
// カスタム画像を使用
showToast({
message: 'ブランドの通知',
icon: 'https://fastly.jsdelivr.net/npm/@vant/assets/logo.png',
});
// アイコンサイズを指定
showToast({
message: '大きなアイコンの通知',
icon: 'star-o',
iconSize: '48px'
});
// ローディングアイコンの種類を指定
showLoadingToast({
message: '読み込み中...',
forbidClick: true,
loadingType: 'spinner', // 使用 spinner 样式
});📍 表示位置のカスタマイズ
Toast はデフォルトで中央に表示されます。position 属性で表示位置を制御できます。
import { showToast } from 'vant';
// 上部表示 - ステータス通知に適する
showToast({
message: '新着メッセージのお知らせ',
position: 'top',
});
// 下部表示 - 操作フィードバックに適する
showToast({
message: '操作が完了しました',
position: 'bottom',
});
// 中央表示（デフォルト）- 重要な通知に適する
showToast({
message: '重要なお知らせ',
position: 'middle',
});📄 テキストの折り返し方式
wordBreak オプションで長文の折り返し方式を制御し、より上品に表示します。
import { showToast } from 'vant';
// 単語を分割して改行（デフォルト）
showToast({
message: 'This message will contain a incomprehensibilities long word.',
wordBreak: 'break-all',
});
// 単語を分割しない - 単語の整合性を保持
showToast({
message: 'This message will contain a incomprehensibilities long word.',
wordBreak: 'break-word',
});
// 通常の改行 - スペースでのみ改行
showToast({
message: 'This is a normal text wrapping example with multiple words.',
wordBreak: 'normal',
});🔄 動的更新トースト
Toast の呼び出しはインスタンスを返します。インスタンスの message を更新して動的に内容を変更できます。進捗表示に最適です。
import { showLoadingToast, closeToast, showSuccessToast } from 'vant';
// カウントダウン例
const toast = showLoadingToast({
duration: 0,
forbidClick: true,
message: 'カウントダウン 3 秒',
});
let second = 3;
const timer = setInterval(() => {
second--;
if (second) {
toast.message = `カウントダウン ${second} 秒`;
} else {
clearInterval(timer);
closeToast();
showSuccessToast('カウントダウン終了！');
}
}, 1000);
// アップロード進捗例
const uploadToast = showLoadingToast({
duration: 0,
forbidClick: true,
message: 'アップロード中 0%',
});
// 擬似的なアップロード進捗
let progress = 0;
const uploadTimer = setInterval(() => {
progress += 10;
if (progress <= 100) {
uploadToast.message = `アップロード中 ${progress}%`;
}
if (progress >= 100) {
clearInterval(uploadTimer);
closeToast();
showSuccessToast('アップロード完了！');
}
}, 200);🔗 シングルトンモード
Toast はデフォルトでシングルトンです。複数同時表示が必要な場合はマルチインスタンスモードを有効化します。
import { showToast, showSuccessToast, allowMultipleToast } from 'vant';
// マルチインスタンスを有効化
allowMultipleToast();
// 同時に複数の Toast を表示可能
const toast1 = showToast('1 つ目の Toast');
const toast2 = showSuccessToast('2 つ目の Toast');
// 特定の Toast を手動で閉じる
setTimeout(() => {
toast1.close();
}, 2000);
setTimeout(() => {
toast2.close();
}, 3000);
// 実用例：異なる種類のトーストを同時表示
showToast({
message: 'バックグラウンドでデータ同期中...',
position: 'top',
duration: 0
});
showSuccessToast({
message: '操作は成功しました',
position: 'bottom'
});デフォルト設定の変更
setToastDefaultOptions で showToast などのデフォルト設定をグローバルに変更できます。
import { setToastDefaultOptions, resetToastDefaultOptions } from'vant'; setToastDefaultOptions({ duration: 2000 }); setToastDefaultOptions('loading', { forbidClick: true }); resetToastDefaultOptions(); resetToastDefaultOptions('loading');Toast コンポーネントの使用
Toast 内にコンポーネントや任意の内容を埋め込みたい場合は、Toast コンポーネントを直接使用し、message スロットでカスタマイズします。使用前に app.use で登録してください。
import { ref } from'vue'; exportdefault { setup() { const show = ref(false); return { show }; }, };API
🛠️ メソッド
Vant は以下の Toast 関連の補助関数を提供します：
| メソッド名 | 説明 | 引数 | 戻り値 |
|---|---|---|---|
| showToast 📝 | テキストトーストを表示 | ToastOptions | string | Toast インスタンス |
| showLoadingToast ⏳ | ローディングトーストを表示 | ToastOptions | string | Toast インスタンス |
| showSuccessToast ✅ | 成功トーストを表示 | ToastOptions | string | Toast インスタンス |
| showFailToast ❌ | 失敗トーストを表示 | ToastOptions | string | Toast インスタンス |
| closeToast 🔒 | 現在のトーストを閉じる | closeAll: boolean | void |
| allowMultipleToast 🔗 | 複数トーストの同時表示を許可 | - | void |
| setToastDefaultOptions ⚙️ | デフォルト設定を変更 | type | ToastOptions | void |
| resetToastDefaultOptions 🔄 | デフォルト設定をリセット | type | void |
📋 ToastOptions のデータ構造
showToast などの呼び出し時に、以下のオプションを渡せます：
| パラメータ | 説明 | 型 | デフォルト |
|---|---|---|---|
| type 🎯 | 提示类型 - 决定 Toast 的展示样式 | ToastType | text |
| position 📍 | 位置 - 控制 Toast 在屏幕中的显示位置 | ToastPosition | middle |
| message 📝 | 文本内容 - 支持通过 \n 换行 | string | '' |
| wordBreak 📄 | 文本换行方式 - 控制长文本的显示效果 | ToastWordBreak | 'break-all' |
| icon 🎨 | 自定义图标 - 支持图标名称或图片链接 | string | - |
| iconSize 📏 | 图标大小 - 如 20px、2em | number | string | 36px |
| iconPrefix 🏷️ | 图标类名前缀 - 自定义图标库前缀 | string | van-icon |
| overlay 🎭 | 是否显示背景遮罩层 - 增强视觉焦点 | boolean | false |
| forbidClick 🚫 | 是否禁止背景点击 - 防止误操作 | boolean | false |
| closeOnClick 👆 | 是否在点击后关闭 - 快速关闭方式 | boolean | false |
| closeOnClickOverlay 🎭 | 是否在点击遮罩层后关闭 - 遮罩交互 | boolean | false |
| loadingType ⏳ | 加载图标类型 - circular 或 spinner | string | circular |
| duration ⏰ | 展示时长(ms) - 0 表示不自动关闭 | number | 2000 |
| className 🎨 | 自定义类名 - 个性化样式定制 | string | Array | object | - |
| overlayClass 🎭 | 自定义遮罩层类名 - 遮罩样式定制 | string | Array | object | - |
| overlayStyle 🎨 | 自定义遮罩层样式 - 遮罩样式对象 | object | - |
| transition 🎬 | 动画类名 - 自定义进出场动画 | string | van-fade |
| teleport 🚀 | 指定挂载节点 - 控制渲染位置 | string | Element | body |
| z-index 📚 | 层级设置 - 控制显示优先级 | number | string | 2000+ |
| onClose 🔚 | 关闭时的回调函数 - 关闭事件处理 | Function | - |
| onOpened 🎉 | 完全展示后的回调函数 - 显示完成事件 | Function | - |
⚙️ Props
コンポーネントとして Toast を使用する際にサポートされる Props：
| パラメータ | 説明 | 型 | デフォルト |
|---|---|---|---|
| type | 種類（loading``success``fail``html） | ToastType | text |
| position | 表示位置（top``bottom） | ToastPosition | middle |
| message | テキスト内容（\n で改行可） | string | '' |
| word-break | 改行方式（normal``break-all``break-word） | ToastWordBreak | 'break-all' |
| icon | カスタムアイコン（アイコン名または画像 URL。Icon の name 相当） | string | - |
| icon-size | アイコンサイズ（例 20px``2em。デフォルト単位は px） | number | string | 36px | | icon-prefix | アイコンクラス接頭辞（Icon の class-prefix 相当） | string | van-icon |
| overlay | 背景オーバーレイを表示 | boolean | false | | forbid-click | 背景のクリックを禁止 | boolean | false | | close-on-click | クリックで閉じる | boolean | false | | close-on-click-overlay | オーバーレイクリックで閉じる | boolean | false | | loading-type | ローディングアイコン種類（spinner） | string | circular |
| duration | 表示時間（ms）。0 の場合は自動で消えない | number | 2000 | | class-name | カスタムクラス名 | string | Array | object | - | | overlay-class | オーバーレイのクラス名 | string | Array | object | - | | overlay-style | オーバーレイのスタイル | object | - | | transition | アニメーション名（transition の name） | string | van-fade |
| teleport | マウント先（Teleport の to） | string | Element | body |
| z-index | 固定の z-index を設定 | number | string | 2000+ |
🎯 Events
コンポーネントとして Toast を使用する際にサポートされるイベント：
| イベント名 | 説明 | コールバック引数 |
|---|---|---|
| close 🔚 | 閉じたときのコールバック | - |
| opened 🎉 | 完全表示後のコールバック | - |
🎨 Slots
Toast コンポーネント使用時にサポートされるスロット：
| 名前 | 説明 |
|---|---|
| message 📝 | メッセージ内容のカスタマイズ（複雑な構造可） |
📝 型定義
组件导出以下类型定义：
import type {
ToastType,
ToastProps,
ToastOptions,
ToastPosition,
ToastWordBreak,
ToastWrapperInstance,
} from 'vant';🎨 テーマカスタマイズ
🎯 スタイル変数
以下の CSS 変数でスタイルをカスタマイズできます。使用方法は ConfigProvider コンポーネント を参照してください。
| 名称 | デフォルト | 説明 |
|---|---|---|
| --van-toast-max-width | 70% | - |
| --van-toast-font-size | var(--van-font-size-md) | - |
| --van-toast-text-color | var(--van-white) | - |
| --van-toast-loading-icon-color | var(--van-white) | - |
| --van-toast-line-height | var(--van-line-height-md) | - |
| --van-toast-radius | var(--van-radius-lg) | - |
| --van-toast-background | fade(var(--van-black), 70%) | - |
| --van-toast-icon-size | 36px | - |
| --van-toast-text-min-width | 96px | - |
| --van-toast-text-padding | var(--van-padding-xs) var(--van-padding-sm) | - |
| --van-toast-default-padding | var(--van-padding-md) | - |
| --van-toast-default-width | 88px | - |
| --van-toast-default-min-height | 88px | - |
| --van-toast-position-top-distance | 20% | - |
| --van-toast-position-bottom-distance | 20% | - |
❓ よくある質問
🚨 showToast をインポートするとビルドエラー？
showToast のインポート時に以下のエラーが出る場合、babel-plugin-import を使用していることが原因です。
These dependencies were not found:
* vant/es/show-toast in ./src/xxx.js
* vant/es/show-toast/style in ./src/xxx.jsVant 4.0 以降は babel-plugin-import をサポートしません。移行ガイド を参照して削除してください。
🎨 コンポーネントを個別導入時、showToast でスタイルが崩れる？
個別導入 で Vant を統合する場合、showToast などを明示的にインポートする必要はありません。インポートするとスタイル欠落が発生します。
// 以下方式是不需要的
import { showToast } from 'vant'showToast などを明示的にインポートすると、@vant/auto-import-resolver が Toast のスタイルを自動取込しないため、スタイルが欠落します。
解決策は 2 つあります：
- showToast の明示的なインポートを行わない
- どうしてもインポートする場合は、Toast のスタイルも手動でインポートする
import { showToast } from 'vant'
import 'vant/lib/toast/style'関連ドキュメント 📚
🎯 コアコンポーネント
- Loading ローディング - ローディング表示
- Dialog ダイアログ - 複雑な対話を扱うダイアログ
- Notify 通知 - ページ上部の通知
🔧 補助コンポーネント
- Popup ポップアップ - カスタムポップアップの基盤
- Overlay オーバーレイ - 背景オーバーレイの制御
- Icon アイコン - Toast で使うアイコン
⚡ 上級機能
- ConfigProvider グローバル設定 - Toast のテーマと挙動を一元設定
- Locale 国際化 - 多言語環境での Toast 設定