外观
Toast 消息提示
约 909 字大约 3 分钟
2025-10-31
Toast 组件主要用于消息通知、加载提示、操作结果提示等醒目提示效果,我们为其提供了多种丰富的 API。
注意:
由于 uni 中无法通过 js 创建元素,所以需要在页面中调用<toast />组件,再通过ref开启
基本使用
以下为不同能力的 toast 的具体表现
<template>
<view>
<un-toast ref="unToast"></un-toast>
<un-cell-group title-bg-color="rgb(243, 244, 246)">
<un-cell
:titleStyle="{fontWeight: 500}"
:title="item.title"
v-for="(item, index) in list"
:key="index"
isLink
:icon="item.iconUrl"
@click="showToast(item)"
>
</un-cell>
</un-cell-group>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import type { UnToastOptions } from './types.uts'
type ToastItem = {
type?: string
title: string
message?: string
icon?: boolean
iconUrl: string
url?: string
}
const unToast = ref<any>(null)
const show = ref(false)
const list = ref<ToastItem[]>([
{
type: "default",
title: "默认主题",
message: "锦瑟无端五十弦",
iconUrl: "https://uviewui.com/demo/toast/default.png",
},
{
type: "error",
icon: false,
title: "失败主题",
message: "一弦一柱思华年",
iconUrl: "https://uviewui.com/demo/toast/error.png",
},
{
type: "success",
title: "成功主题(带图标)",
message: "庄生晓梦迷蝴蝶",
iconUrl: "https://uviewui.com/demo/toast/success.png",
},
{
type: "loading",
title: "正在加载",
message: "正在加载",
iconUrl: "https://uviewui.com/demo/toast/loading.png",
},
{
type: "default",
title: "结束后跳转标签页",
message: "此情可待成追忆",
url: "/pages/componentsB/tag/tag",
iconUrl: "https://uviewui.com/demo/toast/jump.png",
},
])
const showToast = (params: ToastItem) => {
const options: UnToastOptions = {
...params,
success() {
if (params.url) {
uni.navigateTo({
url: params.url,
})
}
},
}
unToast.value?.open(options)
}
</script>
<style lang="scss">
.u-page {
padding: 0;
}
.un-cell-icon {
width: 36rpx;
height: 36rpx;
margin-right: 8rpx;
}
.un-cell-group__title__text {
font-weight: bold;
}
</style>API
Props
| 参数名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| zIndex | toast展示时的zIndex值 | string | number | 10090 |
| loading | 是否加载中 | boolean | false |
| title | 显示的文字内容 | string | - |
| icon | 图标,或者绝对路径的图片 | string | - |
| type | 主题类型 | Enum | default |
| mask | 是否显示透明遮罩,防止点击穿透 | boolean | false |
| position | 位置 | Enum | center |
| duration | 展示时间,单位ms | string | number | 2000 |
| fill | 实体图标 | boolean | false |
| customStyle | 组件的样式,对象形式 | string | object | {} |
Methods
| 方法名 | 说明 | 参数 |
|---|---|---|
| open | 显示toast | Function |
| close | 关闭toast | Function |
| primary | 显示主色toast | Function |
| success | 显示成功toast | Function |
| error | 显示错误toast | Function |
| warning | 显示警告toast | Function |
| showLoading | 显示加载中toast | Function |
Scss 变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-toast-padding | 12px 20px | 消息提示框内边距 |
| $un-toast-border-radius | $radius-base | 消息提示框圆角 |
| $un-toast-max-width | 300px | 消息提示框最大宽度 |
| $un-toast-loading-padding | 12px 30px | 加载状态消息提示框内边距 |
| $un-toast-loading-bg-color | rgba(17, 17, 17, 0.7) | 加载状态消息提示框背景颜色 |
| $un-toast-text-color | $text-color-inverted | 消息提示框文本颜色 |
| $un-toast-text-font-size | 15px | 消息提示框文本字体大小 |
提示
组件内部默认使用 scss 变量,如需修改,请查看 scss 变量使用 文档
数据类型
/**
* Toast错误类型
* 用于表示Toast显示失败时的错误信息
*/
type UnShowToastFail = {
errCode: number; // 错误码
errSubject: string; // 错误主题
errMsg: string; // 错误信息
}
/**
* Toast配置选项类型
* 用于配置Toast的显示和行为
*/
type UnToastOptions = {
title?: string; // 显示的文字内容
type?: string; // 主题类型
duration?: string | number; // 展示时间,单位ms,默认2000
icon?: boolean | string; // 是否显示图标或图标路径
fill?: boolean; // 实体图标,默认false
position?: string; // 位置,默认center
success?: () => void; // 执行完后的回调函数
fail?: (result: UnShowToastFail) => void; // 失败后回调
mask?: boolean; // 是否显示透明遮罩,防止点击穿透,默认false
loading?: boolean; // 是否加载中状态,默认false
}