docs/api/toast.md
::: sourceCode
GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-prompt
GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-prompt
:::
显示消息提示框
| Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS | HarmonyOS(Vapor) |
|---|---|---|---|---|---|---|
| 4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 | 5.0 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| options | ShowToastOptions | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | uni.showToast参数定义 |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| title | string | 是 | - | Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0 | 提示的内容,长度与 icon 取值有关。 |
| icon | string | 否 | "success" | Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: x | icon值说明 |
| image | string.ImageURIString | 否 | - | Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0 | 自定义图标的本地路径(app端暂不支持gif) |
| mask | boolean | 否 | false | Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0 | 是否显示透明蒙层,防止触摸穿透 |
| duration | number | 否 | 1500 | Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0 | 提示的延迟时间,单位毫秒 |
| position | string | 否 | - | Web: x; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0 | position值说明。纯文本轻提示显示位置,填写有效值后只有 title 属性生效,且不支持通过 uni.hideToast 隐藏。 |
| success | (res: ShowToastSuccess) => void | 否 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | uni.showToast成功回调函数定义 |
| fail | (res: ShowToastFail) => void | 否 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | uni.showToast失败回调函数定义 |
| complete | (res: any) => void | 否 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | uni.showToast完成回调函数定义 |
| 合法值 | 兼容性 | 描述 |
|---|---|---|
| success | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 显示成功图标 |
| error | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 显示错误图标 |
| fail | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 显示错误图标,此时title文本无长度显示,支付宝、抖音小程序生效 |
| exception | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 显示异常图标,此时title文本无长度显示,支付宝小程序生效 |
| loading | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 显示加载图标 |
| none | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 不显示图标 |
| 合法值 | 兼容性 | 描述 |
|---|---|---|
| top | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 居上显示 |
| center | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 居中显示 |
| bottom | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 居底显示 |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errCode | number | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 错误码 |
| errSubject | string | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 统一错误主题(模块)名称 |
| data | any | 否 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 错误信息中包含的数据 |
| cause | Error | 否 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 源错误信息,可以包含多个错误,详见SourceError |
| errMsg | string | 是 | - | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - |
| 合法值 | 兼容性 | 描述 |
|---|---|---|
| 1 | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 撤销 |
| 1001 | Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: - | 请求参数非法 |
::: sourceCode
GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-prompt
GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-prompt
:::
隐藏消息提示框。
| Web | 微信小程序 | Android | iOS | iOS uni-app x UTS 插件 | HarmonyOS | HarmonyOS(Vapor) |
|---|---|---|---|---|---|---|
| 4.0 | 4.41 | 3.91 | 4.11 | 4.11 | 4.61 | 5.0 |
示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见 ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/toast/toast
appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/toast/toast
示例
<template>
<!-- #ifdef APP -->
<scroll-view direction="vertical" style="flex:1">
<!-- #endif -->
<page-head :title="data.title"></page-head>
<view class="uni-padding-wrap">
<view class="uni-padding-wrap">
<text class="uni-title-text uni-common-mb">设置icon</text>
</view>
<view class="uni-list uni-common-pl">
<radio-group @change="radioChangeIcon">
<radio class="uni-list-cell uni-list-cell-pd radio-icon" v-for="(icon, index) in data.icon_enum" :key="icon.value"
:class="index < data.icon_enum.length - 1 ? 'uni-list-cell-line' : ''" :value="icon.value"
:checked="index === data.icon_current">{{icon.name}}</radio>
</radio-group>
</view>
<view class="uni-list-cell uni-list-cell-padding">
<view class="uni-list-cell-db">是否显示自定义图标</view>
<switch :checked="data.imageSelect" @change="change_image_boolean" />
</view>
<view class="uni-list-cell uni-list-cell-padding">
<view class="uni-list-cell-db">是否显示透明蒙层-屏蔽点击事件</view>
<switch :checked="data.maskSelect" @change="change_mask_boolean" />
</view>
<view class="uni-title uni-list-cell-padding">提示的延迟时间,默认:1500(单位毫秒)</view>
<view class="uni-list-cell-padding">
<slider @change="sliderChange" foreColor="#007AFF" :value="data.intervalSelect" :min="1500" :max="5000"
:show-value="true" />
</view>
<view class="uni-btn-v">
<button type="default" @tap="toast1Tap" id="btn-toast-default">点击弹出toast</button>
<button type="default" @tap="hideToast" id="btn-toast-hide">点击隐藏toast</button>
</view>
<!-- #ifdef APP -->
<view class="uni-padding-wrap uni-common-mt">
<text class="uni-title-text uni-common-mb"> 设置position,仅App生效 </text>
</view>
<view class="uni-list uni-common-pl">
<radio-group @change="radioChangePosition">
<radio class="uni-list-cell uni-list-cell-pd radio-position" v-for="(position, index) in data.position_enum"
:key="position.value" :class="index < data.position_enum.length - 1 ? 'uni-list-cell-line' : ''"
:value="position.value" :checked="index === data.position_current">{{position.name}}</radio>
</radio-group>
</view>
<button class="uni-btn uni-common-mb" type="default" @tap="toast2Tap">点击弹出设置position的toast</button>
<!-- #endif -->
<text>{{data.exeRet}}</text>
</view>
<!-- #ifdef APP -->
</scroll-view>
<!-- #endif -->
</template>
<script setup lang="uts">
type IconItemType = {
value : "success" | "error" | "fail" | "exception" | "loading" | "none";
name : string
}
type PositionItemType = {
value : "top" | "center" | "bottom";
name : string
}
type DataType = {
title: string;
exeRet: string;
imageSelect: boolean;
maskSelect: boolean;
intervalSelect: number;
position_current: number;
position_enum: PositionItemType[];
icon_current: number;
icon_enum: IconItemType[];
}
// 使用reactive包装数据,避免ref数据在自动化测试中无法获取
const data = reactive({
title: 'toast',
exeRet: '',
imageSelect: false,
maskSelect: false,
intervalSelect: 1500,
position_current: 0,
position_enum: [
{ "value": "top", "name": "top: 居上显示(Android 暂不支持)" },
{ "value": "center", "name": "center: 居中显示(Android 暂不支持)" },
{ "value": "bottom", "name": "bottom: 居底显示" },
],
icon_current: 0,
icon_enum: [
{
value: 'success',
name: '显示成功图标',
},
{
value: 'error',
name: '显示错误图标',
},
// {
// value: 'fail',
// name: '显示错误图标',
// },
// {
// value: 'exception',
// name: '显示异常图标,此时title文本无长度显示',
// },
{
value: 'loading',
name: '显示加载图标',
},
{
value: 'none',
name: '不显示图标',
},
],
} as DataType)
onMounted(() => {
uni.showToast({
title: 'onMounted 调用示例,2秒后消失'
})
setTimeout(function () {
uni.hideToast()
}, 2000);
})
//自动化测试例专用
const jest_getWindowInfo = () : GetWindowInfoResult => {
return uni.getWindowInfo();
}
const radioChangeIcon = (e : UniRadioGroupChangeEvent) => {
for (let i = 0; i < data.icon_enum.length; i++) {
if (data.icon_enum[i].value === e.detail.value) {
data.icon_current = i;
break;
}
}
}
const change_image_boolean = (e : UniSwitchChangeEvent) => {
data.imageSelect = e.detail.value
}
const change_mask_boolean = (e : UniSwitchChangeEvent) => {
data.maskSelect = e.detail.value
}
const sliderChange = (e : UniSliderChangeEvent) => {
data.intervalSelect = e.detail.value
}
const radioChangePosition = (e : UniRadioGroupChangeEvent) => {
for (let i = 0; i < data.position_enum.length; i++) {
if (data.position_enum[i].value === e.detail.value) {
data.position_current = i;
break;
}
}
}
const toast1Tap = () => {
uni.showToast({
title: "默认",
icon: data.icon_enum[data.icon_current].value,
duration: data.intervalSelect,
image: data.imageSelect ? "/static/test-image/logo.png" : null,
mask: data.maskSelect,
success: (res) => {
// console.log('success:',res)
data.exeRet = "success:" + JSON.stringify(res)
},
fail: (res) => {
data.exeRet = "fail:" + JSON.stringify(res)
},
})
}
const toast3Tap = () => {
uni.showToast({
title: "默认",
icon: 'none',
duration: data.intervalSelect,
image: data.imageSelect ? "/static/test-image/logo.png" : null,
mask: data.maskSelect,
success: (res) => {
// console.log('success:',res)
data.exeRet = "success:" + JSON.stringify(res)
},
fail: (res) => {
data.exeRet = "fail:" + JSON.stringify(res)
},
})
}
// #ifdef APP
const toast2Tap = () => {
let positionValue = data.position_enum[data.position_current].value
uni.showToast({
title: "显示一段轻提示,position:" + positionValue,
position: positionValue,
success: (res) => {
data.exeRet = "success:" + JSON.stringify(res)
},
fail: (res) => {
data.exeRet = "fail:" + JSON.stringify(res)
},
})
}
// #endif
const hideToast = () => {
uni.hideToast()
}
defineExpose({
data,
toast1Tap,
toast3Tap,
// #ifdef APP
toast2Tap,
// #endif
hideToast
})
</script>
:::
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errMsg | string | 是 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | 错误信息 |