Toast 轻提示 ​

介绍 ​

在页面中间弹出黑色半透明提示，用于消息通知、加载提示、操作结果提示等场景。

引入 ​

通过以下方式来引入组件。

js
import { createApp } from 'vue';
import { Toast } from '@szhn/dh-design-mobile';

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

函数调用 ​

为了便于使用 Toast，dh-design-mobile 提供了一系列辅助函数，通过辅助函数可以快速唤起全局的 Toast 组件。

比如使用 showToast 函数，调用后会直接在页面中渲染对应的轻提示。

js
import { showToast } from '@szhn/dh-design-mobile';

showToast('提示内容');

代码演示 ​

文字提示 ​

使用 showToast 方法在屏幕中间展示一条文字提示。

js
import { showToast } from '@szhn/dh-design-mobile';

showToast('提示内容');

加载提示 ​

使用 showLoadingToast 方法展示加载提示，通过 forbidClick 选项可以禁用背景点击。

js
import { showLoadingToast } from '@szhn/dh-design-mobile';

showLoadingToast({
  message: '加载中...',
  forbidClick: true,
});

成功/失败提示 ​

使用 showSuccessToast 方法展示成功提示，使用 showFailToast 方法展示失败提示。

js
import { showSuccessToast, showFailToast } from '@szhn/dh-design-mobile';

showSuccessToast('成功文案');
showFailToast('失败文案');

自定义图标 ​

通过 icon 选项可以自定义图标，支持传入图标名称或图片链接，等同于 Icon 组件的 name 属性。

js
import { showToast } from '@szhn/dh-design-mobile';

showToast({
  message: '自定义图标',
  icon: 'like-o',
});

showToast({
  message: '自定义图片',
  icon: 'https://fastly.jsdelivr.net/npm/@vant/assets/logo.png',
});

通过 loadingType 属性可以自定义加载图标类型。

js
import { showLoadingToast } from '@szhn/dh-design-mobile';

showLoadingToast({
  message: '加载中...',
  forbidClick: true,
  loadingType: 'spinner',
});

自定义位置 ​

Toast 默认渲染在屏幕正中位置，通过 position 属性可以控制 Toast 展示的位置。

js
import { showToast } from '@szhn/dh-design-mobile';

showToast({
  message: '顶部展示',
  position: 'top',
});

showToast({
  message: '底部展示',
  position: 'bottom',
});

文字换行方式 ​

通过 wordBreak 选项可以控制 Toast 中的文字过长时的截断方式，默认值为 break-all，可选值为 break-word 和 normal。

js
import { showToast } from '@szhn/dh-design-mobile';

// 换行时截断单词
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',
});

动态更新提示 ​

执行 Toast 方法时会返回对应的 Toast 实例，通过修改实例上的 message 属性可以实现动态更新提示的效果。

js
import { showLoadingToast, closeToast } from '@szhn/dh-design-mobile';

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();
  }
}, 1000);

单例模式 ​

Toast 默认采用单例模式，即同一时间只会存在一个 Toast，如果需要在同一时间弹出多个 Toast，可以参考下面的示例：

js
import { showToast, showSuccessToast, allowMultipleToast } from '@szhn/dh-design-mobile';

allowMultipleToast();

const toast1 = showToast('第一个 Toast');
const toast2 = showSuccessToast('第二个 Toast');

toast1.close();
toast2.close();

修改默认配置 ​

通过 setToastDefaultOptions 函数可以全局修改 showToast 等方法的默认配置。

js
import { setToastDefaultOptions, resetToastDefaultOptions } from '@szhn/dh-design-mobile';

setToastDefaultOptions({ duration: 2000 });

setToastDefaultOptions('loading', { forbidClick: true });

resetToastDefaultOptions();

resetToastDefaultOptions('loading');

使用 Toast 组件 ​

如果你需要在 Toast 内嵌入组件或其他自定义内容，可以直接使用 Toast 组件，并使用 message 插槽进行定制。使用前需要通过 app.use 等方式注册组件。

html
<van-toast v-model:show="show" style="padding: 0">
  <template #message>
    <van-image :src="image" width="200" height="140" style="display: block" />
  </template>
</van-toast>
js
import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    return { show };
  },
};

API ​

方法 ​

dh-design-mobile 中导出了以下 Toast 相关的辅助函数：

方法名说明参数返回值
showToast展示文字提示ToastOptions | stringToast 实例
showLoadingToast展示加载提示ToastOptions | stringToast 实例
showSuccessToast展示成功提示ToastOptions | stringToast 实例
showFailToast展示失败提示ToastOptions | stringToast 实例
closeToast关闭当前展示的提示closeAll: booleanvoid
allowMultipleToast允许同时存在多个 Toast-void
setToastDefaultOptions修改默认配置，影响所有的 showToast 调用。传入 type 可以修改指定类型 Toast 的默认配置type | ToastOptionsvoid
resetToastDefaultOptions重置默认配置，影响所有的 showToast 调用。传入 type 可以重置指定类型 Toast 的默认配置typevoid

