vue-modal-core

Vue Modal Core

一个轻量级的 Vue 3 模态框管理库，提供灵活的模态框控制和生命周期管理。

特性

• 🎯 TypeScript 支持
• 🔄 响应式状态管理
• 🎨 灵活的模态框组件复用
• 🔒 完整的生命周期控制
• ⚡ 支持异步关闭控制
• 📦 支持多模态框管理

安装

npm install vue-modal-core
# 或
yarn add vue-modal-core
# 或
pnpm add vue-modal-core

基础用法

1. 首先创建你的模态框组件（例如 MyModal.vue）：

<template>
  <div v-if="visible" class="modal">
    <div class="modal-content">
      <!-- 你的模态框内容 -->
      <button @click="$emit('update:visible', false)">关闭</button>
    </div>
  </div>
</template>

<script setup lang="ts">
defineProps<{
  visible: boolean
}>()
</script>

1. 在应用中使用：

import { createModalContext } from 'vue-modal-core'
import MyModal from './MyModal.vue'

// 创建模态框上下文
const { makeModal, ModalRenderer } = createModalContext({
  baseZIndex: 1000,  // 基础 z-index
  allowMultiple: true,  // 是否允许多个模态框同时存在
  debug: false  // 是否开启调试日志
})

// 创建模态框实例
const modal = makeModal(MyModal)

// 打开模态框
modal.open({
  // 传入 props（除了 visible）
  title: '标题',
  content: '内容'
})

// 关闭模态框
await modal.close()

// 检查模态框是否可见
const isVisible = modal.isVisible()

1. 在 App.vue 中挂载渲染器：

<template>
  <div>
    <!-- 你的应用内容 -->
    <modal-renderer />
  </div>
</template>

高级特性

关闭前钩子

你可以使用 onBeforeClose 钩子来控制模态框的关闭行为：

import { onBeforeClose } from 'vue-modal-core'

// 在模态框组件中
onBeforeClose(async () => {
  // 返回 false 可以阻止模态框关闭
  const shouldClose = await askUser()
  return shouldClose
})

多模态框管理

// 创建多个模态框实例
const modal1 = makeModal(MyModal, Symbol('Modal1'))
const modal2 = makeModal(MyModal, Symbol('Modal2'))

// 控制是否允许多个模态框同时显示
const { makeModal, ModalRenderer } = createModalContext({
  allowMultiple: false  // 设置为 false 时会自动关闭之前的模态框
})

TypeScript 支持

库提供完整的 TypeScript 类型支持，可以获得完整的类型提示：

import type { ExtractComponentOptions } from 'vue-modal-core'

// 模态框的 props 类型会自动推导
const modal = makeModal(MyModal)
modal.open({
  // 这里会获得完整的类型提示
})

API 参考

createModalContext 配置项

参数	类型	默认值	说明
baseZIndex	number	1000	模态框基础 z-index 值
allowMultiple	boolean	true	是否允许多个模态框同时存在
debug	boolean	false	是否开启调试日志

Modal 实例方法

方法	参数	返回值	说明
open	props: ExtractComponentOptions	void	打开模态框
close	-	Promise	关闭模态框
isVisible	-	boolean	获取模态框可见状态

注意事项

1. 确保在模态框组件中正确处理 visible prop 和 update:visible 事件
2. onBeforeClose 钩子必须在组件的 setup 函数或 <script setup> 中使用
3. 多个 onBeforeClose 钩子会按照后进先出（LIFO）的顺序执行

API 文档

createModalContext

创建模态框上下文，返回模态框管理器实例。

interface ModalOptions {
  baseZIndex?: number;      // 基础 z-index 值
  enableAnimation?: boolean; // 是否启用动画
  allowMultiple?: boolean;   // 是否允许多个模态框同时存在
  debug?: boolean;          // 是否启用调试模式
}

const context = createModalContext(options?: ModalOptions);

makeModal

创建模态框实例。

const modal = makeModal(YourModalComponent);

// 返回的实例包含以下方法：
interface ModalInstance {
  open: (props: ComponentProps) => void;  // 打开模态框
  close: () => Promise<boolean>;          // 关闭模态框
  isVisible: () => boolean;               // 获取模态框可见状态
}

onBeforeClose

添加模态框关闭前的钩子函数。

onBeforeClose(() => {
  // 返回 false 可以阻止模态框关闭
  return true;
});

其它

• 这个项目基本是我自己一个人在使用的，所以可能会有一些问题，欢迎提交 PR 和 Issue

许可证

MIT