Toast 轻提示 - Vant 4

Toast 轻提示

🎯 介绍

Toast 就像是应用中的小精灵！它会在页面中间悄悄出现，用黑色半透明的优雅姿态向用户传达各种信息。无论是成功的喜悦、失败的提醒，还是加载中的等待，Toast 都能以最不打扰的方式完成使命，然后优雅地消失。

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { Toast } from 'vant';

const app = createApp();
app.use(Toast);

🚀 函数调用

为了让你的开发体验更加丝滑，Vant 提供了一系列贴心的辅助函数！通过这些函数，你可以轻松唤起全局的 Toast 组件，就像呼唤一个听话的小助手。

比如使用 showToast 函数，简单一行代码就能在页面中展示精美的轻提示。

import { showToast } from 'vant';

showToast('操作成功！');

🎨 代码演示

📝 文字提示

最基础也是最常用的功能！使用 showToast 方法可以在屏幕中间展示一条简洁的文字提示，让用户快速了解操作结果。

import { showToast } from 'vant';

// 简单的文字提示
showToast('保存成功');

// 稍长一点的提示
showToast('您的设置已保存，将在下次启动时生效');

// 多行文字提示
showToast('第一行内容\n第二行内容\n第三行内容');

// 自定义持续时间
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 选项可以自定义图标，支持传入图标名称或图片链接，让你的提示更加个性化和直观。

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 属性可以控制 Toast 展示的位置，适应不同的界面布局需求。

import { showToast } from 'vant';

// 顶部显示 - 适合状态通知
showToast({
  message: '新消息提醒',
  position: 'top',
});

// 底部显示 - 适合操作反馈
showToast({
  message: '操作已完成',
  position: 'bottom',
});

// 中间显示（默认）- 适合重要提示
showToast({
  message: '重要提示信息',
  position: 'middle',
});

📄 文字换行方式

通过 wordBreak 选项可以控制 Toast 中的文字过长时的截断方式，让文本显示更加优雅。

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 方法时会返回对应的 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 默认采用单例模式，即同一时间只会存在一个 Toast。如果需要在同一时间弹出多个 Toast，可以开启多实例模式。

import { showToast, showSuccessToast, allowMultipleToast } from 'vant';

// 开启多实例模式
allowMultipleToast();

// 现在可以同时显示多个 Toast
const toast1 = showToast('第一个 Toast');
const toast2 = showSuccessToast('第二个 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 等方式注册组件。

html

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 🔗	允许同时存在多个 Toast - 开启多实例模式	-	`void`
setToastDefaultOptions ⚙️	修改默认配置 - 全局定制 Toast 行为	`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	自定义图标，支持传入图标名称或图片链接，等同于 Icon 组件的 name 属性	string	-

🎯 Events

通过组件调用 Toast 时，支持以下事件：

事件名	说明	回调参数
close 🔚	关闭时的回调函数 - Toast 消失时触发	-
opened 🎉	完全展示后的回调函数 - Toast 显示完成时触发	-

🎨 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 插件，导致代码被错误编译。

bash

These dependencies were not found: 
* vant/es/show-toast in ./src/xxx.js 
* vant/es/show-toast/style in ./src/xxx.js

Vant 从 4.0 版本开始不再支持 babel-plugin-import 插件，请参考迁移指南移除该插件。

🎨 按需引入组件时，使用 showToast 时出现样式异常问题？

在使用按需引入组件方案集成 Vant 时，使用 showToast 等函数无需进行显式导入，否则会造成样式异常。

// 以下方式是不需要的
import { showToast } from 'vant'

这是因为在显式导入 showToast 等函数时， @vant/auto-import-resolver 将不会自动导入 Toast 的样式资源，这将导致 Toast 组件的样式缺失，从而导致样式异常问题。

解决方案有 2 种：

使用 showToast 时不进行显式导入；
如果必须显示导入 showToast ，则同时需要手动导入 Toast 组件的相关样式。

import { showToast } from 'vant'
import 'vant/lib/toast/style'

Toast 轻提示

🎯 介绍

📦 引入

🚀 函数调用

🎨 代码演示

📝 文字提示

⏳ 加载提示

✅ 成功/失败提示

🎨 自定义图标

📍 自定义位置

📄 文字换行方式

🔄 动态更新提示

🔗 单例模式

修改默认配置

使用 Toast 组件

API

🛠️ 方法

📋 ToastOptions 数据结构

⚙️ Props

🎯 Events

🎨 Slots

📝 类型定义

🎨 主题定制

🎯 样式变量

❓ 常见问题

🚨 引用 showToast 时出现编译报错？

🎨 按需引入组件时，使用 showToast 时出现样式异常问题？

相关文档 📚

🎯 核心组件

🔧 辅助组件

⚡ 高级功能

Toast 轻提示 ​

🎯 介绍 ​

📦 引入 ​

🚀 函数调用 ​

🎨 代码演示 ​

📝 文字提示 ​

⏳ 加载提示 ​

✅ 成功/失败提示 ​

🎨 自定义图标 ​

📍 自定义位置 ​

📄 文字换行方式 ​

🔄 动态更新提示 ​

🔗 单例模式 ​

修改默认配置 ​

使用 Toast 组件 ​

API ​

🛠️ 方法 ​

📋 ToastOptions 数据结构 ​

⚙️ Props ​

🎯 Events ​

🎨 Slots ​

📝 类型定义 ​

🎨 主题定制 ​

🎯 样式变量 ​

❓ 常见问题 ​

🚨 引用 showToast 时出现编译报错？ ​

🎨 按需引入组件时，使用 showToast 时出现样式异常问题？ ​

相关文档 📚 ​

🎯 核心组件 ​

🔧 辅助组件 ​

⚡ 高级功能 ​

Toast 轻提示

🎯 介绍

📦 引入

🚀 函数调用

🎨 代码演示

📝 文字提示

⏳ 加载提示

✅ 成功/失败提示

🎨 自定义图标

📍 自定义位置

📄 文字换行方式

🔄 动态更新提示

🔗 单例模式

修改默认配置

使用 Toast 组件

API

🛠️ 方法

📋 ToastOptions 数据结构

⚙️ Props

🎯 Events

🎨 Slots

📝 类型定义

🎨 主题定制

🎯 样式变量

❓ 常见问题

🚨 引用 showToast 时出现编译报错？

🎨 按需引入组件时，使用 showToast 时出现样式异常问题？

相关文档 📚

🎯 核心组件

🔧 辅助组件

⚡ 高级功能