ToastOptions 数据结构 ​

调用 showToast 等方法时，支持传入以下选项：

参数说明类型默认值
type提示类型，可选值为 loading success fail htmlToastTypetext
position位置，可选值为 top bottomToastPositionmiddle
message文本内容，支持通过\n换行string''
wordBreak文本内容的换行方式，可选值为 normal break-all break-wordToastWordBreak'break-all'
icon自定义图标，支持传入图标名称或图片链接，等同于 Icon 组件的 name 属性string-
iconSize图标大小，如 20px 2em，默认单位为 pxnumber | string36px
iconPrefix图标类名前缀，等同于 Icon 组件的 class-prefix 属性stringvan-icon
overlay是否显示背景遮罩层booleanfalse
forbidClick是否禁止背景点击booleanfalse
closeOnClick是否在点击后关闭booleanfalse
closeOnClickOverlay是否在点击遮罩层后关闭booleanfalse
loadingType加载图标类型, 可选值为 spinnerstringcircular
duration展示时长(ms)，值为 0 时，toast 不会消失number2000
className自定义类名string | Array | object-
overlayClass自定义遮罩层类名string | Array | object-
overlayStyle自定义遮罩层样式object-
transition动画类名，等价于 transition 的name属性stringvan-fade
teleport指定挂载的节点，等同于 Teleport 组件的 to 属性string | Elementbody
z-index将组件的 z-index 层级设置为一个固定值number | string2000+
onClose关闭时的回调函数Function-
onOpened完全展示后的回调函数Function-

Props ​

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

参数说明类型默认值
type提示类型，可选值为 loading success fail htmlToastTypetext
position位置，可选值为 top bottomToastPositionmiddle
message文本内容，支持通过\n换行string''
word-break文本内容的换行方式，可选值为 normal break-all break-wordToastWordBreak'break-all'
icon自定义图标，支持传入图标名称或图片链接，等同于 Icon 组件的 name 属性string-
icon-size图标大小，如 20px 2em，默认单位为 pxnumber | string36px
icon-prefix图标类名前缀，等同于 Icon 组件的 class-prefix 属性stringvan-icon
overlay是否显示背景遮罩层booleanfalse
forbid-click是否禁止背景点击booleanfalse
close-on-click是否在点击后关闭booleanfalse
close-on-click-overlay是否在点击遮罩层后关闭booleanfalse
loading-type加载图标类型, 可选值为 spinnerstringcircular
duration展示时长(ms)，值为 0 时，toast 不会消失number2000
class-name自定义类名string | Array | object-
overlay-class自定义遮罩层类名string | Array | object-
overlay-style自定义遮罩层样式object-
transition动画类名，等价于 transition 的name属性stringvan-fade
teleport指定挂载的节点，等同于 Teleport 组件的 to 属性string | Elementbody
z-index将组件的 z-index 层级设置为一个固定值number | string2000+

Events ​

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

事件名说明回调参数
close关闭时的回调函数-
opened完全展示后的回调函数-

Slots ​

使用 Toast 组件时，支持以下插槽：

名称说明
message自定义文本内容

类型定义 ​

组件导出以下类型定义：

ts
import type {
  ToastType,
  ToastProps,
  ToastOptions,
  ToastPosition,
  ToastWordBreak,
  ToastWrapperInstance,
} from '@szhn/dh-design-mobile';

主题定制 ​

样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称默认值描述
--van-toast-max-width70%轻提示的最大宽度
--van-toast-font-sizevar(--van-font-size-md)轻提示的字体大小
--van-toast-text-colorvar(--van-white)轻提示的文字颜色
--van-toast-loading-icon-colorvar(--van-white)加载图标的颜色
--van-toast-line-heightvar(--van-line-height-md)轻提示的行高
--van-toast-radiusvar(--van-radius-lg)轻提示的圆角大小
--van-toast-backgroundfade(var(--van-black), 70%)轻提示的背景色
--van-toast-icon-size36px图标的大小
--van-toast-text-min-width96px文字提示的最小宽度
--van-toast-text-paddingvar(--van-padding-xs) var(--van-padding-sm)文字提示的内边距
--van-toast-default-paddingvar(--van-padding-md)默认提示的内边距
--van-toast-default-width88px默认提示的宽度
--van-toast-default-min-height88px默认提示的最小高度
--van-toast-position-top-distance20%顶部位置时的距离
--van-toast-position-bottom-distance20%底部位置时的距离

常见问题 ​

引用 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

dh-design-mobile 底层基于 Vant 4.x，不再支持 babel-plugin-import 插件，请参考 迁移指南 移除该插件。

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

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

js
// 以下方式是不需要的
import { showToast } from '@szhn/dh-design-mobile'

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

解决方案有 2 种：

  • 使用 showToast 时不进行显式导入；
  • 如果必须显示导入 showToast ，则同时需要手动导入 Toast 组件的相关样式。
js
import { showToast } from '@szhn/dh-design-mobile'
import '@szhn/dh-design-mobile/style.css'