yann-popup

yann-popup

介绍

以函数式创建弹窗 —— Vue 3 函数式弹窗库（全 TypeScript，内置 Element Plus el-dialog 封装）

安装

pnpm add yann-popup
# 需要项目已安装 peer 依赖
pnpm add vue element-plus

使用说明

在应用根组件放置一次弹窗容器：

<template>
  <RouterView />
  <!-- 所有函数式弹窗都渲染在这里 -->
  <Popup />
</template>

注意：<Popup /> 容器卸载时会销毁其渲染的所有弹窗 （避免容器实例与弹窗数据残留导致内存泄漏）。 将容器放在应用根组件而非路由布局内，可避免路由切换误关弹窗。

import { definePopup, Popup } from 'yann-popup';
import PopupComponent from './component/index.vue';

// 使用方式 1 定义弹窗生成函数
const createPopupFn = definePopup(PopupComponent);
// CloseFn 直接卸载弹窗
// createPopupFn 可以接受三个参数，
// 第一个是 PopupComponent 组件的 props，
// 第二参数 PopupComponent 组件 slots，
// 第三个参数是 配置项
const CloseFn = createPopupFn({});

// 使用方式 2 指定节点 也可以再生成弹窗函数内传递
const createPopupFn = definePopup(PopupComponent, {
  to: 'body'
});
const CloseFn = createPopupFn({});

// 使用方式 3 beforeCloseFn执行后不直接卸载
//  仅驱动内部 modelValue 为 false
//  需要弹窗执行 emit('eventClose') 才会卸载弹窗
const createPopupFn = definePopup(PopupComponent, {
  isUnload: false
});
const beforeCloseFn = createPopupFn({});

// 使用方式 4 添加自定义插槽
const createPopupFn = definePopup(PopupComponent)
const CloseFn = createPopupFn({...}, {
  default: defineAsyncComponent(() => import('./test/index.vue')),
  header:{
    component : defineAsyncComponent(() => import('./test/header.vue')),
    props: {
      title: 'title'
    }
  }
})

// 使用方式 5 createPopup 内置的弹窗函数（基于 el-dialog）
import { createPopup } from 'yann-popup';
const close = createPopup({
  // element-plus的dialog组件的属性
}, {
  // element-plus的dialog组件的插槽
})

// 使用方式 6 defineClosePopup 定义关闭函数 不传参数时表示关闭最后生成的弹窗
const close = defineClosePopup()
if(close){
  //
  close()
}

// 使用方式 7 defineClosePopup 定义指定 id 的关闭函数
import { createPopup, defineClosePopup } from 'yann-popup';
const close = createPopup({
  // element-plus的dialog组件的属性
}, {
  // element-plus的dialog组件的插槽
},{
  id: 2
})

const close = defineClosePopup(2)
close()

类型说明

v2 起整个库使用 TypeScript 编写并随包发布完整的类型声明， 公共类型均从入口导出，可直接在 IDE 中获得提示：

import type {
  PopupProps, // 传给弹窗组件的 props（任意键值）
  PopupOption, // { to?: string; isUnload?: boolean }
  PopupId, // { id?: string | number | symbol }
  PopupSlots, // { [slot: string]: { component, props } }
  PopupSlotsSimple, // { [slot: string]: AnyVueComponent }
  CloseFn, // () => void
  CreatePopup, // (props?, slots?, option?) => CloseFn
  PopupComponentProps, // 自定义弹窗组件需支持的 props 契约
} from "yann-popup";

核心签名：

/** 将 Vue 组件包装为弹窗工厂 */
declare function definePopup(component: AnyVueComponent, initOption?: PopupOption): CreatePopup;

/** 获取关闭函数：传 id 关闭指定弹窗，不传关闭最后一个 */
declare function defineClosePopup(id?: string | number | symbol): CloseFn | undefined;

/** 内置 el-dialog 弹窗工厂 */
declare const createPopup: CreatePopup;

自定义弹窗组件的 props 契约（框架会注入 modelValue 与 index）：

interface PopupComponentProps {
  modelValue?: boolean; // 创建时强制为 true
  index?: number; // 最终 z-index = config.initIndex + index
}

开发

pnpm install   # 安装依赖（node 24 + pnpm 11，见 mise.toml）
pnpm dev       # 启动开发服务
pnpm test      # 运行测试（vitest）
pnpm typecheck # 类型检查（vue-tsc --noEmit，strict 模式）
pnpm lint      # oxlint 检查
pnpm fmt       # oxfmt 格式化
pnpm build     # 类型检查 + 构建（ESM-only，输出 dist/）