@v3hooks/dialog 使用文档

一个用于 Vue 3 的“程序式弹窗”钩子与注册器。

安装

• 依赖：vue >= 3.3.0
• 安装：pnpm add @v3hooks/dialog

快速开始

1. 注册弹窗组件

import { registerBatch } from '@v3hooks/dialog'
import MyDialog from './MyDialog.vue'

registerBatch({
  myDialog: { component: MyDialog }
})

2. 在任意组件中使用 useDialog 打开/关闭

import { useDialog } from '@v3hooks/dialog'

// 传入弹窗类型和选项（选项包含弹窗props以及事件处理器）
const { id, opened } = useDialog('myDialog', {
  // DialogOptions
  closed: true,           // 打开前关闭其他所有弹窗
  destroyed: true,        // 关闭后销毁实例（默认）
  appendToBody: true,     // 挂载到 body（默认）
  openedKey: 'opened',    // 可见键（默认）

  // 组件Props与事件（示例）
  title: 'Hello Dialog',
  onConfirm: () => { console.log('confirmed') },
  onClose: () => { opened.value = false }
})

// 打开/关闭
function openDialog() { opened.value = true }
function closeDialog() { opened.value = false }

API 参考

• registerBatch(components)

  • 参数：Partial<Record<DialogType, DialogComponent>>
  • 功能：批量注册弹窗类型与组件；如已存在相同类型会抛错。

• unregisterBatch(types)

  • 参数：DialogType[]
  • 功能：批量注销已注册的弹窗类型；未注册会抛错。

• useDialog<P extends object, E extends object>(type, options?)

  • 参数：
    • type: DialogType 已注册的弹窗类型字符串。
    • options: DialogOptions & P & EmitsToProps<ShortEmitsToObject<E>>
      • closed?: boolean | string[] 打开前关闭其他弹窗或指定id列表（默认 false）。
      • destroyed?: boolean 关闭后是否销毁实例（默认 true）。
      • appendToBody?: boolean 是否挂载到 body（默认 true），否则挂载到 #app。
      • openedKey?: string 控制可见的prop名称（默认 'opened'）。
      • 组件 props 与事件：直接在此对象中传入，如 title、onConfirm、onClose 等。
  • 返回：{ id: string; opened: Ref<boolean> }
    • id：实例ID，可用于 closed: [id1, id2] 精确关闭。
    • opened：响应式布尔值，控制弹窗打开/关闭。

• 类型：

  • DialogComponent = { component: any; singletonMode?: boolean }
  • DialogOptions 如上；
  • DialogType 为字符串，支持通过模块增强获得类型提示。

类型增强（可选）

若希望在 TS 中获得更严格的弹窗类型提示，可对包内接口进行模块增强：

import '@v3hooks/dialog'

export {}
declare module '@v3hooks/dialog' {
  interface Dialog {
    type: 'myDialog' | 'confirm' | 'alert'
  }
}

在使用useDialog时也可以获得类型提示

import { useDialog } from '@v3hooks/dialog'

useDialog<PropsType, EmitsType>('myDialog', {})

需要注意的是，目前能支持的事件类型定义方式如下：

type MyDialogEmits = {
  'update:opened': [opened: boolean] // 在hooks中表示 onUpdate:opened
  'confirm': [] // 在hooks中表示 onConfirm
  'close': [] // 在hooks中表示 onClose
}

进阶示例：自定义可见键 visible

<!-- CustomDialog.vue -->
<script setup lang="ts">
const props = defineProps<{ visible: boolean }>()
</script>

<template>
  <div v-if="visible">自定义可见键</div>
  <!-- 你的弹窗内容 -->
</template>

import { registerBatch, useDialog } from '@v3hooks/dialog'
import CustomDialog from './CustomDialog.vue'

registerBatch({ custom: { component: CustomDialog } })

const { opened } = useDialog('custom', { openedKey: 'visible' })
opened.value = true

常见问题与注意事项

• DOM 依赖：库使用 document 进行程序式挂载，需在浏览器环境中使用（SSR 场景需在客户端触发）。
• 容器要求：当 appendToBody = false 时，页面需存在 id="app" 的根元素，否则会报错。

许可

ISC