Back to Uni App

Toast

docs/api/toast.md

2.3.317.4 KB
Original Source
<!-- ## uni.showToast(options) @showtoast -->

::: sourceCode

uni.showToast(options) @showtoast

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-prompt

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-prompt

:::

显示消息提示框

showToast 兼容性

Web微信小程序AndroidiOSiOS uni-app x UTS 插件HarmonyOSHarmonyOS(Vapor)
4.04.413.914.114.114.615.0

参数

名称类型必填默认值兼容性描述
optionsShowToastOptions-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -uni.showToast参数定义

options 的属性描述

名称类型必备默认值兼容性描述
titlestring-Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0提示的内容,长度与 icon 取值有关。
iconstring"success"Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: xicon值说明
imagestring.ImageURIString-Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0自定义图标的本地路径(app端暂不支持gif)
maskbooleanfalseWeb: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0是否显示透明蒙层,防止触摸穿透
durationnumber1500Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0提示的延迟时间,单位毫秒
positionstring-Web: x; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; iOS uni-app x UTS 插件: 4.11; HarmonyOS: 4.61; HarmonyOS(Vapor): 5.0position值说明。纯文本轻提示显示位置,填写有效值后只有 title 属性生效,且不支持通过 uni.hideToast 隐藏。
success(res: ShowToastSuccess) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -uni.showToast成功回调函数定义
fail(res: ShowToastFail) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -uni.showToast失败回调函数定义
complete(res: any) => void-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -uni.showToast完成回调函数定义
icon 的属性描述
合法值兼容性描述
successWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -显示成功图标
errorWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -显示错误图标
failWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -显示错误图标,此时title文本无长度显示,支付宝、抖音小程序生效
exceptionWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -显示异常图标,此时title文本无长度显示,支付宝小程序生效
loadingWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -显示加载图标
noneWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -不显示图标
position 的属性描述
合法值兼容性描述
topWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -居上显示
centerWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -居中显示
bottomWeb: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -居底显示

ShowToastFail 的属性值 @showtoastfail-values

名称类型必备默认值兼容性描述
errCodenumber-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -错误码
errSubjectstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -统一错误主题(模块)名称
dataany-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -错误信息中包含的数据
causeError-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
errMsgstring-Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -

errCode 的属性描述

合法值兼容性描述
1Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -撤销
1001Web: -; 微信小程序: -; Android: -; iOS: -; HarmonyOS: -请求参数非法
<!-- UTSAPIJSON.showToast.example -->

参见

<!-- ## uni.hideToast() @hidetoast -->

::: sourceCode

uni.hideToast() @hidetoast

GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-prompt

GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-prompt

:::

隐藏消息提示框。

hideToast 兼容性

Web微信小程序AndroidiOSiOS uni-app x UTS 插件HarmonyOSHarmonyOS(Vapor)
4.04.413.914.114.114.615.0
<!-- UTSAPIJSON.hideToast.example -->

参见

示例

示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见 ::: 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
<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

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息

Bug & Tips@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