Skip to content

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 或快捷方式 confirmLoadingcancelLoading 控制按钮级别的 loading 状态。

el-dialog 原生功能

useDialog 完全支持 el-dialog 的所有原生属性、事件和插槽,直接透传,无需额外配置。

生命周期钩子

useDialog 支持 ElDialog 的原生属性 beforeClose 和事件 @opened@closed,支持异步操作。

数据共享

onOpened 中获取的数据可以通过响应式变量在 defaultheaderfooter 等插槽中共享使用。所有插槽的渲染函数都通过闭包访问响应式状态。

全局配置

通过 useDialog(globalConfig) 传入全局配置,所有 dialog.use() 创建的实例都会继承全局配置,实例配置会覆盖全局配置。

多个弹窗实例

支持创建多个弹窗实例,自动管理 z-index(通过 DialogStack 自动分配和更新)。

API

组合式函数

useDialog

useDialog(globalConfig?)

创建弹窗实例管理器,支持全局配置。

参数:

参数说明类型默认值
globalConfig页面级别的全局配置,会被所有 dialog.use() 创建的实例继承DialogGlobalConfig-

返回值:

  • UseDialogReturn:包含 use 方法的对象
dialog.use(options)

创建弹窗实例。

参数:

参数说明类型默认值
options弹窗选项,会继承 useDialog() 传入的全局配置DialogOptions-

返回值:

  • DialogInstance:弹窗实例,包含 modelValueloadingbuttonLoadings 等响应式状态

DialogOptions

支持 ElDialog

拓展属性

参数说明类型默认值
content内容(支持字符串、VNode、组件、渲染函数)string | VNode | Component | (() => string | Component | VNode)-
scrollbarPropsel-scrollbar 的属性配置Partial<ElScrollbarProps>-
loadingPropsel-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 参数,通过闭包访问响应式状态
  • contentslots 的渲染函数通过闭包访问(从 dialog.use() 解构的变量),不接收 instance 参数
  • slots.default 优先级高于 content 属性

DialogInstance

属性说明类型
id唯一标识符string
modelValuev-model 绑定的响应式值(唯一控制方式)Ref<boolean>
loading弹窗加载状态(自动显示遮罩层)Ref<boolean>
buttonLoadings统一的按钮 loading 管理(响应式)Ref<Record<string, boolean>>
confirmLoading确认按钮 loading(快捷方式,计算属性)WritableComputedRef<boolean>
cancelLoading取消按钮 loading(快捷方式,计算属性)WritableComputedRef<boolean>

DialogGlobalConfig

支持 ElDialog 所有的属性。

拓展属性

参数说明类型默认值
scrollbarPropsel-scrollbar 的属性配置(全局配置)Partial<ElScrollbarProps>-
loadingPropsel-loading 的属性配置(全局配置)Partial<ElLoadingOptions>-

基于 Element Plus 构建