vue-popup-plus 1.4.0 → 1.5.1

package/README.md

@@ -0,0 +1,86 @@
+# Vue Popup Plus 🚀
+
+一个功能强大、灵活易用的 Vue 3 弹窗组件库，让弹窗管理变得简单而优雅。
+
+[![Vue 3](https://img.shields.io/badge/Vue-3.x-brightgreen.svg)](https://vuejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)](https://github.com/yourusername/vue-popup-plus)
+
+## ✨ 特性
+
+- 🎯 **简单易用** - 简洁的 API，快速集成到您的项目中
+- 🔌 **可扩展** - 自定义弹窗内容和样式，满足各种场景需求
+- 🎭 **动画支持** - 内置多种动画效果，让弹窗展示更生动
+- 📱 **响应式设计** - 完美适配各种屏幕尺寸
+- 🧩 **TypeScript 支持** - 完整的类型定义，提供良好的开发体验
+
+## 📦 安装
+
+```bash
+# 使用 npm
+npm install vue-popup-plus
+
+# 使用 yarn
+yarn add vue-popup-plus
+
+# 使用 pnpm
+pnpm add vue-popup-plus
+```
+
+## 📚 文档
+
+查看我们的[在线文档](http://vue-popup-plus.styzy.cn)获取更多详细信息和高级用法。
+
+## 🚀 快速开始
+
+### 全局注册
+
+```js
+import { createApp } from 'vue'
+import { createPopup } from 'vue-popup-plus'
+import App from './App.vue'
+
+const app = createApp(App)
+const popup = createPopup()
+
+app.use(popup)
+
+app.mount('#app')
+```
+
+### 基本使用
+
+```vue
+<template>
+	<button @click="showPopup">显示弹窗</button>
+</template>
+
+<script setup>
+import { usePopup } from 'vue-popup-plus'
+
+const popup = usePopup()
+
+const showPopup = () => {
+	popup.render({
+		// 组件
+		component: () => import('./components/Demo.vue'),
+		// 组件属性
+		componentProps: {
+			// 根据你的组件属性传入
+		},
+		width: 400,
+		maxHeight: 600,
+		mask: false,
+	})
+}
+</script>
+```
+
+## 🤝 贡献
+
+欢迎贡献代码、报告问题或提出新功能建议！请查看[贡献指南](CONTRIBUTING.md)了解更多信息。
+
+## 📄 许可证
+
+[MIT](LICENSE) © Your Name

package/dist/vue-popup-plus.d.ts

@@ -1,8 +1,14 @@
+import { AllowedComponentProps } from 'vue';
 import { App } from 'vue';
+import { AsyncComponentLoader } from 'vue';
 import { Component } from 'vue';
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
 import { ComputedRef } from 'vue';
+import { DefineComponent } from 'vue';
 import { InjectionKey } from 'vue';
-import { version } from '../package.json';
+import { PublicProps } from 'vue';
+import { VNodeProps } from 'vue';
 
 declare type Animation_2 = IAnimations[keyof IAnimations];
 
@@ -130,13 +136,21 @@ export declare type CreateOption = {
      * ```
      */
     prototypeName?: string;
+    /**
+     * 日志器
+     *
+     * - 默认使用内置的日志器，仅会在开启调试模式时在控制台输出日志
+     * - 你可以自定义日志器，需要注意日志的接收将不会受到调试模式的影响，
+     *   无论调试模式是否开启，日志都将被传递给自定义的日志器。
+     */
+    logHandler?: ILogHandler;
     /**
      * 开启调试模式
      *
      * - 默认为 false
      * - 注意：开启调试模式可能会影响到性能，不建议在生产环境开启。
-     * - 开启后，所有的弹出层将以 Vue app 应用实例的方式创建，可通过 Vue DevTools
-     *   开发者工具直接访问到内部的相关组件，方便开发者调试。
+     * - 开启后，将会在控制台输出日志，同时如果未注册根组件，调试模式下
+     *   将会使用 Vue App 实例渲染弹出层，方便开发者调试。
      */
     debugMode?: boolean;
 };
@@ -144,7 +158,7 @@ export declare type CreateOption = {
 /**
  * 创建一个弹出层控制器实例
  *
- * - 该实例需要通过 app.use() 安装后才能使用
+ * - 该实例需要被 Vue 的 app.use() 函数后才能使用
  *
  * @param options 创建配置，具体请参考 {@link CreateOption}
  * @returns 弹出层控制器实例
@@ -153,6 +167,35 @@ export declare function createPopup(options?: CreateOption): IController;
 
 export declare const definePlugin: IDefinePlugin;
 
+declare type ErrorOption = {
+    namespace: string;
+    caller: string;
+    message: string;
+} | ILog;
+
+/**
+ * 提取组件的 props 所允许的所有类型
+ *
+ * - 相较于 `ExtractComponentPropTypes` 返回的类型，还提供了底层对 `VNodeProps`
+ *  和 `AllowedComponentProps` 类型属性的支持
+ * - 支持同步组件和异步组件
+ * - 对于异步组件，除了支持 `defineAsyncComponent` 方法定义组件，还支持直接传入
+ *   ()=>import() 函数。
+ */
+declare type ExtractComponentAllPropTypes<TComponent extends Component = Component> = WithDefaultProps<TComponent extends new () => {
+    $props: infer TProps;
+} ? TProps : TComponent extends AsyncComponentLoader ? InstanceType<Awaited<ReturnType<TComponent>>['default']>['$props'] : Record<string, any>>;
+
+/**
+ * 提取组件的 props 类型
+ *
+ * - 包含组件自定义的属性类型以及通过 `ComponentCustomProps` 接口定义的全局属性类型
+ * - 支持同步组件和异步组件
+ * - 对于异步组件，除了支持 `defineAsyncComponent` 方法定义组件，还支持直接传入
+ *   ()=>import() 函数。
+ */
+export declare type ExtractComponentPropTypes<TComponent extends Component = Component> = Omit<ExtractComponentAllPropTypes<TComponent>, keyof (VNodeProps & AllowedComponentProps)>;
+
 declare type ExtractPluginOption<TPlugin extends PopupPlugin> = TPlugin extends PopupPlugin<infer TOption> ? TOption : never;
 
 declare interface IAnimations extends PopupCustomAnimations {
@@ -194,18 +237,19 @@ declare interface IController extends PopupCustomProperties {
     /**
      * 版本号
      */
-    readonly version: string;
+    readonly version: Version;
     /**
      * 安装插件
      *
      * @param {App} app - Vue应用实例
-     * @returns {void}
+     * @returns {any}
      */
-    install(app: App): void;
+    install(app: App): any;
     /**
-     * 安装插件
+     * 注册插件
      *
-     * - 可安装使用 `definePlugin` 方法定义的插件
+     * - 可注册使用 `definePlugin()` 方法定义的插件
+     * - 重复注册相同的插件，会被忽略
      * - 具体请参考{@link IDefinePlugin}
      */
     use<TOption extends PluginOption, TPlugin extends PopupPlugin<TOption>>(plugin: TPlugin, options?: ExtractPluginOption<TPlugin>): void;
@@ -216,7 +260,7 @@ declare interface IController extends PopupCustomProperties {
      *   是唯一的必填项，其他渲染参数具体请参考{@link RenderOption}
      * - 返回值是弹出层的实例 id ，用于调用 destroy() 方法销毁弹出层
      */
-    render(options: RenderOption): InstanceId;
+    render<TComponent extends Component = Component>(options: RenderOption<TComponent>): InstanceId;
     /**
      * 更新弹出层
      *
@@ -231,6 +275,7 @@ declare interface IController extends PopupCustomProperties {
      * - 传入弹出层的实例 id ，用于销毁指定的弹出层
      * - 第二个参数是自定义负载参数，会作为参数传递给创建弹出层时的 onUnmounted 回调函数
      * - 该函数返回一个 Promise 对象，用于等待弹出层关闭动画完成
+     * - 如果弹出层不存在，会在调试模式下打印警告日志
      */
     destroy(instanceId: InstanceId, payload?: any): void;
 }
@@ -239,11 +284,14 @@ declare interface IDefinePlugin {
     /**
      * 定义插件
      *
-     * - 该方法用于定义一个可以直接被 `popup.use` 方法安装的插件
+     * - 该方法用于定义一个可以直接被 `popup.use` 方法注册的插件
      * - 插件的名称 `name` 必须唯一
+     * - 插件的作者 `author` 可以是个人或组织名称
+     * - 插件的核心版本要求 `coreVersion` 可以指定插件所适配的最低和最高核心版本，
+     * 不符合要求的核心将无法注册该插件
      * - 插件的安装函数 `install` 必须是一个函数，接收三个参数：
-     *   - 第一个参数接收安装此插件的弹出层控制器实例
-     *   - 第二个参数接收安装此插件的弹出层的创建配置
+     *   - 第一个参数接收注册此插件的弹出层控制器实例
+     *   - 第二个参数接收注册此插件的弹出层的创建配置
      *   - 第三个参数接收插件自定义选项，可自行定义，插件使用者可在调用
      *  `popup.use` 方法时传入
      * - 使用示例：
@@ -258,6 +306,11 @@ declare interface IDefinePlugin {
      *
      * const plugin = definePlugin({
      * 	name: 'test',
+     * 	author: 'your name',
+     * 	coreVersionValidator(coreVersion){
+     * 		const requiredVersion = '1.5.0'
+     * 		return coreVersion >= requiredVersion
+     * 	},
      * 	install(popup, config, { logEnable = false }: TestPluginOption = {}) {
      * 		popup.customProperties.test = function (message) {
      * 			this.render({
@@ -289,8 +342,45 @@ declare interface IInstanceId {
     name: Readonly<string>;
 }
 
+export declare interface ILog {
+    /**
+     * 命名空间
+     */
+    namespace: string;
+    /**
+     * 类型
+     */
+    type: LogType;
+    /**
+     * 调用者
+     */
+    caller: string;
+    /**
+     * 消息
+     */
+    message: string;
+    /**
+     * 日志组
+     */
+    group: LogGroup;
+    readonly hasCaller: boolean;
+    /**
+     * 是否有日志组
+     */
+    readonly hasGroup: boolean;
+}
+
+export declare interface ILogHandler {
+    /**
+     * 日志处理函数
+     *
+     * @param log 日志实例
+     */
+    (log: ILog): any;
+}
+
 export declare class InstanceId implements IInstanceId {
-    #private;
+    private _seed;
     get seed(): number;
     get name(): string;
     constructor(seed: number);
@@ -349,6 +439,125 @@ declare interface IPluginWrappedController extends IController {
     readonly customAnimations: PopupCustomAnimations;
 }
 
+export declare class Log implements ILog {
+    namespace: string;
+    type: LogType;
+    caller: string;
+    message: string;
+    group: LogGroup;
+    get hasCaller(): boolean;
+    get hasGroup(): boolean;
+    /**
+     * 创建日志实例
+     *
+     * @param type 日志类型
+     * @param name 日志名称
+     * @param message 日志消息
+     * @param group 日志组
+     * @returns 日志实例
+     */
+    constructor({ type, caller, message, group, }?: LogOption);
+}
+
+export declare type LogGroup = Array<LogGroupItem>;
+
+declare type LogGroupDataItem = {
+    /**
+     * 数据组元素类型
+     */
+    type: typeof LogGroupItemType.Data;
+    /**
+     * 数据项名称
+     */
+    dataName: string;
+    /**
+     * 数据项值
+     */
+    dataValue: any;
+    /**
+     * 数据项约束类型
+     *
+     * - 如不传，将自动设置为 any
+     */
+    dataType?: string;
+};
+
+declare type LogGroupDefaultItem = {
+    /**
+     * 组元素类型
+     */
+    type?: typeof LogGroupItemType.Default;
+    /**
+     * 组元素消息
+     */
+    message: string;
+};
+
+declare type LogGroupItem = LogGroupDefaultItem | LogGroupDataItem;
+
+/**
+ * 日志组元素类型
+ */
+export declare const LogGroupItemType: {
+    /**
+     * 默认类型
+     */
+    readonly Default: "default";
+    /**
+     * 数据类型
+     */
+    readonly Data: "data";
+};
+
+export declare type LogGroupItemType = (typeof LogGroupItemType)[keyof typeof LogGroupItemType];
+
+export declare type LogOption = {
+    /**
+     * 日志类型
+     */
+    type?: LogType;
+    /**
+     * 日志调用者
+     */
+    caller?: string;
+    /**
+     * 日志消息
+     */
+    message?: string;
+    /**
+     * 日志组
+     *
+     * - 用于在日志消息中展示多个数据项
+     */
+    group?: LogGroup;
+};
+
+/**
+ * 日志类型
+ */
+export declare const LogType: {
+    /**
+     * 成功日志
+     */
+    readonly Success: "success";
+    /**
+     * 信息日志
+     */
+    readonly Info: "info";
+    /**
+     * 警告日志
+     */
+    readonly Warning: "warning";
+    /**
+     * 错误日志
+     */
+    readonly Error: "error";
+};
+
+export declare type LogType = (typeof LogType)[keyof typeof LogType];
+
+export declare type Placement = 'left-top' | 'left' | 'left-bottom' | 'top' | 'center' | 'bottom' | 'right-top' | 'right' | 'right-bottom';
+
 declare type PluginInstall<TOption extends PluginOption> = (controller: IPluginWrappedController, config: Readonly<CoreConfig>, option?: TOption) => void;
 
 declare type PluginOption = Record<string, any>;
@@ -368,24 +577,76 @@ export declare interface PopupCustomAnimations {
 export declare interface PopupCustomProperties {
 }
 
+export declare class PopupError extends Error {
+    /**
+     * 弹出层错误类
+     *
+     * - 建议从 {@link ILog} 日志实例创建错误
+     * @param {ErrorOption} options 错误参数
+     * @example
+     * new PopupError(new Log({
+     * 	type: LogType.Error,
+     * 	caller: 'controller.render()',
+     * 	message: '弹出层渲染失败',
+     * }))
+     */
+    constructor({ namespace, caller, message }: ErrorOption);
+}
+
 export declare type PopupPlugin<TOption extends PluginOption = never> = {
     /**
      * 插件名称
      *
      * - 插件名称必须唯一
+     * - 名称冲突将导致插件注册失败
      */
     name: string;
     /**
      * 插件安装函数
      *
-     * - 第一个参数接收安装此插件的弹出层控制器实例
-     * - 第二个参数接收安装此插件的弹出层的创建配置
+     * - 第一个参数接收注册此插件的弹出层控制器实例
+     * - 第二个参数接收注册此插件的弹出层的创建配置
      * - 第三个参数接收插件自定义选项，可自行定义，插件使用者可在调用
      *  `popup.use` 方法时传入
      */
     install: PluginInstall<TOption>;
+    /**
+     * 插件作者
+     *
+     * - 插件作者可以是个人或组织名称
+     * - 从核心 `1.5.0` 版本开始，不设置插件作者将会导致在插件注册时
+     * 通过日志输出一个警告，用以提示插件使用者相关风险
+     */
+    author?: string;
+    /**
+     * 插件核心版本校验函数
+     *
+     * - 插件作者需要在插件安装函数中校验弹出层核心版本是否符合插件要求
+     * - 该函数需要返回一个布尔值，`true` 表示核心版本符合要求，`false`
+     * 表示不符合要求，核心将会阻止该插件的注册
+     * - 从核心 `1.5.0` 版本开始，不设置该校验函数将会导致在插件注册时
+     * 通过日志输出一个警告，用以提示插件使用者相关风险
+     */
+    /**
+     * 插件核心版本要求
+     *
+     * - 插件作者可以指定插件所适配的最低和最高核心版本
+     * - 不符合要求的核心将无法注册该插件
+     */
+    requiredCoreVersion?: {
+        /**
+         * 插件所适配的最低核心版本
+         */
+        min?: Version;
+        /**
+         * 插件所适配的最高核心版本
+         */
+        max?: Version;
+    };
 };
 
+export declare const PopupRoot: DefineComponent<    {}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+
 declare type PopupViewStyle = ComputedRef<{
     width: number;
     height: number;
@@ -394,7 +655,16 @@ declare type PopupViewStyle = ComputedRef<{
     translateY: number;
 }>;
 
-declare type RenderComponentOptions = {
+/**
+ * 打印日志
+ *
+ * - 仅在开启调试模式时打印输出日志
+ * @param log 日志实例
+ * @returns
+ */
+export declare const printLog: ILogHandler;
+
+declare type RenderComponentOptions<TComponent extends Component = Component> = {
     /**
      * 弹出层渲染的组件
      *
@@ -417,11 +687,14 @@ declare type RenderComponentOptions = {
      * })
      * ```
      */
-    component: Component;
+    component: TComponent;
     /**
      * 弹出层渲染组件的 props ，会传递给弹出层组件
+     * - 会自动根据传入的组件进行类型推导，提供完善的类型提示
+     * - 除了组件的属性，还支持传入组件的事件监听器，事件监听器的名称需要以 `on` 开头，
+     *   例如 `onClick` 、 `onInput` 等。
      */
-    componentProps?: Record<string, any>;
+    componentProps?: ExtractComponentPropTypes<TComponent>;
     /**
      * 弹出层渲染之后的回调
      */
@@ -459,7 +732,7 @@ declare type RenderConfigOptions = {
     disableScroll?: boolean;
 };
 
-export declare type RenderOption = RenderConfigOptions & RenderComponentOptions & RenderStyleOptions;
+export declare type RenderOption<TComponent extends Component = Component> = RenderComponentOptions<TComponent> & RenderConfigOptions & RenderStyleOptions;
 
 declare type RenderStyleOptions = {
     /**
@@ -600,6 +873,14 @@ declare type RenderStyleOptions = {
      * 	minHeight: 300,
      */
     minHeight?: string | number;
+    /**
+     * 弹出层位置
+     *
+     * - 默认为 center ，即居中显示
+     * - 更多位置请查看 {@link Placement}
+     * @since 1.5.0
+     */
+    placement?: Placement;
     /**
      * 弹出层视图动画类型
      *
@@ -633,7 +914,10 @@ declare type RenderStyleOptions = {
      */
     maskAnimation?: Animation_2;
     /**
-     * 弹出层遮罩是否启用模糊效果，默认为 true
+     * 弹出层遮罩是否启用模糊效果
+     *
+     * - 默认为 true
+     * @since 1.3.0
      */
     maskBlur?: boolean;
     /**
@@ -655,11 +939,18 @@ export declare type UpdateOption = Partial<RenderStyleOptions>;
 /**
  * 获取弹出层控制器实例
  *
+ * - 必须先调用 {@link createPopup} 创建弹出层控制器实例，才能使用该函数
+ * ，否则会抛出异常
+ *
  * @returns 弹出层控制器实例
  */
 export declare function usePopup(): IController;
 
-export { version }
+export declare type Version = `${number}.${number}.${number}`;
+
+export declare const version: Version;
+
+declare type WithDefaultProps<T> = T extends Record<string, any> ? T : Record<string, any>;
 
 export { }