# uni.showToast(options)

显示消息提示框

# showToast 兼容性 ?

Web 微信小程序 支付宝小程序 Android iOS HarmonyOS
4.0 4.41 5.31 3.91 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-android/app-ios端暂不支持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 是

# 参见

# uni.hideToast(options?)

隐藏消息提示框。

# hideToast 兼容性 ?

Web 微信小程序 支付宝小程序 Android iOS HarmonyOS
4.0 4.41 5.31 3.91 4.11 4.61

# 参数

名称 类型 必填
options HideToastOptions 否
名称 类型 必备 兼容性 描述
allType boolean 否
是否关闭所有类型的 toast,默认不关闭。仅鸿蒙平台支持。
success (res: HideToastSuccess) => void 否
成功回调函数定义
fail (res: HideToastFail) => void 否
失败回调函数定义
complete (res: any) => void 否
完成回调函数定义
noConflict boolean 否
需要基础库: 2.22.1

目前 toast 和 loading 相关接口可以相互混用,此参数可用于取消混用特性

# HideToastSuccess 的属性值

名称 类型 必备
errMsg string 是

# HideToastFail 的属性值

名称 类型 必备 描述
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="data.title"></page-head>
    <view class="uni-padding-wrap">
      <enum-data :items="iconOptions" title="设置icon" item-class="radio-icon"
        @change="radioChangeIcon"></enum-data>
      <boolean-data :defaultValue="data.imageSelect" title="是否显示自定义图标"
        @change="change_image_boolean"></boolean-data>
      <boolean-data :defaultValue="data.maskSelect" title="是否显示透明蒙层-屏蔽点击事件"
        @change="change_mask_boolean"></boolean-data>
      <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 -->
      <enum-data :items="positionOptions" title="设置position,仅App生效" item-class="radio-position"
        @change="radioChangePosition"></enum-data>
      <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">
  import { ItemType } from '@/components/enum-data/enum-data-types'

  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: 'loading',
        name: '显示加载图标',
      },
      {
        value: 'none',
        name: '不显示图标',
      },
    ],
  } as DataType)

  const iconOptions = computed(() : ItemType[] => {
    return data.icon_enum.map((item, index) : ItemType => {
      return {
        value: index,
        name: item.name,
        checked: index == data.icon_current
      }
    })
  })

  const positionOptions = computed(() : ItemType[] => {
    return data.position_enum.map((item, index) : ItemType => {
      return {
        value: index,
        name: item.name,
        checked: index == data.position_current
      }
    })
  })

  let isAutoTest = false

  onLoad((options : OnLoadOptions) => {
    isAutoTest = options['autoTest'] == 'true'
  })

  onMounted(() => {
    const duration = isAutoTest ? 10000 : 3000
    uni.showToast({
      title: 'onMounted 调用示例,3秒后消失',
      duration: duration
    })
    if (!isAutoTest) {
      setTimeout(function () {
        uni.hideToast()
      }, duration);
    }
  })

  //自动化测试例专用
  const jest_getWindowInfo = () : GetWindowInfoResult => {
    return uni.getWindowInfo();
  }

  const radioChangeIcon = (value : number) => {
    data.icon_current = value
  }

  const change_image_boolean = (value : boolean) => {
    data.imageSelect = value
  }

  const change_mask_boolean = (value : boolean) => {
    data.maskSelect = value
  }

  const sliderChange = (e : UniSliderChangeEvent) => {
    data.intervalSelect = e.detail.value
  }

  const radioChangePosition = (value : number) => {
    data.position_current = value
  }

  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,
      duration: data.intervalSelect,
      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>

# 通用类型

# GeneralCallbackResult

名称 类型 必备 描述
errMsg string 是 错误信息

# 页面级toast和应用级toast

toast,分页面级和应用级。默认为页面级。

  • 页面级toast: toast 和页面绑定。**页面(含 dialogPage)关闭时,toast 会跟随页面立即一起消失;新页面(含 dialogPage)出现时会遮挡之前页面弹出的 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 都不会跟随页面被遮挡或消失。toast会按指定的时长完整显示,然后再消失。

由于历史原因和平台差异,设置应用级 toast 的方式是设置 showToast 的参数 position 属性,不管 position 设为 "top"、"center"、"bottom" 均可。

并非所有平台、所有版本都支持设置 position,即应用级 toast。

  • 小程序平台不支持,所以小程序平台的 toast 都是和页面绑定的。
  • web平台暂不支持。后续会补充
  • iOS平台需要5.31+ 蒸汽模式才支持。
  • Android平台设置 position 时弹出的是 Android系统的 toast,该 toast 样式受rom影响:
    • 系统toast 不支持 icon 图标,仅支持文字,Android12及以上版本文字内容通常限制为两行
    • Android11及以上版本,系统toast设置不支持设置显示在顶部或居中,仅支持显示在底部
    • Android11及以上版本,应用进入后台后,调用系统 toast 不弹出。 文档地址
    • 部分 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

  • showToast 里的 Loading,和 showLoading 的区别是,showLoading 需要手动调用 HideLoading 才会关闭。而 showToast 里的 Loading 显示指定时间后会自动关闭。一般情况都需要精准控制关闭时机,所以大多使用 showLoading 和 hideLoading