Dialog 对话框

通过 v-model 控制的模态内容容器。组件负责遮罩、Escape、焦点进入与恢复、滚动锁和过渡事件；表单数据及提交逻辑由业务层维护。

Dialog 面板统一读取全局或局部的 soft、clear、solid 材质设置，内部 Aurora Plus 组件继承同一材质上下文。模态交互层保持完全透明，不改变对话框之外的页面亮度；面板自身使用背景模糊、细边框和通用浮层阴影表达层级。

系统启用“减少透明度”时，玻璃会自动切换为不透明表面并关闭背景模糊；高对比度模式还会增强边界和分隔线。

打开时默认聚焦对话框容器，不会自动聚焦关闭按钮。需要让表单控件或操作按钮获得初始焦点时，在目标元素上显式添加 autofocus。

基础用法

编辑项目资料

表单绑定 draftProfile，并通过底部操作区完成取消或保存。

vue

<template>
  <div>
    <AuButton type="primary" @click="dialogVisible = true">编辑项目资料</AuButton>
    <AuDialog
      v-model="dialogVisible"
      title="编辑项目资料"
      width="520px"
      close-on-click-modal
    >
      <form class="dialog-demo__form" @submit.prevent="saveProfile">
        <label>
          <span>项目名称</span>
          <input v-model.trim="draftProfile.name" autofocus />
        </label>
        <label>
          <span>项目说明</span>
          <textarea v-model.trim="draftProfile.description" rows="3"></textarea>
        </label>
      </form>
      <template #footer>
        <AuButton @click="dialogVisible = false">取消</AuButton>
        <AuButton type="primary" :disabled="!draftProfile.name" @click="saveProfile">保存</AuButton>
      </template>
    </AuDialog>
  </div>
</template>
<script setup>
import { reactive, ref } from 'vue';
import { AuButton, AuDialog } from 'aurora-plus';
const dialogVisible = ref(false);
const draftProfile = reactive({
  name: 'Aurora Editor',
  description: '一个专注 Markdown 编辑体验的桌面应用。',
});
function saveProfile() {
  if (!draftProfile.name) return;
  dialogVisible.value = false;
}
</script>
<style scoped>
.dialog-demo__form,
.dialog-demo__form label {
  display: grid;
  gap: 14px;
}
.dialog-demo__form label {
  gap: 7px;
  color: var(--au-color-text-regular);
  font-size: 13px;
}
.dialog-demo__form input,
.dialog-demo__form textarea {
  width: 100%;
  padding: 9px 11px;
  border: 1px solid var(--au-color-border);
  border-radius: var(--au-border-radius-base);
  color: var(--au-color-text-primary);
  background: transparent;
  outline: none;
  resize: vertical;
}
.dialog-demo__form input:focus,
.dialog-demo__form textarea:focus {
  border-color: var(--au-color-primary);
}
</style>

Dialog API

Attributes

属性	说明	类型	默认值
modelValue / v-model	是否显示	boolean	true
title	默认标题	string	''
width	宽度；数字转换为 px	string / number	min(560px, calc(100vw - 32px))
height	固定高度；数字转换为 px	string / number	''
maxHeight	最大高度；数字转换为 px	string / number	90vh
top	对话框顶部外边距；数字转换为 px	string / number	''
modal	是否启用透明模态交互层并设置 aria-modal	boolean	true
lockScroll	显示期间是否锁定页面滚动	boolean	true
appendToBody	是否 Teleport 到 body	boolean	true
closeOnClickModal	点击遮罩是否关闭	boolean	false
closeOnOverlay	closeOnClickModal 的兼容属性	boolean	false
closeOnPressEscape	按 Escape 是否关闭	boolean	true
showClose	是否显示右上角关闭按钮	boolean	true
closeLabel	关闭按钮提示和无障碍名称	string	关闭
zIndex	遮罩层级	number	10000

Events

事件名	说明	参数
update:modelValue	内部请求关闭时更新绑定值	(visible: boolean)
open	开始打开时触发	—
opened	打开过渡结束后触发	—
close	组件内部触发关闭时调用	(reason: DialogCloseReason)
closed	关闭过渡结束后触发	—

DialogCloseReason 为 api、overlay、escape 或 close-button。父组件直接把 v-model 改为 false 时不会额外触发 close。

Slots

插槽名	作用域参数	说明
default	{ close }	对话框正文
header	{ close }	自定义标题区域
footer	{ close }	底部操作区；未提供时不渲染 footer

Exposes

属性或方法	说明
close(reason?)	从组件实例主动关闭，默认 reason 为 api
dialogRef	对话框内容根元素引用