uView Next
4.1.6

外观

Modal 模态框

约 1809 字大约 6 分钟

2025-10-31

弹出模态框，常用于消息提示、消息确认、在当前页面内完成特定的交互操作。

基本使用

默认情况下，模态框只有一个确认按钮：

  • 请至少要配置弹框的内容参数content。
  • 通过show绑定一个布尔变量来控制模态框的显示与否。
<template>
	<view >
		<un-modal :show="show" :title="title" :content='content'></un-modal>
		<un-button @click="show = true">打开</un-button>
	</view>
</template>

<script setup lang="ts">
	import { ref } from 'vue'
	
	const show = ref(false)
	const title = ref('标题')
	const content = ref('uView的目标是成为uni-app生态最优秀的UI框架')
</script>

传入富文本内容

有时候我们需要给模态框的内容，不一定是纯文本的字符串，可能会需要换行，嵌入其他元素等，这时候我们可以使用slot功能，再结合uni-apprictText组件， 就能传入富文本内容了，如下演示：

<template>
	<view >
		<un-modal :show="show"  :title="title" >
			<view class="slot-content">
				<rich-text :nodes="content"></rich-text>
			</view>
		</un-modal>
		<un-button @click="show = true">打开</un-button>
	</view>
</template>

<script setup lang="ts">
	import { ref } from 'vue'
	
	const show = ref(false)
	const title = ref('标题')
	const content = ref(`空山新雨后<br>
					天气晚来秋`)
</script>

异步关闭

异步关闭只对"确定"按钮起作用，需要设置asyncClose为true，当点击确定按钮的时候，按钮的文字变成一个loading动画，此动画的颜色为 confirm-color参数的颜色，同时Modal不会自动关闭，需要手动设置通过show绑定的变量为false来实现手动关闭。

<template>
	<view class="">
		<un-modal :show="show" @confirm="confirm" ref="uModal" :asyncClose="true"></un-modal>
		<un-button @click="showModal">弹起Modal</un-button>
	</view>
</template>

<script setup lang="ts">
	import { ref } from 'vue'
	
	const show = ref(false)
	
	const showModal = () => {
		show.value = true
	}
	
	const confirm = () => {
		setTimeout(() => {
			// 3秒后自动关闭
			show.value = false
		}, 3000)
	}
</script>

点击遮罩关闭

有时候我们不显示"关闭"按钮的时候，需要点击遮罩也可以关闭Modal，这时通过配置closeOnClickOverlay为true即可（注意：关闭事件需要自行处理，只会在开启closeOnClickOverlay后点击遮罩层执行close回调）

<un-modal :show="show" :closeOnClickOverlay="true"></un-modal>

控制模态框宽度

可以通过设置width参数控制模态框的宽度，不支持百分比，可以数值，px，rpx单位

<un-modal v-model="show" width="300px"></un-modal>

缩放效果

开启缩放效果，在打开和收起模态框的时候，会带有缩放效果，具体效果请见示例，此效果默认开启，通过zoom参数配置

<un-modal v-model="show" :zoom="false"></un-modal>

API

Props

注意：需要给modal组件通过show绑定一个布尔值，来初始化modal的状态，随后该值被双向绑定。

参数说明类型默认值
show是否显示模态框booleanfalse
title标题内容string-
content模态框内容，如传入slot内容，则此参数无效string-
confirmText确认按钮的文字string确认
cancelText取消按钮的文字string取消
showConfirmButton是否显示确认按钮booleantrue
showCancelButton是否显示取消按钮booleanfalse
confirmColor确认按钮的颜色string#2979ff
cancelColor取消按钮的颜色string#606266
duration弹窗动画过度时间string | number200
buttonReverse对调确认和取消的位置booleanfalse
zoom是否开启缩放模式booleantrue
zIndex弹出层的z-index值string | number10075
asyncClose是否异步关闭，只对确定按钮有效booleanfalse
closeable v4.1.6是否显示关闭图标booleanfalse
closeOnClickOverlay是否允许点击遮罩关闭Modalbooleanfalse
negativeTop往上偏移的值，避免和键盘重合的情况string | number0
widthmodal宽度，不支持百分比string | number320px
confirmButtonShape确认按钮的样式string100px
round设置圆角值string6px
buttonModel按钮模式
Enum
text
buttonRadius按钮圆角，仅按钮模式有效string100px
confirmBgColor确认按钮背景颜色，仅按钮模式有效string-
cancelBgColor取消按钮背景颜色，仅按钮模式有效string-
customStyle自定义样式string | object-

