vue-popup-plus 1.0.0 → 1.1.0

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

@@ -1,56 +1,115 @@
 import { App } from 'vue';
 import { Component } from 'vue';
+import { ComputedRef } from 'vue';
 import { InjectionKey } from 'vue';
 import { version } from '../package.json';
 
+declare type Animation_2 = IAnimations[keyof IAnimations];
+
 /**
  * 组件注入键类型
  */
 declare type ComponentInjectKeys = {
     /**
-     * 当前组件所在弹出层的实例ID，可用于销毁当前弹出层
-     * @example
+     * 当前组件所在弹出层的实例ID
+     * - 可用于销毁当前弹出层
+     * - 使用示例：
+     * ```ts
      * // 弹出层渲染的所有子代组件中
-     * const instanceId = inject(POPUP_COMPONENT_INJECT_KEYS.INSTANCE_ID)
+     * import { inject } from 'vue'
+     * import { usePopup, POPUP_COMPONENT_INJECTS } from 'vue-popup-plus'
+     *
+     * // 获取弹出层控制器
+     * const popup = usePopup()
+     *
+     * // 获取当前组件所在弹出层的实例ID
+     * const instanceId = inject(POPUP_COMPONENT_INJECTS.INSTANCE_ID)
      *
      * // 销毁当前弹出层
-     * this.$popup.destroy(instanceId)
+     * popup.destroy(instanceId)
+     * ```
      */
     INSTANCE_ID: InjectionKey<InstanceId>;
+    /**
+     * 弹出层视图样式
+     * - 可在弹出层内部组件内获取弹出层根级视图组件的样式
+     * - 使用示例：
+     * ```ts
+     * // 弹出层渲染的所有子代组件中
+     * import { inject } from 'vue'
+     * import { usePopup, POPUP_COMPONENT_INJECTS } from 'vue-popup-plus'
+     *
+     * // 获取弹出层控制器
+     * const popup = usePopup()
+     *
+     * // 获取当前组件所在弹出层的实例ID
+     * const instanceId = inject(POPUP_COMPONENT_INJECTS.INSTANCE_ID)
+     *
+     * // 获取弹出层根级视图组件的样式
+     * const computedViewStyle = inject(POPUP_COMPONENT_INJECTS.COMPUTED_VIEW_STYLE)
+     * ```
+     */
+    COMPUTED_VIEW_STYLE: InjectionKey<PopupViewStyle>;
+};
+
+declare type ControllerPrototype = Record<string, string | boolean | number | symbol | object | null | undefined | bigint | ControllerPrototypeFunctionValue> & {
+    render: '内置 render 方法';
+    update: '内置 update 方法';
+    destroy: '内置 destroy 方法';
+    install: '内置 install 方法';
+    use: '内置 use 方法';
 };
 
+declare type ControllerPrototypeFunctionValue = (this: IController, ...args: any[]) => any;
+
+declare type CoreConfig = Required<CoreOptions>;
+
 declare type CoreOptions = {
     /**
-     * 弹出层 zIndex 基础值，默认为1000，每次生成弹出层时，除非 render() 方法传入 zIndex，否则使用此基础值，每次使用后会自动递增
+     * 弹出层 zIndex 基础值
+     * - 默认为1000，每次生成弹出层时，除非 render() 方法传入 zIndex，否则使用此基础值，每次使用后会自动递增
      */
     zIndex?: number;
     /**
-     * 弹出层控制器挂载在 Vue 实例上的属性名，默认为 $popup ，这在使用选项式API时可以在组件内通过this.$popup 访问控制器实例，如需自定义属性名，请参考如下代码：
+     * 是否自动禁用滚动
+     * - 默认为 true
+     * - 开启后，弹出层显示时会自动禁用页面滚动
+     */
+    autoDisableScroll?: boolean;
+    /**
+     * 弹出层控制器挂载在 Vue 实例上的属性名
+     * - 默认为 $popup ，这在使用选项式API时可以在组件内通过this.$popup 访问控制器实例，可以使用该属性自定义挂载属性名
+     * - 使用示例：
+     * ```ts
+     * // main.ts
+     * import { createPopup } from 'vue-popup-plus'
      *
-     * @example
-     * // 初始化插件
-     * createPopup({
+     * const popup = createPopup({
      * 	prototypeName: '$customPopup'
      * })
      *
-     * // 在组件内访问
+     * // 组件内
      * this.$customPopup.render({
      * 	component: Demo,
      * })
-     * @end
-     * @important 注意，如果你使用 TypeScript，则自定义属性名称需要手动同步添加类型扩展，扩展代码可以放在一个 .ts 文件，或是一个影响整个项目的 *.d.ts 文件中。
-     * @example
-     * // 添加导出，没有该代码将无法有效扩展
-     * export {}
-     *
-     * // 自定义扩展
+     * ```
+     * - 注意，如果你使用 TypeScript，则自定义属性名称需要手动同步添加类型扩展，扩展代码可以放在一个 .ts 文件，或是一个影响整个项目的 *.d.ts 文件中。
+     * - 扩展代码示例：
+     * ```ts
+     * // 扩展自定义属性名类型
      * declare module 'vue' {
      * 	interface ComponentCustomProperties {
-     * 		$customPopup: VuePopupPlusController
+     * 		$customPopup: typeof popup
      * 	}
      * }
      */
     prototypeName?: string;
+    /**
+     * 开启调试模式
+     * - 默认为 false
+     * - 开启后，会提供开发调试功能
+     */
+    debugMode?: boolean;
 };
 
 /**
@@ -58,64 +117,58 @@ declare type CoreOptions = {
  * @param options 弹出层核心配置
  * @returns 弹出层控制器实例
  */
