技术分享 | 弹窗开发中,如何使用 Hook 封装 el-dialog?

弹窗是前端开发中的一种常见需求。Element UI 框架中的 el-dialog 组件提供了弹窗相关的基本功能,但在实际开发中,我们难免会遇到一些定制化需求,比如对弹窗进行二次封装以便在项目中统一管理样式和行为。

本文将分享如何使用 useDialog Hook 封装 el-dialog,实现更灵活、更易用的弹窗组件。

一、问题澄清

「将一个通用的组件应用在多个页面」是一个很常见的实际场景。

举个例子:以购买应用程序为例,用户可能在付费页面进行购买操作,也可能在浏览其他页面时触发购买需求,此时就需要弹出对话框引导用户完成购买行为。

为了实现这一功能,过去通常会采用以下步骤:

  1. 封装购买组件:首先创建一个通用的购买组件,以便在不同页面和场景下复用。
  2. 在付费页面渲染购买组件:将购买组件直接嵌到付费页面中。
  3. 在其他页面使用 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 需要达成以下目标:

  1. 满足基础用法,传入 el-dialog 的基础属性以及默认slot显示的内容,导出 openDialogcloseDialog 函数;
  2. 支持 el-dialog 的事件配置;
  3. 支持默认 slot 组件的属性配置;
  4. 支持 el-dialog 其他 slot 配置,例如 headerfooter 等;
  5. 在内容组件中抛出特定事件支持关闭 dialog;
  6. 支持显示内容为 jsx普通文本Vue Component
  7. 支持在显示内容中控制是否可以关闭的回调函数,例如 beforeClose
  8. 支持显示之前钩子,例如 onBeforeOpen
  9. 支持定义和弹出时修改配置属性;
  10. 支持继承 root vue 的 prototype,可以使用如 vue-i18n$t 函数;
  11. 支持 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 显示的内容,导出 openDialogcloseDialog 函数;
目标 2:支持 el-dialog 的事件配置;
目标 3.:支持默认 slot 组件的属性配置;
目标 4:支持 el-dialog 其他 slot 配置,如 headerfooter 等;
目标 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;

  1. 在定义中支持 closeEventName ;
interface Options<P> {
  // ...
  closeEventName?: string // 新增的属性
}
  1. 修改 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

  1. 在定义中支持 onBeforeOpenbeforeCloseDialog 默认传给内容组件,有组件调用设置;
type DialogProps = ElDialogInstance['$props'] & {
  onBeforeOpen?: () => boolean | void
}
  1. 修改 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 x 极狐GitLab,共探 AI 时代研发提效新范式

宁波银行:在「金融科技」引擎上,沉浸式提效减负

生成式 AI 如何释放开发者的生产力?

新晋技术管理者如何推动组织变革?

欢迎试用 LigaAI-智能研发协作平台,体验智能研发协作,一起变大变强!