技术分享 | 弹窗开发中，如何使用 Hook 封装 el-dialog？
弹窗是前端开发中的一种常见需求。Element UI 框架中的 el-dialog 组件提供了弹窗相关的基本功能，但在实际开发中，我们难免会遇到一些定制化需求，比如对弹窗进行二次封装以便在项目中统一管理样式和行为。
本文将分享如何使用 useDialog Hook 封装 el-dialog，实现更灵活、更易用的弹窗组件。
一、问题澄清
「将一个通用的组件应用在多个页面」是一个很常见的实际场景。
举个例子：以购买应用程序为例，用户可能在付费页面进行购买操作，也可能在浏览其他页面时触发购买需求，此时就需要弹出对话框引导用户完成购买行为。
为了实现这一功能，过去通常会采用以下步骤：
- 封装购买组件：首先创建一个通用的购买组件，以便在不同页面和场景下复用。
- 在付费页面渲染购买组件：将购买组件直接嵌到付费页面中。
- 在其他页面使用
el-dialog展示购买组件：在其他页面通过el-dialog控制组件的显示，利用visible状态变量（通常是一个ref响应式变量）动态控制对话框的弹出与关闭。
虽然这种方式可以满足功能需求，但随着该组件被越来越多的页面和功能所使用，维护也会愈加复杂繁琐——每增加一个使用页面，都必须重复编写控制显示/隐藏的逻辑代码。
那么，有没有更好的方法可以简化这个过程？是否可以通过某种方式，用一个单独的函数全局控制购买组件的打开和关闭，从而减少代码重复，降低维护成本？
二、关于 useDialog Hook
在 Vue 中，Hook 允许在函数式组件或者 API 中「钩入」Vue 特性。它们通常在组合式 API（Composition API）中使用，这是 Vue 提供的一套响应式和可复用逻辑功能的集合。
本文提到的 useDialog Hook 就是一个封装了 el-dialog 组件基本功能的自定义 Hook，它还可以提供附加特性以便在项目中管理和展示弹窗。
三、实现 useDialog Hook
useDialog Hook 需要达成以下目标：
- 满足基础用法，传入
el-dialog的基础属性以及默认slot显示的内容，导出openDialog和closeDialog函数； - 支持
el-dialog的事件配置； - 支持默认
slot组件的属性配置； - 支持
el-dialog其他 slot 配置，例如header和footer等； - 在内容组件中抛出特定事件支持关闭 dialog；
- 支持显示内容为
jsx、普通文本、Vue Component； - 支持在显示内容中控制是否可以关闭的回调函数，例如
beforeClose； - 支持显示之前钩子，例如
onBeforeOpen； - 支持定义和弹出时修改配置属性；
- 支持继承 root vue 的 prototype，可以使用如
vue-i18n的$t函数； - 支持
ts参数提示；
（一）准备 useDialog.ts 文件实现类型定义
import type { Ref } from 'vue'
import { h, render } from 'vue'
import { ElDialog } from 'element-plus'
import type {
ComponentInternalInstance,
} from '@vue/runtime-core'
type Content = Parameters<typeof h>[0] | string | JSX.Element
// 使用 InstanceType 获取 ElDialog 组件实例的类型
type ElDialogInstance = InstanceType<typeof ElDialog>
// 从组件实例中提取 Props 类型
type DialogProps = ElDialogInstance['$props'] & {
}
interface ElDialogSlots {
header?: (...args: any[]) => Content
footer?: (...args: any[]) => Content
}
interface Options<P> {
dialogProps?: DialogProps
dialogSlots?: ElDialogSlots
contentProps?: P
}
（二）实现普通 useDialog 函数
下面的函数实现了含目标 1、2、3、4、6 和 11 在内的基础用法。
目标 1：满足基础用法，传入
el-dialog基础属性及默认 slot 显示的内容，导出openDialog和closeDialog函数；
目标 2：支持el-dialog的事件配置；
目标 3.：支持默认slot组件的属性配置；
目标 4：支持el-dialog其他 slot 配置，如header和footer等；
目标 6：支持显示内容为jsx、普通文本、Vue Component；
目标 11：支持ts参数提示；
export function useDialog<P = any>(content: Content, options?: Ref<Options<P>> | Options<P>) {
let dialogInstance: ComponentInternalInstance | null = null
let fragment: Element | null = null
// 关闭并卸载组件
const closeAfter = () => {
if (fragment) {
render(null, fragment as unknown as Element) // 卸载组件
fragment.textContent = '' // 清空文档片段
fragment = null
}
dialogInstance = null
}
function closeDialog() {
if (dialogInstance)
dialogInstance.props.modelValue = false
}
// 创建并挂载组件
function openDialog() {
if (dialogInstance) {
closeDialog()
closeAfter()
}
const { dialogProps, contentProps } = options
fragment = document.createDocumentFragment() as unknown as Element
const vNode = h(ElDialog, {
...dialogProps,
modelValue: true,
onClosed: () => {
dialogProps?.onClosed?.()
closeAfter()
},
}, {
default: () => [typeof content === 'string'
? content
: h(content as any, {
...contentProps,
})],
...options.dialogSlots,
})
render(vNode, fragment)
dialogInstance = vNode.component
document.body.appendChild(fragment)
}
onUnmounted(() => {
closeDialog()
})
return { openDialog, closeDialog }
}
（三）实现目标 5
目标 5：在内容组件中抛出特定事件支持关闭 dialog；
- 在定义中支持
closeEventName;
interface Options<P> {
// ...
closeEventName?: string // 新增的属性
}
- 修改
useDialog函数接收closeEventName事件关闭 dialog。
export function useDialog<P = any>(content: Content, options?: Ref<Options<P>> | Options<P>) {
// ...
// 创建并挂载组件
function openDialog() {
// ...
fragment = document.createDocumentFragment() as unknown as Element
// 转换closeEventName事件
const closeEventName = `on${upperFirst(_options?.closeEventName || 'closeDialog')}`
const vNode = h(ElDialog, {
// ...
}, {
default: () => [typeof content === 'string'
? content
: h(content as any, {
...contentProps,
[closeEventName]: closeDialog, // 监听自定义关闭事件，并执行关闭
})],
...options.dialogSlots,
})
render(vNode, fragment)
dialogInstance = vNode.component
document.body.appendChild(fragment)
}
onUnmounted(() => {
closeDialog()
})
return { openDialog, closeDialog }
}
（四）实现目标 7、8
目标 7：支持在显示内容中控制是否可以关闭的回调函数，例如
beforeClose；
目标 8：支持显示之前钩子，例如onBeforeOpen；
- 在定义中支持
onBeforeOpen、beforeCloseDialog默认传给内容组件，有组件调用设置；
type DialogProps = ElDialogInstance['$props'] & {
onBeforeOpen?: () => boolean | void
}
- 修改
useDialog函数接收onBeforeOpen事件并传递beforeCloseDialog。
export function useDialog<P = any>(content: Content, options?: Ref<Options<P>> | Options<P>) {
// ...
// 创建并挂载组件
function openDialog() {
// ...
const { dialogProps, contentProps } = options
// 调用before钩子，如果为false则不打开
if (dialogProps?.onBeforeOpen?.() === false) {
return
}
// ...
// 定义当前块关闭前钩子变量
let onBeforeClose: (() => Promise<boolean | void> | boolean | void) | null
const vNode = h(ElDialog, {
// ...
beforeClose: async (done) => {
// 配置`el-dialog`的关闭回调钩子函数
const result = await onBeforeClose?.()
if (result === false) {
return
}
done()
},
onClosed: () => {
dialogProps?.onClosed?.()
closeAfter()
// 关闭后回收当前变量
onBeforeClose = null
},
}, {
default: () => [typeof content === 'string'
? content
: h(content as any, {
// ...
beforeCloseDialog: (fn: (() => boolean | void)) => {
// 把`beforeCloseDialog`传递给`content`，当组件内部使用`props.beforeCloseDialog(fn)`时，会把fn传递给`onBeforeClose`
onBeforeClose = fn
},
})],
...options.dialogSlots,
})
render(vNode, fragment)
dialogInstance = vNode.component
document.body.appendChild(fragment)
}
onUnmounted(() => {
closeDialog()
})
return { openDialog, closeDialog }
}
（五）实现目标 9、10
目标 9：支持定义和弹出时修改配置属性；
目标 10：支持继承 root vue 的 prototype，可以使用例如vue-i18n的$t函数；
// 定义工具函数，获取计算属性的option
function getOptions<P>(options?: Ref<Options<P>> | Options<P>) {
if (!options)
return {}
return isRef(options) ? options.value : options
}
export function useDialog<P = any>(content: Content, options?: Ref<Options<P>> | Options<P>) {
// ...
// 获取当前组件实例，用于设置当前dialog的上下文，继承prototype
const instance = getCurrentInstance()
// 创建并挂载组件，新增`modifyOptions`参数
function openDialog(modifyOptions?: Partial<Options<P>>) {
// ...
const _options = getOptions(options)
// 如果有修改，则合并options。替换之前的options变量为 _options
if (modifyOptions)
merge(_options, modifyOptions)
// ...
const vNode = h(ElDialog, {
// ...
}, {
// ...
})
// 设置当前的上下文为使用者的上下文
vNode.appContext = instance?.appContext || null
render(vNode, fragment)
dialogInstance = vNode.component
document.body.appendChild(fragment)
}
onUnmounted(() => {
closeDialog()
})
return { openDialog, closeDialog }
}
通过上面的封装使用 useDialog Hook 后，需要弹窗时，只需要引入该 Hook 并调用 openDialog 方法，非常方便简洁。此外，这样的封装也会让后续修改弹窗逻辑变得更加方便，只需要在 useDialog Hook 中修改，无需逐个重复编辑。
四、useDialog Hook 案例实操
下面，我们使用 useDialog Hook 来解决开头提到的应用程序购买问题。
（一）创建 components/buy.vue 购买组件
<script lang="ts" setup>
const props = defineProps({
from: {
type: String,
default: '',
},
})
</script>
<template>
我是购买组件
</template>
（二）在 pages/subscription.vue 页面中使用 buy.vue 购买组件
<script lang="ts" setup>
import Buy from '@/components/buy.vue'
</script>
<template>
<Buy from="subscription" />
</template>
（三）在其他功能页面中弹出 buy.vue 购买组件
<script lang="ts" setup>
import { useDialog } from '@/hooks/useDialog'
const Buy = defineAsyncComponent(() => import('@/components/buy.vue'))
const { openDialog } = useDialog(Buy, {
dialogProps: {
// ...
title: '购买'
},
contentProps: {
from: 'function',
},
})
const onSomeClick = () => {
openDialog()
}
</script>
拓展：useDialog Hook 的其他应用
beforeClose & closeEventName 示例：buy.vue 购买组件
<script lang="ts" setup>
const props = defineProps({
from: {
type: String,
default: '',
},
beforeCloseDialog: {
type: Function,
default: () => true,
},
})
const emit = defineEmits(['closeDialog'])
props.beforeCloseDialog(() => {
// 假如from 为 空字符串不能关闭
if (!props.from) {
return false
}
return true
})
// 关闭dialog
const onBuySuccess = () => emit('closeDialog')
</script>
<script lang="ts" setup>
import { useDialog } from '@/hooks/useDialog'
const Buy = defineAsyncComponent(() => import('@/components/buy.vue'))
const { openDialog } = useDialog(Buy, {
dialogProps: {
// ...
title: '购买'
},
contentProps: {
from: '',
},
})
const onSomeClick = () => {
openDialog()
}
</script>
总结
使用 useDialog Hook 封装 el-dialog 可以让前端技术更加有趣简洁。笔者也希望大家能尝试这样的封装方式，让前端代码更加优雅且易于维护。
优秀的工程师就同优秀的厨师一样，掌握了精妙的烹饪和调味技巧，就能让每道菜都变得美味可口！
LigaAI 重视开发者文化的维护与构建，将继续分享更多技术分享和趣味技术实践。
欢迎关注 LigaAI 帐号，也期待您点击新一代智能研发协作平台，与我们展开更多交流。
助力开发者扬帆远航，LigaAI 期待与你一路同行！
