uni-app x

展示全部

# uni.showToast(options) GitCode GitHub

显示消息提示框

# showToast 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	4.11	4.11	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

options

ShowToastOptions

是

uni.showToast参数定义

名称

类型

必备

默认值

兼容性

描述

title

string

是

提示的内容，长度与 icon 取值有关。

icon

string

否

"success"

icon值说明

合法值

兼容性

描述

success

显示成功图标

error

显示错误图标

fail

显示错误图标，此时title文本无长度显示

exception

显示异常图标，此时title文本无长度显示

显示加载图标

none

不显示图标

image

string.ImageURIString

否

自定义图标的本地路径（app端暂不支持gif）

mask

boolean

否

false

是否显示透明蒙层，防止触摸穿透

duration

number

否

1500

提示的延迟时间，单位毫秒

position

string

否

position值说明。纯文本轻提示显示位置，填写有效值后只有 title 属性生效，且不支持通过 uni.hideToast 隐藏。

合法值

兼容性

描述

top

居上显示

center

居中显示

bottom

居底显示

success

(res: ShowToastSuccess) => void

否

uni.showToast成功回调函数定义

fail

(res: ShowToastFail) => void

否

uni.showToast失败回调函数定义

complete

(res: any) => void

否

uni.showToast完成回调函数定义

# ShowToastFail 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

合法值

兼容性

描述

撤销

1001

请求参数非法

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

# 参见

# uni.hideToast() GitCode GitHub

隐藏消息提示框。

# hideToast 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.0	4.41	3.91	4.11	4.11	4.61

# 参见

# 通用类型

# GeneralCallbackResult

名称

类型

必备

默认值

兼容性

描述

errMsg

string

是

错误信息

# Bug & Tips

在 iOS、微信小程序、Web 平台，showToast 是和页面（包括 dialogPage）绑定的
在 Android 平台
- position 设为 bottom 时，为系统toast，此时与 App 绑定，而不是与页面绑定。position 不为 bottom 时仍与页面绑定
- 系统toast 不支持 icon 图标，仅支持文字
- 部分 Android ROM，如 MIUI，调用系统 toast 时，会在 toast 行首自动加上 App 图标。此为 ROM 行为，目的是帮助用户区分该 toast 是哪个 App 弹出的
在 HarmonyOS 平台，目前只有系统 toast ，和 App window 绑定
当 Toast 和页面绑定时：
- 当showToast执行时，会寻找当前页面栈顶的窗体（包括 dialogPage），找到后进行绑定，然后弹出 Toast。
  - 在支持 dialogPage 的平台（Web和App），uni.showModal、uni.showActionSheet 也是 dialogPage 实现的，此时 toast 会绑定到这些 dialogPage 上
  - 在弹出 Toast 后，再次打开新页面，新页面会覆盖原页面弹出的 Toast。
    - 如需在新页面（包括 dialogPage）弹出 Toast，需要再次调用 showToast
- 关闭页面（包括 dialogPage）时，Toast 会跟随页面（包括 dialogPage）一起消失 + 如需在dialogPage关闭后，仍然弹出 Toast，需要在关闭dialogPage后再次调用 showToast
当 Toast 和应用绑定时，也即系统 toast：弹出和关闭页面，系统 toast 都不会跟随页面被遮挡或消失。
Android 11 及以上版本，应用进入后台后，调用系统 toast 不弹出。文档地址
showToast 里的 Loading，和 showLoading 的区别是，showLoading 需要手动调用 HideLoading 才会关闭。而 showToast 里的 Loading 显示指定时间后会自动关闭。一般情况都需要精准控制关闭时机，所以大多使用 showLoading 和 hideLoading