uni-app
uniCloud
HBuilder X
uniMPSdk
uni-app
uni-app
uniCloud
HBuilder X
uniMPSdk
English
Introduction
uni.showToast(options)
Parameters
ShowToastOptions Values
Example
showToast Compatibility
See also
注意事项
uni.showLoading(options)
Parameters
ShowLoadingOptions Values
Expand All

# uni.showToast(options)

显示消息提示框

# # Parameters

name type required default description
options ShowToastOptions YES - uni.showToast参数定义

# # ShowToastOptions Values

name type optinal default description
title string YES - 提示的内容，长度与 icon 取值有关。
icon string NO - icon值说明 success: 显示成功图标，error: 显示错误图标； fail: 显示错误图标，此时title文本无长度显示； exception: 显示异常图标，此时title文本无长度显示； loading: 显示加载图标；none: 不显示图标。
image string NO - 自定义图标的本地路径（app端暂不支持gif）
mask boolean NO - 是否显示透明蒙层，防止触摸穿透，默认：false
duration number NO - 提示的延迟时间，单位毫秒，默认：1500
position string NO - position值说明（仅App生效） top: 居上显示； center: 居中显示；bottom： 居底显示
success (res: ShowToastSuccess) => void NO - 接口调用成功的回调函数
fail (res: UniError) => void NO - 接口调用失败的回调函数
complete (res: any) => void NO - 接口调用结束的回调函数（调用成功、失败都会执行）

# # Example

hello uni-app x

<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">点击弹出默认toast</button>
       <button class="uni-btn-v" type="default" @tap="toastTapIconError">点击弹出设置icon的toast</button>
       <button class="uni-btn-v" type="default" @tap="toast2Tap">点击弹出设置duration的toast</button>
       <button class="uni-btn-v" type="default" @tap="toast3Tap">点击弹出显示loading的toast</button>
       <!-- #ifndef MP-ALIPAY -->
       <button class="uni-btn-v" type="default" @tap="toast4Tap">点击弹出显示自定义图片的toast</button>
       <!-- #endif -->
       <!-- #ifdef APP-PLUS -->
       <button class="uni-btn-v" type="default" @tap="toast5Tap">点击显示无图标的居底toast</button>
       <!-- #endif -->
       <button class="uni-btn-v" type="default" @tap="hideToast">点击隐藏toast</button>
     </view>
     <text>{{exeRet}}</text>
   </view>
 </view>
</template>
<script lang="uts">
 export default {
   data() {
     return {
       title: 'toast',
       exeRet: ''
     }
   },
   methods: {
     toast1Tap: function () {
       uni.showToast({
         title: "默认",
         success: (res) => {
           this.exeRet = "success:" + JSON.stringify(res) + new Date()
         },
         fail: (res) => {
           this.exeRet = "fail:" + JSON.stringify(res)
         },
       })
     },
     toastTapIconError: function () {
       uni.showToast({
         title: "默认",
         icon: 'error',
         success: (res) => {
           this.exeRet = "success:" + JSON.stringify(res) + new Date()
         },
         fail: (res) => {
           this.exeRet = "fail:" + JSON.stringify(res)
         },
       })
     },
     toast2Tap: function () {
       uni.showToast({
         title: "duration 3000",
         duration: 3000,
         success: (res) => {
           this.exeRet = "success:" + JSON.stringify(res) + new Date()
         },
         fail: (res) => {
           this.exeRet = "fail:" + JSON.stringify(res)
         },
       })
     },
     toast3Tap: function () {
       uni.showToast({
         title: "loading",
         icon: "loading",
         duration: 5000,
         success: (res) => {
           this.exeRet = "success:" + JSON.stringify(res) + new Date()
         },
         fail: (res) => {
           this.exeRet = "fail:" + JSON.stringify(res)
         },
       })
     },
     toast4Tap: function () {
       uni.showToast({
         title: "logo",
         image: "/static/uni.png",
         success: (res) => {
           this.exeRet = "success:" + JSON.stringify(res) + new Date()
         },
         fail: (res) => {
           this.exeRet = "fail:" + JSON.stringify(res)
         },
       })
     },
     // #ifdef APP-PLUS
     toast5Tap: function () {
       uni.showToast({
         title: "显示一段轻提示",
         position: 'bottom',
         success: (res) => {
           this.exeRet = "success:" + JSON.stringify(res) + new Date()
         },
         fail: (res) => {
           this.exeRet = "fail:" + JSON.stringify(res)
         },
       })
     },
     // #endif
     hideToast: function () {
       uni.hideToast()
     }
   }
 }
