# uni.showToast(options)

显示消息提示框

# 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

# 参见

# uni.hideToast()

隐藏消息提示框。

# hideToast 兼容性

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

# 参见

# 示例

示例为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">
      <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>

# 通用类型

# 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.showModaluni.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