::: sourceCode
## uni.showToast(options) @showtoast
> issues: https://issues.dcloud.net.cn/?mid=api.ui.toast.showToast
> 源码: https://github.com/dcloudio/uni-app/tree/uni-app-x-alpha/src/uni_modules/uni-showToast
:::
显示消息提示框
### showToast 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61
### 参数
| 名称 | 类型 | 必填 | 描述 |
| :- | :- | :- | :- |
| options | **ShowToastOptions** | 是 | uni.showToast参数定义 |
#### options 的属性描述
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
| :- | :- | :- | :- | :-: | :- |
| title | string | 是 | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 提示的内容,长度与 icon 取值有关。 |
| icon | string | 否 | "success" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 5.25 | icon值说明 |
| image | [string.ImageURIString](/uts/data-type.md#ide-string) | 否 | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 5.25 | 自定义图标的本地路径(app-android/app-ios端暂不支持gif) |
| mask | boolean | 否 | false | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 5.25 | 是否显示透明蒙层,防止触摸穿透 |
| duration | number | 否 | 1500 | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 提示的延迟时间,单位毫秒 |
| position | string | 否 | | Web: 5.32; 微信小程序: x; 支付宝小程序: x; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | position值说明。纯文本轻提示显示位置,填写有效值后只有 title 属性生效,且不支持通过 uni.hideToast 隐藏。 |
| success | (res: ShowToastSuccess) => void | 否 | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | uni.showToast成功回调函数定义 |
| fail | (res: [ShowToastFail](#showtoastfail-values)) => void | 否 | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | uni.showToast失败回调函数定义 |
| complete | (res: any) => void | 否 | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | uni.showToast完成回调函数定义 |
##### icon 的属性描述
| 合法值 | 兼容性 | 描述 |
| :- | :-: | :- |
| "success" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 5.25 | 显示成功图标 |
| "error" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 5.25 | 显示错误图标 |
| "fail" | Web: x; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 显示错误图标,此时title文本无长度显示,支付宝、抖音小程序生效 |
| "exception" | Web: x; 微信小程序: x; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 显示异常图标,此时title文本无长度显示,支付宝小程序生效 |
| "loading" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 5.25 | 显示加载图标 |
| "none" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 5.25 | 不显示图标 |
##### position 的属性描述
| 合法值 | 兼容性 | 描述 |
| :- | :-: | :- |
| "top" | Web: 5.32; 微信小程序: x; 支付宝小程序: x; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 居上显示 |
| "center" | Web: 5.32; 微信小程序: x; 支付宝小程序: x; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 居中显示 |
| "bottom" | Web: 5.32; 微信小程序: x; 支付宝小程序: x; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 居底显示 |
#### ShowToastFail 的属性值 @showtoastfail-values
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| errCode | number | 是 | 错误码 |
| errSubject | string | 是 | 统一错误主题(模块)名称 |
| data | any | 否 | 错误信息中包含的数据 |
| cause | [Error](/err-spec.md#unierror) | 否 | 源错误信息,可以包含多个错误,详见SourceError |
| errMsg | string | 是 | |
#### errCode 的属性描述
| 合法值 | 描述 |
| :- | :- |
| 1 | 撤销 |
| 1001 | 请求参数非法 |
::: sourceCode
## uni.hideToast(options?) @hidetoast
> issues: https://issues.dcloud.net.cn/?mid=api.ui.toast.hideToast
> 源码: https://github.com/dcloudio/uni-app/tree/uni-app-x-alpha/src/uni_modules/uni-prompt
:::
隐藏消息提示框。
### hideToast 兼容性
Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61
### 参数
| 名称 | 类型 | 必填 |
| :- | :- | :- |
| options | **HideToastOptions** | 否 |
#### options 的属性描述
| 名称 | 类型 | 必备 | 兼容性 | 描述 |
| :- | :- | :- | :-: | :- |
| allType | boolean | 否 | Web: 5.32; 微信小程序: x; 支付宝小程序: x; Android: 5.31; iOS: 5.31; HarmonyOS: 5.31 | 是否关闭所有类型的 toast,默认不关闭。 |
| success | (res: [HideToastSuccess](#hidetoastsuccess-values)) => void | 否 | Web: x; 微信小程序: x; 支付宝小程序: x; Android: 5.31; iOS: 5.31; HarmonyOS: 5.31 | 成功回调函数定义 |
| fail | (res: [HideToastFail](#hidetoastfail-values)) => void | 否 | Web: x; 微信小程序: x; 支付宝小程序: x; Android: 5.31; iOS: 5.31; HarmonyOS: 5.31 | 失败回调函数定义 |
| complete | (res: any) => void | 否 | Web: x; 微信小程序: x; 支付宝小程序: x; Android: 5.31; iOS: 5.31; HarmonyOS: 5.31 | 完成回调函数定义 |
| noConflict | boolean | 否 | 微信小程序: 4.41 | 需要基础库: `2.22.1`
目前 toast 和 loading 相关接口可以相互混用,此参数可用于取消混用特性
|
#### HideToastSuccess 的属性值 @hidetoastsuccess-values
| 名称 | 类型 | 必备 |
| :- | :- | :- |
| errMsg | string | 是 |
#### HideToastFail 的属性值 @hidetoastfail-values
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| errCode | number | 是 | 错误码 |
| errSubject | string | 是 | 统一错误主题(模块)名称 |
| data | any | 否 | 错误信息中包含的数据 |
| cause | [Error](/err-spec.md#unierror) | 否 | 源错误信息,可以包含多个错误,详见SourceError |
| errMsg | string | 是 | |
#### errCode 的属性描述
| 合法值 | 描述 |
| :- | :- |
| 1 | 撤销 |
| 1001 | 请求参数非法 |
## 示例
示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/API/toast/toast.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/API/toast/toast.uvue)
::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/API/toast/toast
> appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/API/toast/toast
>示例
```vue
提示的延迟时间,默认:1500(单位毫秒)
{{data.exeRet}}
```
:::
## 通用类型
### GeneralCallbackResult @generalcallbackresult-values
| 名称 | 类型 | 必备 | 描述 |
| :- | :- | :- | :- |
| errMsg | string | 是 | 错误信息 |
## 页面级toast和应用级toast@position
toast,分页面级和应用级。默认为页面级。
- 页面级toast:
toast 和页面绑定。**页面(含 dialogPage)关闭时,toast 会跟随页面立即一起消失;新页面(含 dialogPage)出现时会遮挡之前页面弹出的 toast **。
+ 当showToast执行时,会寻找当前页面栈顶的窗体(包括 dialogPage),找到后进行绑定,然后弹出 Toast。
+ 在支持 dialogPage 的平台(Web和App),[uni.showModal](./modal.md)、[uni.showActionSheet](./action-sheet.md) 也是 dialogPage 实现的,此时 toast 会绑定到这些 dialogPage 上
+ 在弹出 toast 后,再次打开新页面,新页面会覆盖原页面弹出的 toast。
+ 如需在新页面(包括 dialogPage)弹出 toast,需要再次调用 showToast
+ 关闭页面(包括 dialogPage)时,toast 会跟随页面(包括 dialogPage)一起消失
+ 如需在dialogPage关闭后,仍然弹出 toast,需要在关闭dialogPage后再次调用 showToast
- 应用级toast:
toast 和应用绑定。
弹出和关闭页面,全部 toast 都不会跟随页面被遮挡或消失。toast会按指定的时长完整显示,然后再消失。
由于历史原因和平台差异,设置应用级 toast 的方式是设置 showToast 的参数 position 属性,不管 position 设为 "top"、"center"、"bottom" 均可。
并非所有平台、所有版本都支持设置 position,即应用级 toast。
- 小程序平台不支持,所以小程序平台的 toast 都是和页面绑定的。
- iOS平台需要5.31+ 蒸汽模式、web平台需要5.32 才支持。
- Android平台设置 position 时弹出的是 Android系统的 toast,该 toast 样式受rom影响:
* 系统toast 不支持 icon 图标,仅支持文字,Android12及以上版本文字内容通常限制为两行
* Android11及以上版本,系统toast设置不支持设置显示在顶部或居中,仅支持显示在底部
* Android11及以上版本,应用进入后台后,调用系统 toast 不弹出。 [文档地址](https://developer.android.google.cn/about/versions/11/behavior-changes-11?hl=nb#toasts)
* 部分 Android ROM,如 MIUI,调用系统 toast 时,会在 toast 行首自动加上 App 图标。此为 ROM 行为,目的是帮助用户区分该 toast 是哪个 App 弹出的
- HarmonyOS 平台
- 5.24 及以下
- 只有系统 toast ,和 App window 绑定
- 不支持 icon 图标,仅支持文字
- 5.25 及以上:
* position 设为 top、center、bottom 时,为系统 toast,和页面绑定
* 当没有传递 position 参数时,支持 icon、mask、image 参数,和页面绑定
## Bug & Tips@tips
- showToast 里的 Loading,和 showLoading 的区别是,showLoading 需要手动调用 HideLoading 才会关闭。而 showToast 里的 Loading 显示指定时间后会自动关闭。一般情况都需要精准控制关闭时机,所以大多使用 showLoading 和 hideLoading