更新最新代码

packages/@core/ui-kit/popup-ui/build.config.ts

@@ -0,0 +1,21 @@
+import { defineBuildConfig } from 'unbuild';
+
+export default defineBuildConfig({
+  clean: true,
+  declaration: true,
+  entries: [
+    {
+      builder: 'mkdist',
+      input: './src',
+      loaders: ['vue'],
+      pattern: ['**/*.vue'],
+    },
+    {
+      builder: 'mkdist',
+      format: 'esm',
+      input: './src',
+      loaders: ['js'],
+      pattern: ['**/*.ts'],
+    },
+  ],
+});

packages/@core/ui-kit/popup-ui/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@vben-core/popup-ui",
+  "version": "5.2.1",
+  "homepage": "https://github.com/vbenjs/vue-vben-admin",
+  "bugs": "https://github.com/vbenjs/vue-vben-admin/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vbenjs/vue-vben-admin.git",
+    "directory": "packages/@vben-core/uikit/popup-ui"
+  },
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm unbuild",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@vben-core/composables": "workspace:*",
+    "@vben-core/icons": "workspace:*",
+    "@vben-core/shadcn-ui": "workspace:*",
+    "@vben-core/shared": "workspace:*",
+    "@vben-core/typings": "workspace:*",
+    "@vueuse/core": "catalog:",
+    "vue": "catalog:"
+  }
+}

packages/@core/ui-kit/popup-ui/postcss.config.mjs

@@ -0,0 +1 @@
+export { default } from '@vben/tailwind-config/postcss';

packages/@core/ui-kit/popup-ui/src/alert/alert.ts

@@ -0,0 +1,99 @@
+import type { Component, VNode, VNodeArrayChildren } from 'vue';
+
+import type { Recordable } from '@vben-core/typings';
+
+import { createContext } from '@vben-core/shadcn-ui';
+
+export type IconType = 'error' | 'info' | 'question' | 'success' | 'warning';
+
+export type BeforeCloseScope = {
+  isConfirm: boolean;
+};
+
+export type AlertProps = {
+  /** 关闭前的回调，如果返回false，则终止关闭 */
+  beforeClose?: (
+    scope: BeforeCloseScope,
+  ) => boolean | Promise<boolean | undefined> | undefined;
+  /** 边框 */
+  bordered?: boolean;
+  /**
+   * 按钮对齐方式
+   * @default 'end'
+   */
+  buttonAlign?: 'center' | 'end' | 'start';
+  /** 取消按钮的标题 */
+  cancelText?: string;
+  /** 是否居中显示 */
+  centered?: boolean;
+  /** 确认按钮的标题 */
+  confirmText?: string;
+  /** 弹窗容器的额外样式 */
+  containerClass?: string;
+  /** 弹窗提示内容 */
+  content: Component | string;
+  /** 弹窗内容的额外样式 */
+  contentClass?: string;
+  /** 执行beforeClose回调期间，在内容区域显示一个loading遮罩*/
+  contentMasking?: boolean;
+  /** 弹窗底部内容（与按钮在同一个容器中） */
+  footer?: Component | string;
+  /** 弹窗的图标（在标题的前面） */
+  icon?: Component | IconType;
+  /**
+   * 弹窗遮罩模糊效果
+   */
+  overlayBlur?: number;
+  /** 是否显示取消按钮 */
+  showCancel?: boolean;
+  /** 弹窗标题 */
+  title?: string;
+};
+
+/** Prompt属性 */
+export type PromptProps<T = any> = {
+  /** 关闭前的回调，如果返回false，则终止关闭 */
+  beforeClose?: (scope: {
+    isConfirm: boolean;
+    value: T | undefined;
+  }) => boolean | Promise<boolean | undefined> | undefined;
+  /** 用于接受用户输入的组件 */
+  component?: Component;
+  /** 输入组件的属性 */
+  componentProps?: Recordable<any>;
+  /** 输入组件的插槽 */
+  componentSlots?:
+    | (() => any)
+    | Recordable<unknown>
+    | VNode
+    | VNodeArrayChildren;
+  /** 默认值 */
+  defaultValue?: T;
+  /** 输入组件的值属性名 */
+  modelPropName?: string;
+} & Omit<AlertProps, 'beforeClose'>;
+
+/**
+ * Alert上下文
+ */
+export type AlertContext = {
+  /** 执行取消操作 */
+  doCancel: () => void;
+  /** 执行确认操作 */
+  doConfirm: () => void;
+};
+
+export const [injectAlertContext, provideAlertContext] =
+  createContext<AlertContext>('VbenAlertContext');
+
+/**
+ * 获取Alert上下文
+ * @returns AlertContext
+ */
+export function useAlertContext() {
+  const context = injectAlertContext();
+  if (!context) {
+    throw new Error('useAlertContext must be used within an AlertProvider');
+  }
+  return context;
+}