Methods

方法名说明类型
open显示Modal
Function
close隐藏Modal
Function

Event

事件名说明类型
confirm点击确认按钮时触发
Function
cancel点击取消按钮时触发
Function
close点击遮罩关闭触发，closeOnClickOverlay为true有效
Function

Slots

名称说明
default传入自定义内容，一般为富文本，见上方说明
confirmButton传入自定义按钮，用于在微信小程序弹窗通过按钮授权的场景

数据类型

type UnModalOptions = {
  title?: string; // 标题
  content?: string; // 弹窗内容
  confirmText?: string; // 确认文案
  cancelText?: string; // 取消文案
  showConfirmButton?: boolean; // 是否显示确认按钮
  showCancelButton?: boolean; // 是否显示取消按钮
  confirmColor?: string; // 确认按钮颜色
  cancelColor?: string; // 取消文字颜色
  buttonReverse?: boolean; // 对调确认和取消的位置
  confirmBgColor?: string; // 确认按钮背景颜色
  cancelBgColor?: string; // 取消按钮背景颜色
  buttonRadius?: string; // 确认按钮圆角
  buttonModel?: string; // 按钮模式
  zoom?: boolean; // 是否开启缩放效果
  zIndex?: string | number; // 层级
  asyncClose?: boolean; // 是否异步关闭，只对确定按钮有效
  closeOnClickOverlay?: boolean; // 是否允许点击遮罩关闭modal
  negativeTop?: string | number; // 给一个负的margin-top，往上偏移，避免和键盘重合的情况
  width?: string | number; // modal宽度，不支持百分比，可以数值，px，rpx单位
  confirmButtonShape?: string; // 确认按钮的样式
  duration?: string | number; // 弹窗动画过度时间
  round?: string; // 设置圆角值
  success?: (result: UnShowModalResult) => void; // 打开后回调
  fail?: (result: UnShowModalFail) => void; // 失败后回调
  customStyle?: string | object; // 自定义样式
}

type UnShowModalResult = {
  cancel: boolean; // 是否取消
  confirm: boolean; // 是否确认
}

type UnShowModalFail = {
  errCode: number; // 错误码
  errSubject: string; // 错误主题
  errMsg: string; // 错误信息
}

Scss 变量

变量名默认值说明
$un-modal-width325px模态框宽度
$un-modal-border-radius$radius-base模态框圆角
$un-modal-title-font-size$text-lg标题文字大小
$un-modal-title-font-weight$font-bold标题文字粗细
$un-modal-title-color$text-color标题文字颜色
$un-modal-title-padding-top15px标题上边距
$un-modal-content-padding30px内容区域内边距
$un-modal-content-text-font-size$text-base内容文字大小
$un-modal-content-text-color$text-color内容文字颜色
$un-modal-button-text-height48px文字模式按钮高度
$un-modal-button-height36px按钮模式按钮高度
$un-modal-button-margin0 10px按钮外边距
$un-modal-button-cancel-bg-color$color-info-light取消按钮背景颜色
$un-modal-button-confirm-bg-color$color-primary确认按钮背景颜色
$un-modal-button-text-color$text-color按钮文字颜色
$un-modal-button-text-font-size$text-base按钮文字大小
$un-modal-button-text-hover-bg-color$bg-color按钮文字模式hover背景颜色
$un-modal-button-text-cancel-color$text-color文字模式取消按钮颜色
$un-modal-button-text-confirm-color$color-primary文字模式确认按钮颜色
$un-modal-button-margin-bottom20px按钮底部外边距
$un-modal-button-padding0 10px按钮内边距
$un-modal-button-hover-opacity0.8按钮hover透明度

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next