</script>

# # showToast Compatibility

Android version Android uni-app Android uni-app-x iOS version iOS uni-app iOS uni-app-x
4.4.4 √ 3.9.0 9.0 √ 3.9.0

# # See also

showToast

Related Bug

# 注意事项

  • position 参数android平台特别说明

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

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

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

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

# uni.showLoading(options)

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

# # Parameters

name type required default description
options ShowLoadingOptions YES - uni.showLoading参数定义

# # ShowLoadingOptions Values

name type optinal default description
title string YES - 提示的内容，长度与 icon 取值有关。
mask boolean NO - 是否显示透明蒙层，防止触摸穿透，默认：false
success (res: ShowLoadingSuccess) => void NO - 接口调用成功的回调函数
fail (res: UniError) => void NO - 接口调用失败的回调函数
complete (res: any) => void NO - 接口调用结束的回调函数（调用成功、失败都会执行）

# # Example

hello uni-app x

<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" class="radio-group">
         <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>
<script lang="uts">
type ItemType = {
 value : string
 name : string
}
export default {
 data() {
   return {
     title: 'loading',
     items: [
       {
         value: 'null',
         name: '无标题',
       },
       {
         value: '三秒后自动关闭',
         name: '普通标题',
       },
       {
         value: '超长文本内容，测试超出范围-超长文本内容，测试超出范围-三秒后自动关闭',
         name: '长标题',
       },
     ] as ItemType[],
     current: 0,
     maskSelect: false,
     titleSelect: "null"
   }
 },
 methods: {

   radioChange(e : RadioGroupChangeEvent) {
     const selected = this.items.find((item) : boolean => {
       return item.value == e.detail.value
     })
     if (selected != null) {
       this.titleSelect = selected.value
     }
   },
   maskChange: function (e : SwitchChangeEvent) {
     this.maskSelect = e.detail.value
   },
   showLoading: function () {

     console.log(this.titleSelect)
     if (this.titleSelect == "null") {
       uni.showLoading({
         title: "",
         mask: this.maskSelect
       });
     } else {
       uni.showLoading({
         title: this.titleSelect,
         mask: this.maskSelect
       });
     }
     setTimeout(() => {
       this.hideLoading();
     }, 3000);
   },
   hideLoading: function () {
     uni.hideLoading();
   }
 }
}
</script>

# # showLoading Compatibility

Android version Android uni-app Android uni-app-x iOS version iOS uni-app iOS uni-app-x
4.4.4 √ 3.9.0 9.0 √ 3.9.0

# # See also

showLoading

Related Bug

# uni.showModal(options)

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

# # Parameters

name type required default description
options ShowModalOptions YES - uni.showModal 参数定义

# # ShowModalOptions Values

name type optinal default description
title string NO - 提示的标题
content string NO - 提示的内容
showCancel boolean NO true
是否显示取消按钮，默认为 true
cancelText string NO - 取消按钮的文字，默认为"取消"
cancelColor string NO - 取消按钮的文字颜色，默认为"#000000"
confirmText string NO - 确定按钮的文字，默认为"确定"
confirmColor string NO - 确定按钮的文字颜色
editable boolean NO false
是否显示输入框
placeholderText string NO - 显示输入框时的提示文本
success (res: ShowModalSuccess) => void NO - 接口调用成功的回调函数
fail (res: UniError) => void NO - 接口调用失败的回调函数
complete (res: any) => void NO - 接口调用结束的回调函数（调用成功、失败都会执行）
# # ShowModalSuccess Values
name type optinal default description
confirm boolean YES - 为 true 时，表示用户点击了确定按钮
cancel boolean YES - 为 true 时，表示用户点击了取消（用于 Android 系统区分点击蒙层关闭还是点击取消按钮关闭）
content string NO - editable 为 true 时，用户输入的文本

# # Example

hello uni-app x

<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">
   					modal测试
   				</button>
   			</view>
   			<text>{{ exeRet }}</text>
   		</view>
   	</view>
   	<!-- #ifdef APP -->
   </scroll-view>
   <!-- #endif -->