-export declare function createPopup(options?: CoreOptions): PopupController;
+export declare function createPopup(options?: CoreOptions): IController;
 
-declare class InstanceId implements PopupInstanceId {
-    #private;
-    get seed(): number;
-    get name(): string;
-    constructor(seed: number);
-}
-
-/**
- * 动画类型集合
- */
-export declare const POPUP_ANIMATIONS: Readonly<PopupAnimationCollection>;
-
-/**
- * 弹出层内部组件注入属性，在弹出层内部渲染的所有子代组件中，都可以通过 inject 注入弹出层所提供的相关参数
- */
-export declare const POPUP_COMPONENT_INJECT_KEYS: Readonly<ComponentInjectKeys>;
+export declare const definePlugin: IDefinePlugin;
 
-/**
- * 动画类型集合类型
- */
-declare interface PopupAnimationCollection {
+declare interface IAnimations extends PopupCustomAnimations {
     /**
      * 无动画
      */
-    NONE: symbol;
+    readonly NONE: 'none';
     /**
      * 淡入淡出
      */
-    FADE: symbol;
+    readonly FADE: 'fade';
     /**
      * 缩放放大
      */
-    SCALE_ENLARGE: symbol;
+    readonly SCALE_ENLARGE: 'scale-enlarge';
     /**
      * 缩放缩小
      */
-    SCALE_SHRINK: symbol;
+    readonly SCALE_SHRINK: 'scale-shrink';
     /**
      * 顶部飞入
      */
-    FLY_TOP: symbol;
+    readonly FLY_TOP: 'fly-top';
     /**
      * 左侧飞入
      */
-    FLY_LEFT: symbol;
+    readonly FLY_LEFT: 'fly-left';
     /**
      * 右侧飞入
      */
-    FLY_RIGHT: symbol;
+    readonly FLY_RIGHT: 'fly-right';
     /**
      * 底部飞入
      */
-    FLY_BOTTOM: symbol;
+    readonly FLY_BOTTOM: 'fly-bottom';
 }
 
-declare interface PopupController extends PopupCustomController {
+declare interface IController extends PopupCustomProperties {
+    /**
+     * 安装插件
+     * @param {App} app - Vue应用实例
+     * @returns {void}
+     */
+    install(app: App): void;
+    /**
+     * 安装插件
+     * - 可安装使用 `definePlugin` 方法定义的插件
+     * - 具体请参考{@link IDefinePlugin}
+     */
+    use(plugin: Plugin_2): void;
     /**
      * 渲染弹出层，返回弹出层实例id，可调用destroy(id)方法销毁弹出层
      * @param {RenderOptions} options - 渲染参数
@@ -135,21 +188,41 @@ declare interface PopupController extends PopupCustomController {
      * @returns {Promise<void>}
      */
     destroy(instanceId: InstanceId, payload?: any): void;
-    /**
-     * 安装插件
-     * @param {App} app - Vue应用实例
-     * @returns {void}
-     */
-    install(app: App): void;
 }
 
-declare interface PopupCustomController {
+declare interface IDefinePlugin {
+    /**
+     * 定义插件
+     * - 插件是一个对象，包含插件名称和安装方法
+     * - 安装方法接收一个可扩展自定义属性的控制器实例作为参数，用于扩展弹出层插件的原型属性
+     * - 使用示例：
+     * ```ts
+     * import { createPopup, definePlugin } from 'vue-popup-plus'
+     * const popup = createPopup()
+     * const plugin = definePlugin({
+     * 	// 插件名称，必须唯一
+     * 	name: 'test',
+     * 	// 插件安装时的回调函数，会将控制器实例作为参数传入
+     * 	install(popup) {
+     * 		popup.customProperties.test = function (message) {
+     * 			this.render({
+     * 				component: () => import('path/Demo.vue'),
+     * 				componentProps: {
+     * 					message,
+     * 				},
+     * 			})
+     * 		}
+     * 	},
+     * })
+     * ```
+     */
+    (options: Plugin_2): Plugin_2;
 }
 
 /**
  * 实例 id 接口
  */
-declare interface PopupInstanceId {
+declare interface IInstanceId {
     /* Excluded from this release type: seed */
     /**
      * 实例 id 名称
@@ -157,6 +230,90 @@ declare interface PopupInstanceId {
     name: Readonly<string>;
 }
 
+declare class InstanceId implements IInstanceId {
+    #private;
+    get seed(): number;
+    get name(): string;
+    constructor(seed: number);
+}
+
+declare interface IPluginWrappedController extends IController {
+    /**
+     * 原型属性
+     * - 可在插件的 `install` 方法中扩展方法或属性
+     * - 该属性为只读属性，只允许扩展，并且内置方法不能被覆盖
+     * - 使用示例：
+     * ```ts
+     * // 插件中扩展方法
+     * import { definePlugin } from 'vue-popup-plus'
+     *
+     * const plugin = definePlugin({
+     * 	name: 'test',
+     * 	install(popup) {
+     * 		popup.customProperties.test = function (message: string) {
+     * 			this.render({
+     * 				component: () => import('./views/Demo.vue'),
+     * 				componentProps: {
+     * 					message,
+     * 				},
+     * 			})
+     * 		}
+     * 	},
+     * })
+     *
+     * // 调用
+     * popup.test('hello world')
+     * ```
+     */
+    readonly customProperties: ControllerPrototype;
+    /**
+     * 自定义动画类型
+     * - 可在插件的 `install` 方法中扩展动画类型
+     * - 该属性为只读属性，只允许扩展，并且内置动画类型不能被覆盖
+     * - 使用示例：
+     * ```ts
+     * // 插件中扩展动画类型
+     * import { definePlugin } from 'vue-popup-plus'
+     *
+     * const plugin = definePlugin({
+     * 	name: 'test',
+     * 	install(popup) {
+     * 		popup.customAnimations.CUSTOM = 'CUSTOM'
+     * 	},
+     * })
+     * ```
+     */
+    readonly customAnimations: PopupCustomAnimations;
+}
+
+declare type Plugin_2 = {
+    name: string;
+    install: PluginInstall;
+};
+
+declare type PluginInstall = (controller: IPluginWrappedController, config: Readonly<CoreConfig>) => void;
+
+export declare const POPUP_ANIMATIONS: IAnimations;
+
+/**
+ * 弹出层内部组件注入属性，在弹出层内部渲染的所有子代组件中，都可以通过 inject 注入弹出层所提供的相关参数
+ */
+export declare const POPUP_COMPONENT_INJECTS: Readonly<ComponentInjectKeys>;
+
+export declare interface PopupCustomAnimations {
+}
+
+export declare interface PopupCustomProperties {
+}
+
+declare type PopupViewStyle = ComputedRef<{
+    width: number;
+    height: number;
+    zIndex: number;
+    translateX: number;
+    translateY: number;
+}>;
+
 declare type RenderComponentOptions = {
     /**
      * 弹出层渲染的组件，想要创建一个弹出层，这个唯一必要的参数。它的值可以是一个同步组件，也可以是一个异步组件的 import() 函数。
@@ -184,7 +341,7 @@ declare type RenderComponentOptions = {
     /**
      * 弹出层关闭之后的回调，触发时会将destroy() 方法的负载参数 payload 作为参数传入
      */
-    onUnmounted?: <T>(payload?: T) => void;
+    onUnmounted?: (payload?: any) => void;
 };
 
 declare type RenderElement = HTMLElement | string;
@@ -325,18 +482,30 @@ declare type RenderStyleOptions = {
      * minHeight: 300,
      */
     minHeight?: string | number;
+    /**
+     * 弹出层视图水平偏移量，默认为 0 ，单位为 px
+     */
+    viewTranslateX?: number;
+    /**
+     * 弹出层视图垂直偏移量，默认为 0 ，单位为 px
+     */
+    viewTranslateY?: number;
+    /**
+     * 弹出层视图是否允许超出窗口边界，默认为 false
+     */
+    viewTranslateOverflow?: boolean;
     /**
      * 弹出层动画时长，默认为 100 ，单位为 毫秒
      */
     animationDuration?: number;
     /**
-     * 遮罩层动画类型，默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看 {@link PopupAnimationCollection}
+     * 遮罩层动画类型，默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看 {@link IAnimations}
      */
-    maskAnimation?: symbol;
+    maskAnimation?: Animation_2;
     /**
-     * 视图层动画类型，默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看 {@link PopupAnimationCollection}
+     * 视图层动画类型，默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看 {@link IAnimations}
      */
-    viewAnimation?: symbol;
+    viewAnimation?: Animation_2;
     /**
      * 弹出层 zIndex ，若不设置，则使用全局递增的 zIndex 值
      */
@@ -349,7 +518,7 @@ declare type UpdateOptions = Partial<Omit<RenderOptions, 'component' | 'el' | 'a
  * 获取弹出层控制器实例
  * @returns 弹出层控制器实例
  */
-export declare function usePopup(): PopupController;
+export declare function usePopup(): IController;
 
 export { version }
 
@@ -358,6 +527,6 @@ export { }
 
 declare module 'vue' {
     interface ComponentCustomProperties {
-        $popup: PopupController;
+        $popup: IController;
     }
 }