uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
API
uni.showToast(options)
showToast 兼容性
参数
ShowToastFail 的属性值
示例
参见
uni.hideToast()
hideToast 兼容性
参见
通用类型
展示全部

# uni.showToast(options) GitCodeGitHub

显示消息提示框

# 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文本无长度显示
loading
-
显示加载图标
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 是 -
-
错误码
合法值 兼容性 描述
1
-
撤销
1001
-
请求参数非法
errSubject string 是 -
-
统一错误主题（模块）名称
data any 否 -
-
错误信息中包含的数据
cause Error 否 -
-
源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 -
-

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<template>
  <!-- #ifdef APP -->
  <scroll-view direction="vertical" style="flex:1">
  <!-- #endif -->
    <page-head :title="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 icon_enum" :key="icon.value"
            :class="index < icon_enum.length - 1 ? 'uni-list-cell-line' : ''" :value="icon.value"
            :checked="index === 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="imageSelect" @change="change_image_boolean" />
      </view>
      <view class="uni-list-cell uni-list-cell-padding">
        <view class="uni-list-cell-db">是否显示透明蒙层-屏蔽点击事件</view>
        <switch :checked="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="intervalSelect" :min="1500" :max="5000"
          :show-value="true" />
      </view>
      <view class="uni-btn-v">
        <button class="uni-btn-v" type="default" @tap="toast1Tap" id="btn-toast-default">点击弹出toast</button>
        <button class="uni-btn-v" 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 position_enum"
            :key="position.value" :class="index < position_enum.length - 1 ? 'uni-list-cell-line' : ''"
            :value="position.value" :checked="index === position_current">{{position.name}}</radio>
        </radio-group>
      </view>
      <button class="uni-btn uni-btn-v uni-common-mb" type="default" @tap="toast2Tap">点击弹出设置position的toast</button>
      <!-- #endif -->
      <text>{{exeRet}}</text>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script lang="uts">
  type IconItemType = {
    value : "success" | "error" | "fail" | "exception" | "loading" | "none";
    name : string
  }
  type PositionItemType = {
    value : "top" | "center" | "bottom";
    name : string
  }
  export default {
    data() {
      return {
        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: 居底显示" },
        ] as PositionItemType[],
        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 IconItemType[],
      }
    },
    onLoad() {
      uni.showToast({
        title: 'onLoad 调用示例,2秒后消失'
      })
      setTimeout(function () {
        uni.hideToast()
      }, 2000);
    },
    methods: {
      //自动化测试例专用
      jest_getWindowInfo() : GetWindowInfoResult {
        return uni.getWindowInfo();
      },
      radioChangeIcon(e : UniRadioGroupChangeEvent) {
        for (let i = 0; i < this.icon_enum.length; i++) {
          if (this.icon_enum[i].value === e.detail.value) {
            this.icon_current = i;
            break;
          }
        }
      },
      change_image_boolean: function (e : UniSwitchChangeEvent) {
        this.imageSelect = e.detail.value
      },
      change_mask_boolean: function (e : UniSwitchChangeEvent) {
        this.maskSelect = e.detail.value
      },
      sliderChange(e : UniSliderChangeEvent) {
        this.intervalSelect = e.detail.value
      },
      radioChangePosition(e : UniRadioGroupChangeEvent) {
        for (let i = 0; i < this.position_enum.length; i++) {
          if (this.position_enum[i].value === e.detail.value) {
            this.position_current = i;
            break;
          }
        }
      },
      toast1Tap: function () {
        uni.showToast({
          title: "默认",
          icon: this.icon_enum[this.icon_current].value,
          duration: this.intervalSelect,
          image: this.imageSelect ? "/static/uni.png" : null,
          mask: this.maskSelect,
          success: (res) => {
            // console.log('success:',res)
            this.exeRet = "success:" + JSON.stringify(res)
          },
          fail: (res) => {
            this.exeRet = "fail:" + JSON.stringify(res)
          },
        })
      },
      toast3Tap: function () {
        uni.showToast({
          title: "默认",
          icon: 'none',
          duration: this.intervalSelect,
          image: this.imageSelect ? "/static/uni.png" : null,
          mask: this.maskSelect,
          success: (res) => {
            // console.log('success:',res)
            this.exeRet = "success:" + JSON.stringify(res)
          },
          fail: (res) => {
            this.exeRet = "fail:" + JSON.stringify(res)
          },
        })
      },
      // #ifdef APP
      toast2Tap: function () {
        let positionValue = this.position_enum[this.position_current].value
        uni.showToast({
          title: "显示一段轻提示,position:" + positionValue,
          position: positionValue,
          success: (res) => {
            this.exeRet = "success:" + JSON.stringify(res)
          },
          fail: (res) => {
            this.exeRet = "fail:" + JSON.stringify(res)
          },
        })
      },
      // #endif
      hideToast: function () {
        uni.hideToast()
      }
    }
  }
</script>

# 参见

# uni.hideToast() GitCodeGitHub

隐藏消息提示框。

# 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
本页导读
uni.showToast(options)
showToast 兼容性
参数
ShowToastFail 的属性值
示例
参见
uni.hideToast()
hideToast 兼容性
参见
通用类型
GeneralCallbackResult
Bug & Tips