跳到主要内容

Dialog 对话框 ​

uni-appH5微信小程序App

跨端确认对话框,支持标题、底部操作区和遮罩关闭。

何时使用 ​

需要用户确认或处理的关键操作:删除确认、表单弹窗、重要提示。

何时不使用 ​

轻量反馈用 Toast;复杂多步流程考虑抽屉或独立页面;移动端底部操作用 ActionSheet。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
Dialog 对话框 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuebooleanfalse是否显示,使用 v-model 双向绑定:v-model="visible"
titlestring""标题文本;可用 title 插槽覆盖
maskClosablebooleantrue点击遮罩是否关闭
showClosebooleantrue是否显示右上角 × 关闭按钮
showFooterbooleantrue是否显示底部按钮区;置 false 并配合 footer 插槽可完全自定义
confirmTextstring"确定"确定按钮文案
cancelTextstring"取消"取消按钮文案
zIndexnumber1001弹层层级
widthstring"420px"面板宽度;移动端(<768px)自动全宽贴底,此值不生效
beforeClose(done: () => void) => void-关闭前钩子:所有关闭途径(遮罩/×/Escape/取消/确定)都会先调用它,调用 done() 后才真正关闭;用于异步确认或表单校验。多弹层时 z-index 由内部递增管理

Events ​

名称载荷说明
update:modelValueboolean显隐变化时触发,配合 v-model 使用
confirmvoid点击确定按钮时触发,随后对话框关闭
cancelvoid点击取消按钮时触发,随后对话框关闭
closevoid任何途径关闭时触发(确定/取消/遮罩/×/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" />