Dialog 对话框
uni-appH5微信小程序App
跨端确认对话框,支持标题、底部操作区和遮罩关闭。
何时使用
需要用户确认或处理的关键操作:删除确认、表单弹窗、重要提示。
何时不使用
轻量反馈用 Toast;复杂多步流程考虑抽屉或独立页面;移动端底部操作用 ActionSheet。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | boolean | false | 是否显示,使用 v-model 双向绑定:v-model="visible" |
title | string | "" | 标题文本;可用 title 插槽覆盖 |
maskClosable | boolean | true | 点击遮罩是否关闭 |
showClose | boolean | true | 是否显示右上角 × 关闭按钮 |
showFooter | boolean | true | 是否显示底部按钮区;置 false 并配合 footer 插槽可完全自定义 |
confirmText | string | "确定" | 确定按钮文案 |
cancelText | string | "取消" | 取消按钮文案 |
zIndex | number | 1001 | 弹层层级 |
width | string | "420px" | 面板宽度;移动端(<768px)自动全宽贴底,此值不生效 |
beforeClose | (done: () => void) => void | - | 关闭前钩子:所有关闭途径(遮罩/×/Escape/取消/确定)都会先调用它,调用 done() 后才真正关闭;用于异步确认或表单校验。多弹层时 z-index 由内部递增管理 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | boolean | 显隐变化时触发,配合 v-model 使用 |
confirm | void | 点击确定按钮时触发,随后对话框关闭 |
cancel | void | 点击取消按钮时触发,随后对话框关闭 |
close | void | 任何途径关闭时触发(确定/取消/遮罩/×/Escape) |
Slots
| 名称 | 说明 |
|---|---|
default | 对话框内容 |
title | 标题区域 |
footer | 底部操作区 |
示例
基础用法
vue
<Button variant="primary" @click="visible = true">打开对话框</Button>
<Dialog v-model="visible" title="提示">
<Text>确认要提交本月的工时报表吗?</Text>
</Dialog>自定义底部
vue
<Button variant="secondary" @click="visible2 = true">自定义底部</Button>
<Dialog v-model="visible2" title="删除确认" :show-footer="false">
<Text variant="secondary">删除后不可恢复,请谨慎操作。</Text>
<template #footer><view class="row">
<Button variant="ghost" block @click="visible2 = false">再想想</Button>
<Button variant="danger" block @click="visible2 = false">删除</Button>
</view></template>
</Dialog>隐藏关闭按钮
vue
<Button variant="ghost" @click="visible3 = true">强确认</Button>
<Dialog v-model="visible3" title="协议更新" :show-close="false" :mask-closable="false">
<Text>请阅读并同意新版用户协议后继续。</Text>
</Dialog>宽度与关闭前拦截
vue
<Button variant="primary" @click="visible4 = true">拦截关闭</Button>
<Dialog v-model="visible4" title="确认提交" width="86%" :before-close="beforeClose" />