packages/@core/ui-kit/popup-ui/src/alert/index.ts

@@ -0,0 +1,14 @@
+export type {
+  AlertProps,
+  BeforeCloseScope,
+  IconType,
+  PromptProps,
+} from './alert';
+export { useAlertContext } from './alert';
+export { default as Alert } from './alert.vue';
+export {
+  vbenAlert as alert,
+  clearAllAlerts,
+  vbenConfirm as confirm,
+  vbenPrompt as prompt,
+} from './AlertBuilder';

packages/@core/ui-kit/popup-ui/src/drawer/__tests__/drawer-api.test.ts

@@ -0,0 +1,116 @@
+import type { DrawerState } from '../drawer';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { DrawerApi } from '../drawer-api';
+
+// 模拟 Store 类
+vi.mock('@vben-core/shared/store', () => {
+  return {
+    isFunction: (fn: any) => typeof fn === 'function',
+    Store: class {
+      get state() {
+        return this._state;
+      }
+      private _state: DrawerState;
+
+      private options: any;
+
+      constructor(initialState: DrawerState, options: any) {
+        this._state = initialState;
+        this.options = options;
+      }
+
+      batch(cb: () => void) {
+        cb();
+      }
+
+      setState(fn: (prev: DrawerState) => DrawerState) {
+        this._state = fn(this._state);
+        this.options.onUpdate();
+      }
+    },
+  };
+});
+
+describe('drawerApi', () => {
+  let drawerApi: DrawerApi;
+  let drawerState: DrawerState;
+
+  beforeEach(() => {
+    drawerApi = new DrawerApi();
+    drawerState = drawerApi.store.state;
+  });
+
+  it('should initialize with default state', () => {
+    expect(drawerState.isOpen).toBe(false);
+    expect(drawerState.cancelText).toBe(undefined);
+    expect(drawerState.confirmText).toBe(undefined);
+  });
+
+  it('should open the drawer', () => {
+    drawerApi.open();
+    expect(drawerApi.store.state.isOpen).toBe(true);
+  });
+
+  it('should close the drawer if onBeforeClose allows it', () => {
+    drawerApi.close();
+    expect(drawerApi.store.state.isOpen).toBe(false);
+  });
+
+  it('should not close the drawer if onBeforeClose returns false', () => {
+    const onBeforeClose = vi.fn(() => false);
+    const drawerApiWithHook = new DrawerApi({ onBeforeClose });
+    drawerApiWithHook.open();
+    drawerApiWithHook.close();
+    expect(drawerApiWithHook.store.state.isOpen).toBe(true);
+    expect(onBeforeClose).toHaveBeenCalled();
+  });
+
+  it('should trigger onCancel and keep drawer open if onCancel is provided', () => {
+    const onCancel = vi.fn();
+    const drawerApiWithHook = new DrawerApi({ onCancel });
+    drawerApiWithHook.open();
+    drawerApiWithHook.onCancel();
+    expect(onCancel).toHaveBeenCalled();
+    expect(drawerApiWithHook.store.state.isOpen).toBe(true); // 关闭逻辑不在 onCancel 内
+  });
+
+  it('should update shared data correctly', () => {
+    const testData = { key: 'value' };
+    drawerApi.setData(testData);
+    expect(drawerApi.getData()).toEqual(testData);
+  });
+
+  it('should set state correctly using an object', () => {
+    drawerApi.setState({ title: 'New Title' });
+    expect(drawerApi.store.state.title).toBe('New Title');
+  });
+
+  it('should set state correctly using a function', () => {
+    drawerApi.setState((prev) => ({ ...prev, confirmText: 'Yes' }));
+    expect(drawerApi.store.state.confirmText).toBe('Yes');
+  });
+
+  it('should call onOpenChange when state changes', () => {
+    const onOpenChange = vi.fn();
+    const drawerApiWithHook = new DrawerApi({ onOpenChange });
+    drawerApiWithHook.open();
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it('should call onClosed callback when provided', () => {
+    const onClosed = vi.fn();
+    const drawerApiWithHook = new DrawerApi({ onClosed });
+    drawerApiWithHook.onClosed();
+    expect(onClosed).toHaveBeenCalled();
+  });
+
+  it('should call onOpened callback when provided', () => {
+    const onOpened = vi.fn();
+    const drawerApiWithHook = new DrawerApi({ onOpened });
+    drawerApiWithHook.open();
+    drawerApiWithHook.onOpened();
+    expect(onOpened).toHaveBeenCalled();
+  });
+});

packages/@core/ui-kit/popup-ui/src/drawer/drawer-api.ts

@@ -0,0 +1,183 @@
+import type { DrawerApiOptions, DrawerState } from './drawer';
+
+import { Store } from '@vben-core/shared/store';
+import { bindMethods, isFunction } from '@vben-core/shared/utils';
+
+export class DrawerApi {
+  // 共享数据
+  public sharedData: Record<'payload', any> = {
+    payload: {},
+  };
+  public store: Store<DrawerState>;
+
+  private api: Pick<
+    DrawerApiOptions,
+    | 'onBeforeClose'
+    | 'onCancel'
+    | 'onClosed'
+    | 'onConfirm'
+    | 'onOpenChange'
+    | 'onOpened'
+  >;
+
+  // private prevState!: DrawerState;
+  private state!: DrawerState;
+
+  constructor(options: DrawerApiOptions = {}) {
+    const {
+      connectedComponent: _,
+      onBeforeClose,
+      onCancel,
+      onClosed,
+      onConfirm,
+      onOpenChange,
+      onOpened,
+      ...storeState
+    } = options;
+
+    const defaultState: DrawerState = {
+      class: '',
+      closable: true,
+      closeIconPlacement: 'right',
+      closeOnClickModal: true,
+      closeOnPressEscape: true,
+      confirmLoading: false,
+      contentClass: '',
+      footer: true,
+      header: true,
+      isOpen: false,
+      loading: false,
+      modal: true,
+      openAutoFocus: false,
+      placement: 'right',
+      showCancelButton: true,
+      showConfirmButton: true,
+      submitting: false,
+      title: '',
+    };
+
+    this.store = new Store<DrawerState>(
+      {
+        ...defaultState,
+        ...storeState,
+      },
+      {
+        onUpdate: () => {
+          const state = this.store.state;
+          if (state?.isOpen === this.state?.isOpen) {
+            this.state = state;
+          } else {
+            this.state = state;
+            this.api.onOpenChange?.(!!state?.isOpen);
+          }
+        },
+      },
+    );
+    this.state = this.store.state;
+    this.api = {
+      onBeforeClose,
+      onCancel,
+      onClosed,
+      onConfirm,
+      onOpenChange,
+      onOpened,
+    };
+    bindMethods(this);
+  }
+
+  /**
+   * 关闭抽屉
+   * @description 关闭抽屉时会调用 onBeforeClose 钩子函数，如果 onBeforeClose 返回 false，则不关闭弹窗
+   */
+  async close() {
+    // 通过 onBeforeClose 钩子函数来判断是否允许关闭弹窗
+    // 如果 onBeforeClose 返回 false，则不关闭弹窗
+    const allowClose = (await this.api.onBeforeClose?.()) ?? true;
+    if (allowClose) {
+      this.store.setState((prev) => ({
+        ...prev,
+        isOpen: false,
+        submitting: false,
+      }));
+    }
+  }
+
+  getData<T extends object = Record<string, any>>() {
+    return (this.sharedData?.payload ?? {}) as T;
+  }
+
+  /**
+   * 锁定抽屉状态（用于提交过程中的等待状态）
+   * @description 锁定状态将禁用默认的取消按钮，使用spinner覆盖抽屉内容，隐藏关闭按钮，阻止手动关闭弹窗，将默认的提交按钮标记为loading状态
+   * @param isLocked 是否锁定
+   */
+  lock(isLocked: boolean = true) {
+    return this.setState({ submitting: isLocked });
+  }
+
+  /**
+   * 取消操作
+   */
+  onCancel() {
+    if (this.api.onCancel) {
+      this.api.onCancel?.();
+    } else {
+      this.close();
+    }
+  }
+
+  /**
+   * 弹窗关闭动画播放完毕后的回调
+   */
+  onClosed() {
+    if (!this.state.isOpen) {
+      this.api.onClosed?.();
+    }
+  }
+
+  /**
+   * 确认操作
+   */
+  onConfirm() {
+    this.api.onConfirm?.();
+  }
+
+  /**
+   * 弹窗打开动画播放完毕后的回调
+   */
+  onOpened() {
+    if (this.state.isOpen) {
+      this.api.onOpened?.();
+    }
+  }
+
+  open() {
+    this.store.setState((prev) => ({ ...prev, isOpen: true }));
+  }
+
+  setData<T>(payload: T) {
+    this.sharedData.payload = payload;
+    return this;
+  }
+
+  setState(
+    stateOrFn:
+      | ((prev: DrawerState) => Partial<DrawerState>)
+      | Partial<DrawerState>,
+  ) {
+    if (isFunction(stateOrFn)) {
+      this.store.setState(stateOrFn);
+    } else {
+      this.store.setState((prev) => ({ ...prev, ...stateOrFn }));
+    }
+    return this;
+  }
+
+  /**
+   * 解除抽屉的锁定状态
+   * @description 解除由lock方法设置的锁定状态，是lock(false)的别名
+   */
+  unlock() {
+    return this.lock(false);
+  }
+}

packages/@core/ui-kit/popup-ui/src/drawer/drawer.ts

@@ -0,0 +1,179 @@
+import type { Component, Ref } from 'vue';
+
+import type { ClassType, MaybePromise } from '@vben-core/typings';
+
+import type { DrawerApi } from './drawer-api';
+
+export type DrawerPlacement = 'bottom' | 'left' | 'right' | 'top';
+
+export type CloseIconPlacement = 'left' | 'right';
+
+export interface DrawerProps {
+  /**
+   * 是否挂载到内容区域
+   * @default false
+   */
+  appendToMain?: boolean;
+  /**
+   * 取消按钮文字
+   */
+  cancelText?: string;
+  class?: ClassType;
+  /**
+   * 是否显示关闭按钮
+   * @default true
+   */
+  closable?: boolean;
+  /**
+   * 关闭按钮的位置
+   */
+  closeIconPlacement?: CloseIconPlacement;
+  /**
+   * 点击弹窗遮罩是否关闭弹窗
+   * @default true
+   */
+  closeOnClickModal?: boolean;
+  /**
+   * 按下 ESC 键是否关闭弹窗
+   * @default true
+   */
+  closeOnPressEscape?: boolean;
+  /**
+   * 确定按钮 loading
+   * @default false
+   */
+  confirmLoading?: boolean;
+  /**
+   * 确定按钮文字
+   */
+  confirmText?: string;
+  contentClass?: string;
+  /**
+   * 弹窗描述
+   */
+  description?: string;
+  /**
+   * 在关闭时销毁抽屉
+   */
+  destroyOnClose?: boolean;
+  /**
+   * 是否显示底部
+   * @default true
+   */
+  footer?: boolean;
+  /**
+   * 弹窗底部样式
+   */
+  footerClass?: ClassType;
+  /**
+   * 是否显示顶栏
+   * @default true
+   */
+  header?: boolean;
+  /**
+   * 弹窗头部样式
+   */
+  headerClass?: ClassType;
+  /**
+   * 弹窗是否显示
+   * @default false
+   */
+  loading?: boolean;
+  /**
+   * 是否显示遮罩
+   * @default true
+   */
+  modal?: boolean;
+
+  /**
+   * 是否自动聚焦
+   */
+  openAutoFocus?: boolean;
+  /**
+   * 弹窗遮罩模糊效果
+   */
+  overlayBlur?: number;
+  /**
+   * 抽屉位置
+   * @default right
+   */
+  placement?: DrawerPlacement;
+
+  /**
+   * 是否显示取消按钮
+   * @default true
+   */
+  showCancelButton?: boolean;
+  /**
+   * 是否显示确认按钮
+   * @default true
+   */
+  showConfirmButton?: boolean;
+  /**
+   * 提交中（锁定抽屉状态）
+   */
+  submitting?: boolean;
+  /**
+   * 弹窗标题
+   */
+  title?: string;
+  /**
+   * 弹窗标题提示
+   */
+  titleTooltip?: string;
+  /**
+   * 抽屉层级
+   */
+  zIndex?: number;
+}
+
+export interface DrawerState extends DrawerProps {
+  /** 弹窗打开状态 */
+  isOpen?: boolean;
+  /**
+   * 共享数据
+   */
+  sharedData?: Record<string, any>;
+}
+
+export type ExtendedDrawerApi = DrawerApi & {
+  useStore: <T = NoInfer<DrawerState>>(
+    selector?: (state: NoInfer<DrawerState>) => T,
+  ) => Readonly<Ref<T>>;
+};
+
+export interface DrawerApiOptions extends DrawerState {
+  /**
+   * 独立的抽屉组件
+   */
+  connectedComponent?: Component;
+  /**
+   * 关闭前的回调，返回 false 可以阻止关闭
+   * @returns
+   */
+  onBeforeClose?: () => MaybePromise<boolean | undefined>;
+  /**
+   * 点击取消按钮的回调
+   */
+  onCancel?: () => void;
+  /**
+   * 弹窗关闭动画结束的回调
+   * @returns
+   */
+  onClosed?: () => void;
+  /**
+   * 点击确定按钮的回调
+   */
+  onConfirm?: () => void;
+  /**
+   * 弹窗状态变化回调
+   * @param isOpen
+   * @returns
+   */
+  onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * 弹窗打开动画结束的回调
+   * @returns
+   */
+  onOpened?: () => void;
+}

packages/@core/ui-kit/popup-ui/src/drawer/index.ts

@@ -0,0 +1,3 @@
+export type * from './drawer';
+export { default as VbenDrawer } from './drawer.vue';
+export { setDefaultDrawerProps, useVbenDrawer } from './use-drawer';

packages/@core/ui-kit/popup-ui/src/drawer/use-drawer.ts

@@ -0,0 +1,142 @@
+import type {
+  DrawerApiOptions,
+  DrawerProps,
+  ExtendedDrawerApi,
+} from './drawer';
+
+import {
+  defineComponent,
+  h,
+  inject,
+  nextTick,
+  provide,
+  reactive,
+  ref,
+} from 'vue';
+
+import { useStore } from '@vben-core/shared/store';
+
+import { DrawerApi } from './drawer-api';
+import VbenDrawer from './drawer.vue';
+
+const USER_DRAWER_INJECT_KEY = Symbol('VBEN_DRAWER_INJECT');
+
+const DEFAULT_DRAWER_PROPS: Partial<DrawerProps> = {};
+
+export function setDefaultDrawerProps(props: Partial<DrawerProps>) {
+  Object.assign(DEFAULT_DRAWER_PROPS, props);
+}
+
+export function useVbenDrawer<
+  TParentDrawerProps extends DrawerProps = DrawerProps,
+>(options: DrawerApiOptions = {}) {
+  // Drawer一般会抽离出来，所以如果有传入 connectedComponent，则表示为外部调用，与内部组件进行连接
+  // 外部的Drawer通过provide/inject传递api
+
+  const { connectedComponent } = options;
+  if (connectedComponent) {
+    const extendedApi = reactive({});
+    const isDrawerReady = ref(true);
+    const Drawer = defineComponent(
+      (props: TParentDrawerProps, { attrs, slots }) => {
+        provide(USER_DRAWER_INJECT_KEY, {
+          extendApi(api: ExtendedDrawerApi) {
+            // 不能直接给 reactive 赋值，会丢失响应
+            // 不能用 Object.assign,会丢失 api 的原型函数
+            Object.setPrototypeOf(extendedApi, api);
+          },
+          options,
+          async reCreateDrawer() {
+            isDrawerReady.value = false;
+            await nextTick();
+            isDrawerReady.value = true;
+          },
+        });
+        checkProps(extendedApi as ExtendedDrawerApi, {
+          ...props,
+          ...attrs,
+          ...slots,
+        });
+        return () =>
+          h(
+            isDrawerReady.value ? connectedComponent : 'div',
+            { ...props, ...attrs },
+            slots,
+          );
+      },
+      // eslint-disable-next-line vue/one-component-per-file
+      {
+        name: 'VbenParentDrawer',
+        inheritAttrs: false,
+      },
+    );
+
+    return [Drawer, extendedApi as ExtendedDrawerApi] as const;
+  }
+
+  const injectData = inject<any>(USER_DRAWER_INJECT_KEY, {});
+
+  const mergedOptions = {
+    ...DEFAULT_DRAWER_PROPS,
+    ...injectData.options,
+    ...options,
+  } as DrawerApiOptions;
+
+  mergedOptions.onOpenChange = (isOpen: boolean) => {
+    options.onOpenChange?.(isOpen);
+    injectData.options?.onOpenChange?.(isOpen);
+  };
+
+  const onClosed = mergedOptions.onClosed;
+  mergedOptions.onClosed = () => {
+    onClosed?.();
+    if (mergedOptions.destroyOnClose) {
+      injectData.reCreateDrawer?.();
+    }
+  };
+  const api = new DrawerApi(mergedOptions);
+
+  const extendedApi: ExtendedDrawerApi = api as never;
+
+  extendedApi.useStore = (selector) => {
+    return useStore(api.store, selector);
+  };
+
+  const Drawer = defineComponent(
+    (props: DrawerProps, { attrs, slots }) => {
+      return () =>
+        h(VbenDrawer, { ...props, ...attrs, drawerApi: extendedApi }, slots);
+    },
+    // eslint-disable-next-line vue/one-component-per-file
+    {
+      name: 'VbenDrawer',
+      inheritAttrs: false,
+    },
+  );
+  injectData.extendApi?.(extendedApi);
+  return [Drawer, extendedApi] as const;
+}
+
+async function checkProps(api: ExtendedDrawerApi, attrs: Record<string, any>) {
+  if (!attrs || Object.keys(attrs).length === 0) {
+    return;
+  }
+  await nextTick();
+
+  const state = api?.store?.state;
+
+  if (!state) {
+    return;
+  }
+
+  const stateKeys = new Set(Object.keys(state));
+
+  for (const attr of Object.keys(attrs)) {
+    if (stateKeys.has(attr) && !['class'].includes(attr)) {
+      // connectedComponent存在时，不要传入Drawer的props，会造成复杂度提升，如果你需要修改Drawer的props，请使用 useVbenDrawer 或者api
+      console.warn(
+        `[Vben Drawer]: When 'connectedComponent' exists, do not set props or slots '${attr}', which will increase complexity. If you need to modify the props of Drawer, please use useVbenDrawer or api.`,
+      );
+    }
+  }
+}

packages/@core/ui-kit/popup-ui/src/index.ts

@@ -0,0 +1,3 @@
+export * from './alert';
+export * from './drawer';
+export * from './modal';

packages/@core/ui-kit/popup-ui/src/modal/__tests__/modal-api.test.ts

@@ -0,0 +1,117 @@
+import type { ModalState } from '../modal';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ModalApi } from '../modal-api';
+
+vi.mock('@vben-core/shared/store', () => {
+  return {
+    isFunction: (fn: any) => typeof fn === 'function',
+    Store: class {
+      get state() {
+        return this._state;
+      }
+      private _state: ModalState;
+
+      private options: any;
+
+      constructor(initialState: ModalState, options: any) {
+        this._state = initialState;
+        this.options = options;
+      }
+
+      batch(cb: () => void) {
+        cb();
+      }
+
+      setState(fn: (prev: ModalState) => ModalState) {
+        this._state = fn(this._state);
+        this.options.onUpdate();
+      }
+    },
+  };
+});
+
+describe('modalApi', () => {
+  let modalApi: ModalApi;
+  // 使用 modalState 而不是 state
+  let modalState: ModalState;
+
+  beforeEach(() => {
+    modalApi = new ModalApi();
+    // 获取 modalApi 内的 state
+    modalState = modalApi.store.state;
+  });
+
+  it('should initialize with default state', () => {
+    expect(modalState.isOpen).toBe(false);
+    expect(modalState.cancelText).toBe(undefined);
+    expect(modalState.confirmText).toBe(undefined);
+  });
+
+  it('should open the modal', () => {
+    modalApi.open();
+    expect(modalApi.store.state.isOpen).toBe(true);
+  });
+
+  it('should close the modal if onBeforeClose allows it', () => {
+    modalApi.close();
+    expect(modalApi.store.state.isOpen).toBe(false);
+  });
+
+  it('should not close the modal if onBeforeClose returns false', () => {
+    const onBeforeClose = vi.fn(() => false);
+    const modalApiWithHook = new ModalApi({ onBeforeClose });
+    modalApiWithHook.open();
+    modalApiWithHook.close();
+    expect(modalApiWithHook.store.state.isOpen).toBe(true);
+    expect(onBeforeClose).toHaveBeenCalled();
+  });
+
+  it('should trigger onCancel and close the modal if no onCancel hook is provided', () => {
+    const onCancel = vi.fn();
+    const modalApiWithHook = new ModalApi({ onCancel });
+    modalApiWithHook.open();
+    modalApiWithHook.onCancel();
+    expect(onCancel).toHaveBeenCalled();
+    expect(modalApiWithHook.store.state.isOpen).toBe(true);
+  });
+
+  it('should update shared data correctly', () => {
+    const testData = { key: 'value' };
+    modalApi.setData(testData);
+    expect(modalApi.getData()).toEqual(testData);
+  });
+
+  it('should set state correctly using an object', () => {
+    modalApi.setState({ title: 'New Title' });
+    expect(modalApi.store.state.title).toBe('New Title');
+  });
+
+  it('should set state correctly using a function', () => {
+    modalApi.setState((prev) => ({ ...prev, confirmText: 'Yes' }));
+    expect(modalApi.store.state.confirmText).toBe('Yes');
+  });
+
+  it('should call onOpenChange when state changes', () => {
+    const onOpenChange = vi.fn();
+    const modalApiWithHook = new ModalApi({ onOpenChange });
+    modalApiWithHook.open();
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it('should call onClosed callback when provided', () => {
+    const onClosed = vi.fn();
+    const modalApiWithHook = new ModalApi({ onClosed });
+    modalApiWithHook.onClosed();
+    expect(onClosed).toHaveBeenCalled();
+  });
+
+  it('should call onOpened callback when provided', () => {
+    const onOpened = vi.fn();
+    const modalApiWithHook = new ModalApi({ onOpened });
+    modalApiWithHook.open();
+    modalApiWithHook.onOpened();
+    expect(onOpened).toHaveBeenCalled();
+  });
+});

packages/@core/ui-kit/popup-ui/src/modal/index.ts

@@ -0,0 +1,3 @@
+export type * from './modal';
+export { default as VbenModal } from './modal.vue';
+export { setDefaultModalProps, useVbenModal } from './use-modal';

packages/@core/ui-kit/popup-ui/src/modal/use-modal.ts

@@ -0,0 +1,151 @@
+import type { ExtendedModalApi, ModalApiOptions, ModalProps } from './modal';
+
+import {
+  defineComponent,
+  h,
+  inject,
+  nextTick,
+  provide,
+  reactive,
+  ref,
+} from 'vue';
+
+import { useStore } from '@vben-core/shared/store';
+
+import { ModalApi } from './modal-api';
+import VbenModal from './modal.vue';
+
+const USER_MODAL_INJECT_KEY = Symbol('VBEN_MODAL_INJECT');
+
+const DEFAULT_MODAL_PROPS: Partial<ModalProps> = {};
+
+export function setDefaultModalProps(props: Partial<ModalProps>) {
+  Object.assign(DEFAULT_MODAL_PROPS, props);
+}
+
+export function useVbenModal<TParentModalProps extends ModalProps = ModalProps>(
+  options: ModalApiOptions = {},
+) {
+  // Modal一般会抽离出来，所以如果有传入 connectedComponent，则表示为外部调用，与内部组件进行连接
+  // 外部的Modal通过provide/inject传递api
+
+  const { connectedComponent } = options;
+  if (connectedComponent) {
+    const extendedApi = reactive({});
+    const isModalReady = ref(true);
+    const Modal = defineComponent(
+      (props: TParentModalProps, { attrs, slots }) => {
+        provide(USER_MODAL_INJECT_KEY, {
+          extendApi(api: ExtendedModalApi) {
+            // 不能直接给 reactive 赋值，会丢失响应
+            // 不能用 Object.assign,会丢失 api 的原型函数
+            Object.setPrototypeOf(extendedApi, api);
+          },
+          options,
+          async reCreateModal() {
+            isModalReady.value = false;
+            await nextTick();
+            isModalReady.value = true;
+          },
+        });
+        checkProps(extendedApi as ExtendedModalApi, {
+          ...props,
+          ...attrs,
+          ...slots,
+        });
+        return () =>
+          h(
+            isModalReady.value ? connectedComponent : 'div',
+            {
+              ...props,
+              ...attrs,
+            },
+            slots,
+          );
+      },
+      // eslint-disable-next-line vue/one-component-per-file
+      {
+        name: 'VbenParentModal',
+        inheritAttrs: false,
+      },
+    );
+
+    return [Modal, extendedApi as ExtendedModalApi] as const;
+  }
+
+  const injectData = inject<any>(USER_MODAL_INJECT_KEY, {});
+
+  const mergedOptions = {
+    ...DEFAULT_MODAL_PROPS,
+    ...injectData.options,
+    ...options,
+  } as ModalApiOptions;
+
+  mergedOptions.onOpenChange = (isOpen: boolean) => {
+    options.onOpenChange?.(isOpen);
+    injectData.options?.onOpenChange?.(isOpen);
+  };
+
+  const onClosed = mergedOptions.onClosed;
+  mergedOptions.onClosed = () => {
+    onClosed?.();
+    if (mergedOptions.destroyOnClose) {
+      injectData.reCreateModal?.();
+    }
+  };
+
+  const api = new ModalApi(mergedOptions);
+
+  const extendedApi: ExtendedModalApi = api as never;
+
+  extendedApi.useStore = (selector) => {
+    return useStore(api.store, selector);
+  };
+
+  const Modal = defineComponent(
+    (props: ModalProps, { attrs, slots }) => {
+      return () =>
+        h(
+          VbenModal,
+          {
+            ...props,
+            ...attrs,
+            modalApi: extendedApi,
+          },
+          slots,
+        );
+    },
+    // eslint-disable-next-line vue/one-component-per-file
+    {
+      name: 'VbenModal',
+      inheritAttrs: false,
+    },
+  );
+  injectData.extendApi?.(extendedApi);
+
+  return [Modal, extendedApi] as const;
+}
+
+async function checkProps(api: ExtendedModalApi, attrs: Record<string, any>) {
+  if (!attrs || Object.keys(attrs).length === 0) {
+    return;
+  }
+  await nextTick();
+
+  const state = api?.store?.state;
+
+  if (!state) {
+    return;
+  }
+
+  const stateKeys = new Set(Object.keys(state));
+
+  for (const attr of Object.keys(attrs)) {
+    if (stateKeys.has(attr) && !['class'].includes(attr)) {
+      // connectedComponent存在时，不要传入Modal的props，会造成复杂度提升，如果你需要修改Modal的props，请使用 useModal 或者api
+      console.warn(
+        `[Vben Modal]: When 'connectedComponent' exists, do not set props or slots '${attr}', which will increase complexity. If you need to modify the props of Modal, please use useVbenModal or api.`,
+      );
+    }
+  }
+}

packages/@core/ui-kit/popup-ui/tailwind.config.mjs

@@ -0,0 +1 @@
+export { default } from '@vben/tailwind-config';

packages/@core/ui-kit/popup-ui/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@vben/tsconfig/web.json",
+  "include": ["src"],
+  "exclude": ["node_modules"]
+}