Appearance
Dialog 对话框组件是基于 Element Plus 的 el-dialog 组件封装而成，用于在保留当前页面状态的情况下，告知用户并承载相关操作。
INFO
Dialog 组件完全继承了 Element Plus Dialog 组件的所有属性和事件，因此支持所有 Element Plus Dialog 组件的功能，包括自定义头部、底部、居中布局、全屏显示等高级特性。
插槽命名规则
Dialog 组件的插槽使用 dialog-{slotName} 格式，其中 slotName 对应 Element Plus el-dialog 组件的插槽名称。例如：
dialog-header对应el-dialog的header插槽dialog-footer对应el-dialog的footer插槽dialog-default对应el-dialog的default插槽（也可以直接使用默认插槽）
基础用法
Dialog 通过 v-model 控制显示和隐藏。你可以通过 title 属性设置对话框标题，通过 width 属性设置对话框宽度。使用 before-close 属性可以设置关闭前的回调函数。
loading
嵌套内容
Dialog 组件可以嵌套表格、表单等复杂内容。你可以根据实际需求在对话框内容区域放置任何内容。
loading
自定义头部
通过 dialog-header 插槽可以自定义对话框头部。插槽提供了 close、titleId、titleClass 等参数，方便你自定义关闭按钮和标题样式。你可以通过 show-close 属性控制是否显示默认的关闭按钮。
loading
居中布局
通过 center 属性可以让对话框的头部和底部居中显示。
loading
关闭时销毁
通过 destroy-on-close 属性可以在对话框关闭时销毁其中的元素。这在对话框内容较多或包含复杂组件时，可以提升性能。
loading
全屏对话框
通过 fullscreen 属性可以让对话框全屏显示。
loading
属性说明
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue / v-model | Boolean | false | 是否显示对话框，使用 v-model 进行双向绑定 |
title | String | '' | 对话框标题，也可以通过 dialog-header 插槽自定义 |
width | String | Number | '50%' | 对话框宽度，支持百分比和像素值 |
fullscreen | Boolean | false | 是否全屏显示对话框 |
top | String | '15vh' | 对话框距离顶部的位置 |
modal | Boolean | true | 是否显示遮罩层 |
modal-class | String | '' | 遮罩层的自定义类名 |
append-to-body | Boolean | false | 是否将对话框插入到 body 元素上 |
lock-scroll | Boolean | true | 是否在对话框出现时将 body 滚动锁定 |
custom-class | String | '' | 对话框的自定义类名 |
open-delay | Number | 0 | 对话框打开的延时时间，单位毫秒 |
close-delay | Number | 0 | 对话框关闭的延时时间，单位毫秒 |
close-on-click-modal | Boolean | true | 是否可以通过点击遮罩层关闭对话框 |
close-on-press-escape | Boolean | true | 是否可以通过按下 ESC 键关闭对话框 |
show-close | Boolean | true | 是否显示关闭按钮 |
before-close | Function | undefined | 关闭前的回调函数，会暂停对话框的关闭。回调函数执行后才会关闭对话框。接收 done 函数作为参数，调用 done() 后才会关闭对话框 |
center | Boolean | false | 是否对头部和底部采用居中布局 |
destroy-on-close | Boolean | false | 当关闭对话框时，销毁其中的元素 |
draggable | Boolean | false | 是否可拖拽对话框 |
align-center | Boolean | false | 是否水平垂直居中对话框 |
| 其他属性 | - | - | 支持透传 Element Plus el-dialog 组件的所有属性 |
TIP
- 组件完全兼容 Element Plus Dialog 的所有属性和功能
- 可以参考 Element Plus Dialog 文档 了解更多高级用法
before-close回调函数接收一个done函数作为参数，必须调用done()才会关闭对话框width属性支持字符串（如'500px'、'50%'）和数字（如500，单位为像素）
插槽说明
组件支持通过插槽自定义对话框的各个部分。插槽命名规则为 dialog-{slotName}，其中 slotName 对应 Element Plus el-dialog 组件的插槽名称。
| 插槽名 | 说明 | 作用域参数 |
|---|---|---|
dialog-header | 自定义对话框头部内容 | { close, titleId, titleClass } - close 为关闭对话框的函数，titleId 为标题的 id，titleClass 为标题的类名 |
dialog-footer | 自定义对话框底部内容 | - |
dialog-default | 对话框的主要内容（也可以直接使用默认插槽） | - |
TIP
- 插槽名称必须以
dialog-开头，后面的部分会作为el-dialog的插槽名 - 可以直接使用默认插槽来定义对话框内容，效果与
dialog-default相同 dialog-header插槽提供了close函数，可以在自定义头部中调用它来关闭对话框- 如果使用了
dialog-header插槽，建议设置show-close="false"来隐藏默认的关闭按钮
事件说明
| 事件名 | 说明 | 回调参数 | 触发时机 |
|---|---|---|---|
open | 对话框打开时触发 | - | 对话框打开动画开始时触发 |
opened | 对话框打开动画结束时触发 | - | 对话框打开动画完全结束后触发 |
close | 对话框关闭时触发 | - | 对话框关闭动画开始时触发 |
closed | 对话框关闭动画结束时触发 | - | 对话框关闭动画完全结束后触发 |
update:modelValue | 绑定值更新时触发（用于 v-model 双向绑定） | (value: Boolean) - 新的值 | 当 modelValue 值发生变化时触发，用于实现双向绑定 |
open-auto-focus | 对话框打开后，焦点自动聚焦到对话框内时触发 | - | 对话框打开后，焦点自动聚焦到对话框内时触发 |
close-auto-focus | 对话框关闭后，焦点自动聚焦到触发元素上时触发 | - | 对话框关闭后，焦点自动聚焦到触发元素上时触发 |
TIP
open和opened的区别：open在打开动画开始时触发，opened在打开动画完全结束后触发close和closed的区别：close在关闭动画开始时触发，closed在关闭动画完全结束后触发- 组件完全兼容 Element Plus Dialog 的所有事件，可以参考 Element Plus Dialog 文档 了解更多事件
高级功能
由于组件完全继承了 Element Plus Dialog 的所有功能，因此支持以下高级特性：
可拖拽
通过设置 draggable 属性，可以让对话框可以通过拖拽移动位置。
居中显示
通过设置 align-center 属性，可以让对话框在页面中水平垂直居中显示。
自定义遮罩层
通过设置 modal-class 属性，可以自定义遮罩层的样式类名。
关闭前确认
通过设置 before-close 属性，可以在对话框关闭前执行一些操作（如确认提示），只有调用 done() 函数后才会真正关闭对话框。
嵌套对话框
Dialog 组件支持嵌套使用，可以在一个对话框内打开另一个对话框。
注意事项
显示控制：
- 使用
v-model进行双向绑定，这是推荐的方式 modelValue的值必须是布尔类型，true表示显示，false表示隐藏
- 使用
插槽使用：
- 插槽名称必须以
dialog-开头，例如dialog-header、dialog-footer - 可以直接使用默认插槽来定义对话框内容
- 如果使用了
dialog-header插槽，建议设置show-close="false"来隐藏默认的关闭按钮
- 插槽名称必须以
关闭前回调：
before-close回调函数必须接收一个done函数作为参数- 只有调用
done()后，对话框才会真正关闭 - 如果不调用
done()，对话框将保持打开状态
性能优化：
- 如果对话框内容较多或包含复杂组件，建议设置
destroy-on-close="true"，在关闭时销毁内容以提升性能 - 对于频繁打开关闭的对话框，可以考虑使用
v-if来控制组件的创建和销毁
- 如果对话框内容较多或包含复杂组件，建议设置
Element Plus 兼容性：
- 组件完全兼容 Element Plus Dialog 的所有功能和 API
- 可以参考 Element Plus Dialog 文档 了解更多高级用法
- 支持透传 Element Plus
el-dialog的所有属性和事件
样式定制：
- 可以通过
custom-class属性添加自定义类名来定制对话框样式 - 可以通过
modal-class属性定制遮罩层样式
- 可以通过
常见问题
Q: 为什么我的对话框无法关闭？
A: 请检查以下几点：
- 确保
v-model绑定的值可以正常更新 - 如果设置了
before-close回调，确保在回调中调用了done()函数 - 检查是否设置了
close-on-click-modal="false"和close-on-press-escape="false"，导致无法通过点击遮罩层或按 ESC 键关闭
Q: 如何自定义对话框头部？
A: 使用 dialog-header 插槽可以自定义头部内容。插槽提供了 close、titleId、titleClass 等参数。如果使用了自定义头部，建议设置 show-close="false" 来隐藏默认的关闭按钮。
Q: before-close 回调函数如何使用？
A: before-close 回调函数接收一个 done 函数作为参数。你可以在回调中执行一些操作（如确认提示），然后调用 done() 来关闭对话框。如果不调用 done()，对话框将保持打开状态。
Q: 对话框内容很多时如何优化性能？
A: 建议设置 destroy-on-close="true"，这样在对话框关闭时会销毁其中的元素，下次打开时重新创建，可以提升性能。但需要注意，如果对话框内容包含表单等需要保持状态的内容，可能不适合使用此属性。
Q: 如何实现嵌套对话框？
A: Dialog 组件支持嵌套使用，只需要在一个对话框的内容区域放置另一个 Dialog 组件即可。注意控制好每个对话框的 v-model 值。
Q: 如何让对话框居中显示？
A: 可以通过设置 align-center 属性让对话框在页面中水平垂直居中显示。也可以通过设置 center 属性让对话框的头部和底部内容居中显示。
最佳实践
- 使用
v-model进行双向绑定：这是 Vue 3 推荐的方式，代码更简洁 - 合理使用
before-close：在需要关闭前确认的场景（如未保存的表单），使用before-close来提示用户 - 性能优化：对于内容较多或包含复杂组件的对话框，使用
destroy-on-close来优化性能 - 自定义头部和底部：根据业务需求，使用插槽自定义对话框的头部和底部，提供更好的用户体验
- 响应式设计：使用百分比或响应式单位来设置对话框宽度，适配不同屏幕尺寸
- 无障碍访问：使用
dialog-header插槽时，确保正确使用titleId和titleClass，以提供良好的无障碍访问体验