Dialog 弹窗
基于 Element Plus Dialog 的封装组件,提供组合式函数 useDialog,支持完全独立使用,无需在模板中添加组件。
基础用法
useDialog 组合式函数完全独立使用,弹窗自动渲染到 DOM,无需在模板中添加任何组件。
content 属性
content 属性支持多种类型:字符串、VNode、组件、渲染函数。渲染函数通过闭包访问响应式状态,不接收 instance 参数。
插槽使用
使用 slots 属性自定义弹窗的头部、内容、底部等区域。所有插槽函数通过闭包访问响应式状态,不接收 instance 参数。slots.default 优先级高于 content 属性。
弹窗 Loading
通过 instance.loading.value = true/false 控制弹窗 loading 状态,loading 遮罩层只作用在弹窗内容区域,不是整个弹窗。
自定义 Loading 配置
通过 loadingProps 自定义 el-loading 配置,保持与 el-loading 原生行为一致。
scrollbarProps 配置
通过 scrollbarProps 配置 el-scrollbar 属性,控制内容区域的滚动行为。el-scrollbar 始终内置使用,提供统一的滚动体验。
按钮 Loading
通过 buttonLoadings 或快捷方式 confirmLoading、cancelLoading 控制按钮级别的 loading 状态。
el-dialog 原生功能
useDialog 完全支持 el-dialog 的所有原生属性、事件和插槽,直接透传,无需额外配置。
生命周期钩子
useDialog 支持 ElDialog 的原生属性 beforeClose 和事件 @opened、@closed,支持异步操作。
数据共享
在 onOpened 中获取的数据可以通过响应式变量在 default、header、footer 等插槽中共享使用。所有插槽的渲染函数都通过闭包访问响应式状态。
全局配置
通过 useDialog(globalConfig) 传入全局配置,所有 dialog.use() 创建的实例都会继承全局配置,实例配置会覆盖全局配置。
多个弹窗实例
支持创建多个弹窗实例,自动管理 z-index(通过 DialogStack 自动分配和更新)。
API
组合式函数
useDialog
useDialog(globalConfig?)
创建弹窗实例管理器,支持全局配置。
参数:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| globalConfig | 页面级别的全局配置,会被所有 dialog.use() 创建的实例继承 | DialogGlobalConfig | - |
返回值:
UseDialogReturn:包含use方法的对象
dialog.use(options)
创建弹窗实例。
参数:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| options | 弹窗选项,会继承 useDialog() 传入的全局配置 | DialogOptions | - |
返回值:
DialogInstance:弹窗实例,包含modelValue、loading、buttonLoadings等响应式状态
DialogOptions
支持 ElDialog。
拓展属性:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| content | 内容(支持字符串、VNode、组件、渲染函数) | string | VNode | Component | (() => string | Component | VNode) | - |
| scrollbarProps | el-scrollbar 的属性配置 | Partial<ElScrollbarProps> | - |
| loadingProps | el-loading 的属性配置 | Partial<ElLoadingOptions> | - |
| slots | 插槽(header、footer、title、default) | { default?: () => VNode, header?: () => VNode, footer?: () => VNode, title?: () => VNode } | - |
| onConfirm | 确认按钮钩子(可选) | () => void | Promise<void> | - |
| onCancel | 取消按钮钩子(可选) | () => void | - |
| loading | 弹窗 loading 状态(可选,如果传入则使用用户的,否则使用内部的) | Ref<boolean> | - |
| buttonLoadings | 按钮 loading 状态(可选,如果传入则使用用户的,否则使用内部的) | Ref<Record<string, boolean>> | - |
注意:
- 生命周期钩子(
beforeClose、@opened、@closed)直接使用ElDialog的原生支持,无需额外定义 @opened和@closed事件不接收instance参数,通过闭包访问响应式状态content和slots的渲染函数通过闭包访问(从dialog.use()解构的变量),不接收instance参数slots.default优先级高于content属性
DialogInstance
| 属性 | 说明 | 类型 |
|---|---|---|
| id | 唯一标识符 | string |
| modelValue | v-model 绑定的响应式值(唯一控制方式) | Ref<boolean> |
| loading | 弹窗加载状态(自动显示遮罩层) | Ref<boolean> |
| buttonLoadings | 统一的按钮 loading 管理(响应式) | Ref<Record<string, boolean>> |
| confirmLoading | 确认按钮 loading(快捷方式,计算属性) | WritableComputedRef<boolean> |
| cancelLoading | 取消按钮 loading(快捷方式,计算属性) | WritableComputedRef<boolean> |
DialogGlobalConfig
支持 ElDialog 所有的属性。
拓展属性:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| scrollbarProps | el-scrollbar 的属性配置(全局配置) | Partial<ElScrollbarProps> | - |
| loadingProps | el-loading 的属性配置(全局配置) | Partial<ElLoadingOptions> | - |