外观
Modal 模态框
约 1794 字大约 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 | 是否显示模态框 | boolean | false |
| title | 标题内容 | string | - |
| content | 模态框内容，如传入slot内容，则此参数无效 | string | - |
| confirmText | 确认按钮的文字 | string | 确认 |
| cancelText | 取消按钮的文字 | string | 取消 |
| showConfirmButton | 是否显示确认按钮 | boolean | true |
| showCancelButton | 是否显示取消按钮 | boolean | false |
| confirmColor | 确认按钮的颜色 | string | #2979ff |
| cancelColor | 取消按钮的颜色 | string | #606266 |
| duration | 弹窗动画过度时间 | string | number | 200 |
| buttonReverse | 对调确认和取消的位置 | boolean | false |
| zoom | 是否开启缩放模式 | boolean | true |
| zIndex | 弹出层的z-index值 | string | number | 10075 |
| asyncClose | 是否异步关闭，只对确定按钮有效 | boolean | false |
| closeOnClickOverlay | 是否允许点击遮罩关闭Modal | boolean | false |
| negativeTop | 往上偏移的值，避免和键盘重合的情况 | string | number | 0 |
| width | modal宽度，不支持百分比 | string | number | 320px |
| confirmButtonShape | 确认按钮的样式 | string | 100px |
| round | 设置圆角值 | string | 6px |
| buttonModel | 按钮模式 | Enum | text |
| buttonRadius | 按钮圆角，仅按钮模式有效 | string | 100px |
| 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-width | 325px | 模态框宽度 |
| $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-top | 15px | 标题上边距 |
| $un-modal-content-padding | 30px | 内容区域内边距 |
| $un-modal-content-text-font-size | $text-base | 内容文字大小 |
| $un-modal-content-text-color | $text-color | 内容文字颜色 |
| $un-modal-button-text-height | 48px | 文字模式按钮高度 |
| $un-modal-button-height | 36px | 按钮模式按钮高度 |
| $un-modal-button-margin | 0 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-bottom | 20px | 按钮底部外边距 |
| $un-modal-button-padding | 0 10px | 按钮内边距 |
| $un-modal-button-hover-opacity | 0.8 | 按钮hover透明度 |
提示
组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档