</template>
<script lang="uts">
   type ItemType = {
   	value : string,
   	name : string,
   }
   export default {
   	data() {
   		return {
   			title: 'modal',
   			showCancelSelect: false,
   			cancelTextSelect: false,
   			confirmTextSelect: false,
   			editableSelect: false,
   			placeholderTextSelect: false,
   			exeRet: "",
   			items: [{
   				value: '标题',
   				name: '有标题'
   			},
   			{
   				value: '',
   				name: '无标题'
   			},
   			{
   				value: '超长标题测试内容，测试超过显示最大范围之后的样式-超长标题测试内容，测试超过显示最大范围之后的样式',
   				name: '超长标题'
   			}
   			] as ItemType[],
   			current: 0
   		}
   	},
   	methods: {
   		showCancelChange: function (e : SwitchChangeEvent) {
   			this.showCancelSelect = e.detail.value
   		},
   		cancelTextChange: function (e : SwitchChangeEvent) {
   			this.cancelTextSelect = e.detail.value
   		},
   		confirmTextChange: function (e : SwitchChangeEvent) {
   			this.confirmTextSelect = e.detail.value
   		},
   		editableChange: function (e : SwitchChangeEvent) {
   			this.editableSelect = e.detail.value
   		},
   		placeholderTextChange: function (e : SwitchChangeEvent) {
   			this.placeholderTextSelect = e.detail.value
   		},
   		radioChange(e : RadioGroupChangeEvent) {
   			for (let i = 0; i < this.items.length; i++) {
   				if (this.items[i].value === e.detail.value) {
   					this.current = i;
   					break;
   				}
   			}
   		},
   		modalTap: function () {
   			let cancelTextVal : string
   			let cancelColorVal = ''
   			if (this.cancelTextSelect) {
   				cancelTextVal = "修改后的取消文本"
   				cancelColorVal = "#ff00ff"
   			} else {
   				cancelTextVal = "取消"
   			}

   			let confirmTextVal = '确定'
   			let confirmColorVal = ''
   			if (this.confirmTextSelect) {
   				confirmTextVal = "修改后的确定文本"
   				confirmColorVal = "#00ffff"
   			}

   			let placeholderTextVal = ''
   			let contentVal = "弹窗内容，告知当前状态、信息和解决方法，描述文字尽量控制在三行内"
   			if (this.placeholderTextSelect) {
   				placeholderTextVal = "定制提示信息"
   				contentVal = ""
   			}
   			uni.showModal({
   				title: this.items[this.current].value,
   				editable: this.editableSelect,
   				placeholderText: placeholderTextVal,
   				content: contentVal,
   				showCancel: this.showCancelSelect,
   				cancelText: cancelTextVal,
   				cancelColor: cancelColorVal,
   				confirmText: confirmTextVal,
   				confirmColor: confirmColorVal,
   				success: (res) => {
   					this.exeRet = JSON.stringify(res)
   				},
   				fail: (res) => {
   					this.exeRet = JSON.stringify(res)
   				}
   			})

   		}

   	}
   }
</script>

# # showModal Compatibility

Android version Android uni-app Android uni-app-x iOS version iOS uni-app iOS uni-app-x
4.4.4 √ 3.9.0 9.0 √ 3.9.0

# # See also

showModal

Related Bug

# uni.showActionSheet(options)

从底部向上弹出操作菜单

# # Parameters

name type required default description
options ShowActionSheetOptions YES - uni.showActionSheet函数参数定义

# # ShowActionSheetOptions Values

name type optinal default description
title string NO - 菜单标题
alertText string NO - 警示文案（同菜单标题, app无效）
itemList Array<string> YES - 按钮的文字数组
itemColor string NO - 按钮的文字颜色，字符串格式（iOS默认为系统控件颜色）
popover Popover NO - 大屏设备弹出原生选择按钮框的指示区域，默认居中显示
success (res: ShowActionSheetSuccess) => void NO - 接口调用成功的回调函数
fail (res: UniError) => void NO - 接口调用失败的回调函数
complete (res: any) => void NO - 接口调用结束的回调函数（调用成功、失败都会执行）
# # Popover Values
name type optinal default description
top number YES - 指示区域坐标，使用原生 navigationBar 时一般需要加上 navigationBar 的高度
left number YES - 指示区域坐标
width number YES - 指示区域宽度
height number YES - 指示区域高度
# # ShowActionSheetSuccess Values
name type optinal default description
tapIndex number NO - 用户点击的按钮，从上到下的顺序，从0开始

