Toast 提示框

17:06

说明

通过 ref 调用 show(options) 弹出的轻提示，duration 到期后自动关闭，也可手动调用 hide()（别名 close()）关闭。支持 type 主题、icon 开关、loading 加载态与 position（居中 / 顶部 / 底部）；关闭后可执行 callback，并可携带 url 跳转或 back 返回上一页。

兼容性

平台	支持情况
App	✅ 支持（原生 text 不继承父级 color/font-size，组件已在 text 上内联声明；长文本宽度上限按 525rpx 换算，H5 / 小程序为 70%）
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

点击按钮弹出成功提示，2 秒后自动消失。

查看源码

<template>
    <ux-button type="primary" @click="showToast">成功提示</ux-button>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showToast = () => {
    toastRef.value?.show?.({
        title: '操作成功',
        type: 'success',
        duration: 2000
    });
};
</script>

提示类型

支持 primary/success/error/warning 等多种主题。

查看源码

<template>
    <view class="toast-row">
        <ux-button custom-class="toast-item" type="primary" size="small" @click="showType('primary')">primary</ux-button>
        <ux-button custom-class="toast-item" type="success" size="small" @click="showType('success')">success</ux-button>
        <ux-button custom-class="toast-item" type="error" size="small" @click="showType('error')">error</ux-button>
        <ux-button custom-class="toast-item" type="warning" size="small" @click="showType('warning')">warning</ux-button>
    </view>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showType = (type: string) => {
    toastRef.value?.show?.({
        title: '类型: ' + type,
        type,
        duration: 2000
    });
};
</script>

<style scoped>
.toast-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.toast-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

显示位置

支持顶部、居中与底部三种位置。

查看源码

<template>
    <view class="toast-row">
        <ux-button custom-class="toast-item" type="success" size="small" @click="showPosition('top')">顶部</ux-button>
        <ux-button custom-class="toast-item" type="success" size="small" @click="showPosition('center')">居中</ux-button>
        <ux-button custom-class="toast-item" type="success" size="small" @click="showPosition('bottom')">底部</ux-button>
    </view>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showPosition = (position: string) => {
    toastRef.value?.show?.({
        title: '提示内容',
        position,
        type: 'success',
        duration: 2000
    });
};
</script>

<style scoped>
.toast-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.toast-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

图标开关

设置 icon=false 时不显示图标。

查看源码

<template>
    <ux-button type="warning" size="small" @click="showNoIcon">不显示图标</ux-button>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showNoIcon = () => {
    toastRef.value?.show?.({
        title: '无图标提示',
        type: 'warning',
        icon: false,
        duration: 2000
    });
};
</script>

加载提示

loading=true 时显示加载动画。

查看源码

<template>
    <ux-button type="info" size="small" @click="showLoading">加载提示</ux-button>
    <ux-toast ref="toastRef" />
</template>

<script setup lang="uts">
const toastRef = ref<any>();

const showLoading = () => {
    toastRef.value?.show?.({
        title: '加载中...',
        type: 'default',
        duration: 2000,
        loading: true
    });
};
</script>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
zIndex	层级 z-index	string | number	''	-
type	提示类型	ThemeType | 'default'	'default'	-
duration	显示时长，单位ms	number	2000	-
icon	是否显示图标	boolean	true	-
position	显示位置	ToastPosition	'center'	-
callback	关闭时的回调函数	() => void	-	-
back	是否返回上一页	boolean	false	-
isTab	是否为tab页面跳转	boolean	false	-
url	跳转的url	string	''	-
params	跳转参数对象	UTSJSONObject	-	-
global	是否作为全局根部 toast	boolean	false	-
page	是否作为页面级 toast	boolean | string	false	-
loading	是否为loading “常驻”	boolean	false	-

Events

ux-toast 无事件。

Slots

ux-toast 无插槽。

注意事项

1. 组件通过 ref 调用：show(options) 显示，hide()（别名 close()）关闭。
2. duration 为 0 或 ≤0 时不自动关闭，需手动调用 hide() / close()。
3. icon 只在 error / warning / success / info 四类主题下渲染图标；primary / default 即使 icon=true 也不显示图标。
4. loading=true 时改用加载动画（ux-loading）替代图标，此时 icon 被忽略。
5. callback 只在 duration 到期自动关闭后执行；duration≤0 的手动关闭不会触发。
6. 连续调用 show() 会先清掉上一个定时器并重新合并配置，前后调用互不叠加。
7. duration 到期后，url 非空则 uni.navigateTo 跳转，否则 back=true 时返回上一页；isTab 目前不参与跳转判定。
8. 需要一进入页面就显示时，在 onReady 生命周期里调用 show()。
9. 组件以 ux-mask（透明背景、mask-click-able=false）为底层容器，不会拦截页面点击。