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 兼容性
参见
注意事项
uni.showLoading(options)
参数
示例
showLoading 兼容性
展示全部

# uni.showToast(options)

显示消息提示框

# 参数

名称 类型 必填 默认值 描述
options ShowToastOptions 是 -
名称 类型 必备 默认值 描述
title string 是 - 提示的内容，长度与 icon 取值有关。
icon "success" | "error" | "fail" | "exception" | "loading" | "none" 否 - icon值说明 success: 显示成功图标，error: 显示错误图标； fail: 显示错误图标，此时title文本无长度显示； exception: 显示异常图标，此时title文本无长度显示； loading: 显示加载图标；none: 不显示图标。
image string.ImageURIString | null 否 - 自定义图标的本地路径（app端暂不支持gif）
mask boolean | null 否 - 是否显示透明蒙层，防止触摸穿透，默认：false
duration number | null 否 - 提示的延迟时间，单位毫秒，默认：1500
position "top" | "center" | "bottom" 否 - position值说明（仅App生效） top: 居上显示； center: 居中显示；bottom： 居底显示
success (res: ShowToastSuccess) => void | null 否 - uni.showToast成功回调函数定义
fail (res: IPromptError) => void | null 否 - uni.showToast失败回调函数定义
complete (res: any) => void | null 否 - uni.showToast完成回调函数定义
# IPromptError 的属性值
名称 类型 必备 默认值 描述
errCode 1 | 1001 是 - 错误码
- 1 撤销
- 1001 请求参数非法
errSubject string 是 - 统一错误主题（模块）名称
data any | null 否 - 错误信息中包含的数据
cause Error | null 否 - 源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 - -

# 示例

hello uni-app x

Template

Script

<template>
  <view>
    <page-head :title="title"></page-head>
    <view class="uni-padding-wrap">
      <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="toastTapIconError" id="btn-toast-errorIcon">点击弹出设置icon的toast</button>
        <button class="uni-btn-v" type="default" @tap="toast2Tap" id="btn-toast-duration">点击弹出设置duration的toast</button>
        <button class="uni-btn-v" type="default" @tap="toast3Tap" id="btn-toast-loading">点击弹出显示loading的toast</button>
        <!-- #ifndef MP-ALIPAY -->
        <button class="uni-btn-v" type="default" @tap="toast4Tap">点击弹出显示自定义图片的toast</button>
        <!-- #endif -->
        <!-- #ifdef APP -->
        <button class="uni-btn-v" type="default" @tap="toast5Tap" id="btn-toast-postion-bottom">点击显示无图标的居底toast</button>
        <!-- #endif -->
        <button class="uni-btn-v" type="default" @tap="hideToast" id="btn-toast-hide">点击隐藏toast</button>
      </view>
      <text>{{exeRet}}</text>
    </view>
  </view>
</template>

# showToast 兼容性

Android iOS web
3.9.0 4.11 4.0

# 参见

相关 Bug

# 注意事项

  • App平台 position 参数特别说明

如果没有设置 position 字段，uni.showToast 会采用应用弹窗方案，即弹窗与页面生命周期绑定。 页面关闭时，当前页面弹出的所有弹窗都会被自动取消。

如果设置了position 字段，uni.showToast 会采用系统弹窗方案，即弹窗与页面无绑定关系。 页面关闭后，弹出中的/等待弹出的Toast会继续展示。

系统弹窗在部分系统（比如 MIUI,Google）可能会有应用图标前缀。

系统弹窗在部分系统（比如 鸿蒙 4.0以上）可能不支持顶部和居中展示。

# uni.showLoading(options)

显示 loading 提示框, 需主动调用 uni.hideLoading 才能关闭提示框。

# 参数

名称 类型 必填 默认值 描述
options ShowLoadingOptions 是 -
名称 类型 必备 默认值 描述
title string 是 - 提示的内容，长度与 icon 取值有关。
mask boolean | null 否 - 是否显示透明蒙层，防止触摸穿透，默认：false
success (res: ShowLoadingSuccess) => void | null 否 - uni.showLoading成功回调函数定义
fail (res: IPromptError) => void | null 否 - uni.showLoading失败回调函数定义
complete (res: any) => void | null 否 - uni.showLoading完成回调函数定义
# IPromptError 的属性值
名称 类型 必备 默认值 描述
errCode 1 | 1001 是 - 错误码
- 1 撤销
- 1001 请求参数非法
errSubject string 是 - 统一错误主题（模块）名称
data any | null 否 - 错误信息中包含的数据
cause Error | null 否 - 源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 - -

# 示例