# # Example

hello uni-app x

<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">弹出action sheet</button>
     </view>
   </view>
 </view>
</template>
<script lang="uts">
 type ItemType = {
   value : string,
   name : string,
 }
 export default {
   data() {
     return {
       title: 'action-sheet',
       itemColorCustom: false,
       itemContentLarge: false,
       itemNumLargeSelect: false,
       items: [{
         value: '标题',
         name: '有标题'
       },
       {
         value: '',
         name: '无标题'
       },
       {
         value: '超长标题测试内容，测试超过显示最大范围之后的样式-超长标题测试内容，测试超过显示最大范围之后的样式',
         name: '超长标题'
       }
       ] as ItemType[],
       current: 0,
     }
   },
   methods: {
     radioChange(e : RadioGroupChangeEvent) {
       for (let i = 0; i < this.items.length; i++) {
         if (this.items[i].value === e.detail.value) {
           this.current = i;
           break;
         }
       }
     },
     itemContentLargeChange: function (e : SwitchChangeEvent) {
       this.itemContentLarge = e.detail.value
     },
     itemColorChange: function (e : SwitchChangeEvent) {
       this.itemColorCustom = e.detail.value
     },
     itemNumLargeChange: function (e : SwitchChangeEvent) {
       this.itemNumLargeSelect = e.detail.value
     },
     actionSheetTap() {

       let itemInfo = ['item1', 'item2', 'item3', 'item4']

       if (this.itemContentLarge) {
         itemInfo = ['两个黄鹂鸣翠柳，一行白鹭上青天。窗含西岭千秋雪，门泊东吴万里船', '水光潋滟晴方好,山色空蒙雨亦奇。 欲把西湖比西子,淡妆浓抹总相宜', '']
       } 
       
       if (this.itemNumLargeSelect) {
         // 大量选项测试,不能超过6个元素 https://uniapp.dcloud.net.cn/api/ui/prompt.html#showactionsheet
         itemInfo = []
         for (var i = 1; i <= 10; i++) {
           itemInfo.push('两个黄鹂鸣翠柳，一行白鹭上青天');
         }
       }

       const that = this
       if (this.itemColorCustom) {
         uni.showActionSheet({
           title: this.items[this.current].value,
           itemList: itemInfo,
           itemColor: "#ff00ff",
           success: (e) => {
             console.log(e.tapIndex);
             uni.showToast({
               title: "点击了第" + e.tapIndex + "个选项",
               icon: "none"
             })
           },
           fail: (e) => {
             console.log(e);
           }
         })
       } else {
         uni.showActionSheet({
           title: this.items[this.current].value,
           itemList: itemInfo,
           success: (e) => {
             console.log(e.tapIndex);
             uni.showToast({
               title: "点击了第" + e.tapIndex + "个选项",
               icon: "none"
             })
           },
           fail: (e) => {
             console.log(e);
             uni.showToast({
               title: e.errMsg,
               icon: "none"
             })
           }
         })
       }
     },
   }
 }
</script>

# # showActionSheet Compatibility

Android version Android uni-app Android uni-app-x iOS version iOS uni-app iOS uni-app-x
4.4.4 √ 3.9.0 9.0 √ 3.9.0

# # See also

showActionSheet

Related Bug

# # General type

# # GeneralCallbackResult

name type optinal default description
errMsg string YES - 错误信息

# Bug & Tips

  • 在页面生命周期 onLoad 中调用以上弹窗 API 可能无法正常显示，暂时建议在页面生命周期 onReady 及之后再调用。此bug已于HBuilderX 3.97+修复
On This Page
uni.showToast(options)
Parameters
ShowToastOptions Values
Example
showToast Compatibility
See also
注意事项
uni.showLoading(options)
Parameters
ShowLoadingOptions Values
Example
showLoading Compatibility
See also
uni.showModal(options)
Parameters
ShowModalOptions Values
Example
showModal Compatibility
See also
uni.showActionSheet(options)
Parameters
ShowActionSheetOptions Values
Example
showActionSheet Compatibility
See also
General type
GeneralCallbackResult
Bug & Tips