hello uni-app x

Template

Script

<template>
  <view>
    <page-head :title="title"></page-head>
    <view class="uni-list">
      <view class="uni-list-cell uni-list-cell-pd">
        <view class="uni-list-cell-db">是否显示透明蒙层-屏蔽点击事件</view>
        <switch :checked="maskSelect" @change="maskChange" />
      </view>
      <view class="uni-padding-wrap">
        <view class="uni-title uni-common-mt">
          <text class="uni-title-text"> 设置标题 </text>
        </view>
      </view>
      <view class="uni-list uni-common-pl">
        <radio-group @change="radioChange">
          <radio class="uni-list-cell uni-list-cell-pd radio" v-for="(item, index) in items" :key="item.value"
            :class="index < items.length - 1 ? 'uni-list-cell-line' : ''" :value="item.value"
            :checked="index === current">
            {{ item.name }}
          </radio>
        </radio-group>
      </view>
    </view>
    <view class="uni-padding-wrap">
      <view class="uni-btn-v">
        <button class="uni-btn-v" type="primary" @click="showLoading">显示 loading 提示框</button>
        <button class="uni-btn-v" @click="hideLoading">隐藏 loading 提示框</button>
        <text>为方便演示，loading弹出3秒后自动关闭</text>
      </view>
    </view>
  </view>
</template>

# showLoading 兼容性

Android iOS web
3.9.0 4.11 4.0

# 参见

相关 Bug

# uni.showModal(options)

显示模态弹窗，可以只有一个确定按钮，也可以同时有确定和取消按钮。类似于一个API整合了 html 中：alert、confirm。

# 参数

名称 类型 必填 默认值 描述
options ShowModalOptions 是 -
名称 类型 必备 默认值 描述
title string | null 否 - 提示的标题
content string | null 否 - 提示的内容
showCancel boolean | null 否 true
是否显示取消按钮，默认为 true
cancelText string | null 否 - 取消按钮的文字，默认为"取消"
cancelColor string.ColorString | null 否 - 取消按钮的文字颜色，默认为"#000000"
confirmText string | null 否 - 确定按钮的文字，默认为"确定"
confirmColor string.ColorString | null 否 - 确定按钮的文字颜色
editable boolean | null 否 false
是否显示输入框
placeholderText string | null 否 - 显示输入框时的提示文本
success (res: ShowModalSuccess) => void | null 否 - uni.showModal成功回调函数定义
fail (res: IPromptError) => void | null 否 - uni.showModal失败回调函数定义
complete (res: any) => void | null 否 - uni.showModal完成回调函数定义
# ShowModalSuccess 的属性值
名称 类型 必备 默认值 描述
confirm boolean 是 - 为 true 时，表示用户点击了确定按钮
cancel boolean 是 - 为 true 时，表示用户点击了取消（用于 Android 系统区分点击蒙层关闭还是点击取消按钮关闭）
content string | null 否 - editable 为 true 时，用户输入的文本
# IPromptError 的属性值
名称 类型 必备 默认值 描述
errCode 1 | 1001 是 - 错误码
- 1 撤销
- 1001 请求参数非法
errSubject string 是 - 统一错误主题（模块）名称
data any | null 否 - 错误信息中包含的数据
cause Error | null 否 - 源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 - -

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <view>
      <page-head :title="title"></page-head>
      <view class="uni-list">
        <radio-group @change="radioChange">
          <radio class="uni-list-cell uni-list-cell-pd" v-for="(item, index) in items" :key="item.value"
            :class="index < items.length - 1 ? 'uni-list-cell-line' : ''" :value="item.value"
            :checked="index === current">
            {{ item.name }}
          </radio>
        </radio-group>
      </view>
      <view class="uni-list">
        <view class="uni-list-cell uni-list-cell-pd">
          <view class="uni-list-cell-db">是否显示取消按钮</view>
          <switch :checked="showCancelSelect" @change="showCancelChange" />
        </view>
        <view class="uni-list-cell uni-list-cell-pd">
          <view class="uni-list-cell-db">定制取消文案</view>
          <switch :checked="cancelTextSelect" @change="cancelTextChange" />
        </view>
        <view class="uni-list-cell uni-list-cell-pd">
          <view class="uni-list-cell-db">定制确认文案</view>
          <switch :checked="confirmTextSelect" @change="confirmTextChange" />
        </view>
        <view class="uni-list-cell uni-list-cell-pd">
          <view class="uni-list-cell-db">是否显示输入框</view>
          <switch :checked="editableSelect" @change="editableChange" />
        </view>
        <view class="uni-list-cell uni-list-cell-pd">
          <view class="uni-list-cell-db">是否定制输入提示词</view>
          <switch :checked="placeholderTextSelect" @change="placeholderTextChange" />
        </view>
      </view>
      <view class="uni-padding-wrap uni-common-mt">
        <view class="uni-btn-v">
          <button class="uni-btn-v" type="default" @tap="modalTap" id="btn-modal-show">
            modal测试
          </button>
        </view>
        <text>{{ exeRet }}</text>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

# showModal 兼容性

Android iOS web
3.9.0 4.11 4.0

# 参见

相关 Bug

# uni.showActionSheet(options)

从底部向上弹出操作菜单

# 参数

名称 类型 必填 默认值 描述
options ShowActionSheetOptions 是 -
名称 类型 必备 默认值 描述
title string | null 否 - 菜单标题
alertText string | null 否 - 警示文案（同菜单标题, app无效）
itemList Array<string> 是 - 按钮的文字数组
itemColor string.ColorString | null 否 - 按钮的文字颜色，字符串格式（iOS默认为系统控件颜色）
popover Popover | null 否 - 大屏设备弹出原生选择按钮框的指示区域，默认居中显示
名称 类型 必备 默认值 描述
top number 是 - 指示区域坐标，使用原生 navigationBar 时一般需要加上 navigationBar 的高度
left number 是 - 指示区域坐标
width number 是 - 指示区域宽度
height number 是 - 指示区域高度
success (res: ShowActionSheetSuccess) => void | null 否 - uni.showActionSheet成功回调函数定义
fail (res: IPromptError) => void | null 否 - uni.showActionSheet成功回调函数定义
complete (res: any) => void | null 否 - uni.showActionSheet成功回调函数定义
# ShowActionSheetSuccess 的属性值
名称 类型 必备 默认值 描述
tapIndex number | null 否 - 用户点击的按钮，从上到下的顺序，从0开始
# IPromptError 的属性值
名称 类型 必备 默认值 描述
errCode 1 | 1001 是 - 错误码
- 1 撤销
- 1001 请求参数非法
errSubject string 是 - 统一错误主题（模块）名称
data any | null 否 - 错误信息中包含的数据
cause Error | null 否 - 源错误信息，可以包含多个错误，详见SourceError
errMsg string 是 - -

itemList，即actionsheet的列表项，在app和小程序上最多6项，超出会报错。在web上超出不报错，列表区变为可滚动。

# 示例

hello uni-app x

Template

Script

<template>
  <view>
    <page-head :title="title"></page-head>
    <view class="uni-list">
      <radio-group @change="radioChange">
        <radio class="uni-list-cell uni-list-cell-pd" v-for="(item, index) in items" :key="item.value"
          :class="index < items.length - 1 ? 'uni-list-cell-line': ''" :value="item.value" :checked="index === current">
          {{item.name}}
        </radio>
      </radio-group>
    </view>
    <view class="uni-list">
      <view class="uni-list-cell uni-list-cell-pd">
        <view class="uni-list-cell-db">自定义itemColor</view>
        <switch :checked="itemColorCustom" @change="itemColorChange" />
      </view>
      <view class="uni-list-cell uni-list-cell-pd">
        <view class="uni-list-cell-db">超长文本和空文本item</view>
        <switch :checked="itemContentLarge" @change="itemContentLargeChange" />
      </view>
      <view class="uni-list-cell uni-list-cell-pd">
        <view class="uni-list-cell-db">超过6个item</view>
        <switch :checked="itemNumLargeSelect" @change="itemNumLargeChange" />
      </view>
    </view>
    <view class="uni-padding-wrap">
      <view class="uni-btn-v">
        <button class="uni-btn-v" type="default" @tap="actionSheetTap" id="btn-action-sheet-show">弹出action sheet</button>
      </view>
    </view>
  </view>
</template>

# showActionSheet 兼容性

Android iOS web
3.9.0 4.11 4.0

# 参见

相关 Bug

# 通用类型

# GeneralCallbackResult

名称 类型 必备 默认值 描述
errMsg string 是 - 错误信息

# Bug & Tips

  • 目前web和App的弹窗UI风格不统一，后续会修复
本页导读
uni.showToast(options)
参数
示例
showToast 兼容性
参见
注意事项
uni.showLoading(options)
参数
示例
showLoading 兼容性
参见
uni.showModal(options)
参数
示例
showModal 兼容性
参见
uni.showActionSheet(options)
参数
示例
showActionSheet 兼容性
参见
通用类型
GeneralCallbackResult
Bug & Tips