vue-popup-plus 1.3.4 → 1.5.0

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];
 
@@ -12,18 +18,25 @@ declare type Animation_2 = IAnimations[keyof IAnimations];
 declare type ComponentInjectKeys = {
     /**
      * 当前组件所在弹出层的实例ID
+     *
      * - 可用于销毁当前弹出层
      * - 使用示例：
+     *
      * ```ts
      * // 弹出层渲染的所有子代组件中
      * import { inject } from 'vue'
-     * import { usePopup, POPUP_COMPONENT_INJECTS } from 'vue-popup-plus'
+     * import {
+     * 	usePopup,
+     * 	POPUP_COMPONENT_INJECTS,
+     * } from 'vue-popup-plus'
      *
      * // 获取弹出层控制器
      * const popup = usePopup()
      *
      * // 获取当前组件所在弹出层的实例ID
-     * const instanceId = inject(POPUP_COMPONENT_INJECTS.INSTANCE_ID)
+     * const instanceId = inject(
+     * 	POPUP_COMPONENT_INJECTS.INSTANCE_ID
+     * )
      *
      * // 销毁当前弹出层
      * popup.destroy(instanceId)
@@ -32,21 +45,30 @@ declare type ComponentInjectKeys = {
     INSTANCE_ID: InjectionKey<InstanceId>;
     /**
      * 弹出层视图样式
+     *
      * - 可在弹出层内部组件内获取弹出层根级视图组件的样式
      * - 使用示例：
+     *
      * ```ts
      * // 弹出层渲染的所有子代组件中
      * import { inject } from 'vue'
-     * import { usePopup, POPUP_COMPONENT_INJECTS } from 'vue-popup-plus'
+     * import {
+     * 	usePopup,
+     * 	POPUP_COMPONENT_INJECTS,
+     * } from 'vue-popup-plus'
      *
      * // 获取弹出层控制器
      * const popup = usePopup()
      *
      * // 获取当前组件所在弹出层的实例ID
-     * const instanceId = inject(POPUP_COMPONENT_INJECTS.INSTANCE_ID)
+     * const instanceId = inject(
+     * 	POPUP_COMPONENT_INJECTS.INSTANCE_ID
+     * )
      *
      * // 获取弹出层根级视图组件的样式
-     * const computedViewStyle = inject(POPUP_COMPONENT_INJECTS.COMPUTED_VIEW_STYLE)
+     * const computedViewStyle = inject(
+     * 	POPUP_COMPONENT_INJECTS.COMPUTED_VIEW_STYLE
+     * )
      * ```
      */
     COMPUTED_VIEW_STYLE: InjectionKey<PopupViewStyle>;
@@ -62,30 +84,36 @@ declare type ControllerPrototype = Record<string, string | boolean | number | sy
 
 declare type ControllerPrototypeFunctionValue = (this: IController, ...args: any[]) => any;
 
-declare type CoreConfig = Required<CoreOptions>;
+declare type CoreConfig = Required<CreateOption>;
 
-export declare type CoreOptions = {
+export declare type CreateOption = {
     /**
      * 弹出层 zIndex 基础值
-     * - 默认为1000，每次生成弹出层时，除非 render() 方法传入 zIndex，否则使用此基础值，每次使用后会自动递增
+     *
+     * - 默认为1000，每次生成弹出层时，除非 render() 方法传入
+     *   zIndex，否则使用此基础值，每次使用后会自动递增
      */
     zIndex?: number;
     /**
      * 是否自动禁用滚动
+     *
      * - 默认为 true
      * - 开启后，弹出层显示时会自动禁用页面滚动
      */
     autoDisableScroll?: boolean;
     /**
      * 弹出层控制器挂载在 Vue 实例上的属性名
-     * - 默认为 $popup ，这在使用选项式API时可以在组件内通过this.$popup 访问控制器实例，可以使用该属性自定义挂载属性名
+     *
+     * - 默认为 $popup ，这在使用 选项式 API 时可以在组件内通过 this.$popup
+     *   访问控制器实例，可以使用该属性自定义挂载属性名
      * - 使用示例：
+     *
      * ```ts
      * // main.ts
      * import { createPopup } from 'vue-popup-plus'
      *
      * const popup = createPopup({
-     * 	prototypeName: '$customPopup'
+     * 	prototypeName: '$customPopup',
      * })
      *
      * // 组件内
@@ -93,8 +121,11 @@ export declare type CoreOptions = {
      * 	component: Demo,
      * })
      * ```
-     * - 注意，如果你使用 TypeScript，则自定义属性名称需要手动同步添加类型扩展，扩展代码可以放在一个 .ts 文件，或是一个影响整个项目的 *.d.ts 文件中。
+     *
+     * - 注意，如果你使用 TypeScript，则自定义属性名称需要手动同步添加类型扩展，扩展代码可以放在一个
+     *   .ts 文件，或是一个影响整个项目的 *.d.ts 文件中。
      * - 扩展代码示例：
+     *
      * ```ts
      * // 扩展自定义属性名类型
      * declare module 'vue' {
@@ -102,25 +133,71 @@ export declare type CoreOptions = {
      * 		$customPopup: typeof popup
      * 	}
      * }
+     * ```
      */
     prototypeName?: string;
+    /**
+     * 日志器
+     *
+     * - 默认使用内置的日志器，仅会在开启调试模式时在控制台输出日志
+     * - 你可以自定义日志器，需要注意日志的接收将不会受到调试模式的影响，
+     *   无论调试模式是否开启，日志都将被传递给自定义的日志器。
+     */
+    logHandler?: ILogHandler;
     /**
      * 开启调试模式
+     *
      * - 默认为 false
-     * - 开启后，会提供开发调试功能
+     * - 注意：开启调试模式可能会影响到性能，不建议在生产环境开启。
+     * - 开启后，将会在控制台输出日志，同时如果未注册根组件，调试模式下
+     *   将会使用 Vue App 实例渲染弹出层，方便开发者调试。
      */
     debugMode?: boolean;
 };
 
 /**
- * 创建一个弹出层控制器实例，该实例需要通过 app.use() 安装到Vue实例上才能使用
- * @param options 弹出层核心配置
+ * 创建一个弹出层控制器实例
+ *
+ * - 该实例需要被 Vue 的 app.use() 函数后才能使用
+ *
+ * @param options 创建配置，具体请参考 {@link CreateOption}
  * @returns 弹出层控制器实例
  */
-export declare function createPopup(options?: CoreOptions): IController;
+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 {
     /**
      * 无动画
@@ -137,7 +214,7 @@ declare interface IAnimations extends PopupCustomAnimations {
     /**
      * 缩放缩小
      */
-    readonly SCALE_SHRINK: 'scale-shrink';
+    readonly SCALE_REDUCE: 'scale-reduce';
     /**
      * 顶部飞入
      */
@@ -157,35 +234,48 @@ declare interface IAnimations extends PopupCustomAnimations {
 }
 
 declare interface IController extends PopupCustomProperties {
+    /**
+     * 版本号
+     */
+    readonly version: Version;
     /**
      * 安装插件
+     *
      * @param {App} app - Vue应用实例
-     * @returns {void}
+     * @returns {any}
      */
-    install(app: App): void;
+    install(app: App): any;
     /**
-     * 安装插件
-     * - 可安装使用 `definePlugin` 方法定义的插件
+     * 注册插件
+     *
+     * - 可注册使用 `definePlugin()` 方法定义的插件
+     * - 重复注册相同的插件，会被忽略
      * - 具体请参考{@link IDefinePlugin}
      */
-    use(plugin: PopupPlugin): void;
+    use<TOption extends PluginOption, TPlugin extends PopupPlugin<TOption>>(plugin: TPlugin, options?: ExtractPluginOption<TPlugin>): void;
     /**
-     * 渲染弹出层，返回弹出层实例id，可调用destroy(id)方法销毁弹出层
-     * @param {RenderOptions} options - 渲染参数
-     * @returns 弹出层实例id
+     * 渲染弹出层
+     *
+     * - 渲染参数 `component`
+     *   是唯一的必填项，其他渲染参数具体请参考{@link RenderOption}
+     * - 返回值是弹出层的实例 id ，用于调用 destroy() 方法销毁弹出层
      */
-    render(options: RenderOptions): InstanceId;
+    render<TComponent extends Component = Component>(options: RenderOption<TComponent>): InstanceId;
     /**
-     * 更新弹出层，可更新弹出层参数
-     * @param {InstanceId} instanceId - 弹出层实例id
-     * @param {UpdateOptions} options - 更新参数
+     * 更新弹出层
+     *
+     * - 主要用于更新弹出层的渲染参数
+     * - 第一个参数需要传入需要更新的弹出层的实例 id
+     * - 第二个参数需要传入更新的参数，仅支持部分渲染参数，具体请参考{@link UpdateOption}
      */
-    update(instanceId: InstanceId, options: UpdateOptions): void;
+    update(instanceId: InstanceId, options: UpdateOption): void;
     /**
      * 销毁弹出层
-     * @param {InstanceId} instanceId - 弹出层实例id
-     * @param {any} payload - 自定义负载参数，会作为参数传递给创建弹出层时的onUnmounted回调函数
-     * @returns {Promise<void>}
+     *
+     * - 传入弹出层的实例 id ，用于销毁指定的弹出层
+     * - 第二个参数是自定义负载参数，会作为参数传递给创建弹出层时的 onUnmounted 回调函数
+     * - 该函数返回一个 Promise 对象，用于等待弹出层关闭动画完成
+     * - 如果弹出层不存在，会在调试模式下打印警告日志
      */
     destroy(instanceId: InstanceId, payload?: any): void;
 }
@@ -193,17 +283,35 @@ declare interface IController extends PopupCustomProperties {
 declare interface IDefinePlugin {
     /**
      * 定义插件
-     * - 插件是一个对象，包含插件名称和安装方法
-     * - 安装方法接收一个可扩展自定义属性的控制器实例作为参数，用于扩展弹出层插件的原型属性
+     *
+     * - 该方法用于定义一个可以直接被 `popup.use` 方法注册的插件
+     * - 插件的名称 `name` 必须唯一
+     * - 插件的作者 `author` 可以是个人或组织名称
+     * - 插件的核心版本要求 `coreVersion` 可以指定插件所适配的最低和最高核心版本，
+     * 不符合要求的核心将无法注册该插件
+     * - 插件的安装函数 `install` 必须是一个函数，接收三个参数：
+     *   - 第一个参数接收注册此插件的弹出层控制器实例
+     *   - 第二个参数接收注册此插件的弹出层的创建配置
+     *   - 第三个参数接收插件自定义选项，可自行定义，插件使用者可在调用
+     *  `popup.use` 方法时传入
      * - 使用示例：
+     *
      * ```ts
      * import { createPopup, definePlugin } from 'vue-popup-plus'
      * const popup = createPopup()
+     *
+     * type TestPluginOption = {
+     * 	logEnable?: boolean
+     * }
+     *
      * const plugin = definePlugin({
-     * 	// 插件名称，必须唯一
      * 	name: 'test',
-     * 	// 插件安装时的回调函数，会将控制器实例作为参数传入
-     * 	install(popup) {
+     * 	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({
      * 				component: () => import('path/Demo.vue'),
@@ -211,12 +319,16 @@ declare interface IDefinePlugin {
      * 					message,
      * 				},
      * 			})
+     *
+     * 			if (logEnable) {
+     * 				console.log(message)
+     * 			}
      * 		}
      * 	},
      * })
      * ```
      */
-    (options: PopupPlugin): PopupPlugin;
+    <TOption extends PluginOption>(options: PopupPlugin<TOption>): PopupPlugin<TOption>;
 }
 
 /**
@@ -230,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);
@@ -239,10 +388,12 @@ export declare class InstanceId implements IInstanceId {
 
 declare interface IPluginWrappedController extends IController {
     /**
-     * 原型属性
+     * 控制器实例自定义属性原型对象
+     *
      * - 可在插件的 `install` 方法中扩展方法或属性
      * - 该属性为只读属性，只允许扩展，并且内置方法不能被覆盖
      * - 使用示例：
+     *
      * ```ts
      * // 插件中扩展方法
      * import { definePlugin } from 'vue-popup-plus'
@@ -267,10 +418,12 @@ declare interface IPluginWrappedController extends IController {
      */
     readonly customProperties: ControllerPrototype;
     /**
-     * 自定义动画类型
+     * 动画类型自定义属性原型对象
+     *
      * - 可在插件的 `install` 方法中扩展动画类型
      * - 该属性为只读属性，只允许扩展，并且内置动画类型不能被覆盖
      * - 使用示例：
+     *
      * ```ts
      * // 插件中扩展动画类型
      * import { definePlugin } from 'vue-popup-plus'
@@ -278,7 +431,7 @@ declare interface IPluginWrappedController extends IController {
      * const plugin = definePlugin({
      * 	name: 'test',
      * 	install(popup) {
-     * 		popup.customAnimations.CUSTOM = 'CUSTOM'
+     * 		popup.customAnimations.CUSTOM = 'custom'
      * 	},
      * })
      * ```
@@ -286,12 +439,135 @@ declare interface IPluginWrappedController extends IController {
     readonly customAnimations: PopupCustomAnimations;
 }
 
-declare type PluginInstall = (controller: IPluginWrappedController, config: Readonly<CoreConfig>) => void;
+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>;
 
 export declare const POPUP_ANIMATIONS: IAnimations;
 
 /**
- * 弹出层内部组件注入属性，在弹出层内部渲染的所有子代组件中，都可以通过 inject 注入弹出层所提供的相关参数
+ * 弹出层内部组件注入属性
+ *
+ * - 在弹出层内部渲染的所有子代组件中，都可以通过 inject 注入弹出层所提供的相关参数
  */
 export declare const POPUP_COMPONENT_INJECTS: Readonly<ComponentInjectKeys>;
 
@@ -301,11 +577,76 @@ export declare interface PopupCustomAnimations {
 export declare interface PopupCustomProperties {
 }
 
-export declare type PopupPlugin = {
+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;
-    install: PluginInstall;
+    /**
+     * 插件安装函数
+     *
+     * - 第一个参数接收注册此插件的弹出层控制器实例
+     * - 第二个参数接收注册此插件的弹出层的创建配置
+     * - 第三个参数接收插件自定义选项，可自行定义，插件使用者可在调用
+     *  `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;
@@ -314,26 +655,46 @@ declare type PopupViewStyle = ComputedRef<{
     translateY: number;
 }>;
 
-declare type RenderComponentOptions = {
+/**
+ * 打印日志
+ *
+ * - 仅在开启调试模式时打印输出日志
+ * @param log 日志实例
+ * @returns
+ */
+export declare const printLog: ILogHandler;
+
+declare type RenderComponentOptions<TComponent extends Component = Component> = {
     /**
-     * 弹出层渲染的组件，想要创建一个弹出层，这个唯一必要的参数。它的值可以是一个同步组件，也可以是一个异步组件的 import() 函数。
-     * @example
-     * // 同步组件
-     * import Demo from 'path/Demo.vue'
-     * popup.render({
-     * 	component: Demo,
-     * })
+     * 弹出层渲染的组件
      *
+     * - 要创建一个弹出层，这是唯一必要的参数。
+     * - 支持同步组件和异步组件，为了提高加载速度，优化构建体积，建议使用异步组件。
+     * - 对于异步组件，无需使用 `defineAsyncComponent` 方法定义组件，直接传入
+     *   ()=>import() 函数即可。
+     * - 使用示例：
+     *
+     * ```ts
      * // 异步组件
      * popup.render({
      * 	component: () => import('path/Demo.vue'),
      * })
+     *
+     * // 同步组件
+     * import Demo from 'path/Demo.vue'
+     * popup.render({
+     * 	component: Demo,
+     * })
+     * ```
      */
-    component: Component;
+    component: TComponent;
     /**
      * 弹出层渲染组件的 props ，会传递给弹出层组件
+     * - 会自动根据传入的组件进行类型推导，提供完善的类型提示
+     * - 除了组件的属性，还支持传入组件的事件监听器，事件监听器的名称需要以 `on` 开头，
+     *   例如 `onClick` 、 `onInput` 等。
      */
-    componentProps?: Record<string, any>;
+    componentProps?: ExtractComponentPropTypes<TComponent>;
     /**
      * 弹出层渲染之后的回调
      */
@@ -346,183 +707,250 @@ declare type RenderComponentOptions = {
 
 declare type RenderConfigOptions = {
     /**
-     * 弹出层挂载的父元素，不指定时，默认挂载到 body 元素下
+     * 弹出层挂载的父元素
+     *
+     * - 不指定时，默认挂载到 body 元素下
      */
     appendTo?: Element | string;
     /**
-     * 弹出层是否显示遮罩层，默认值为 true
+     * 弹出层是否显示遮罩层
+     *
+     * - 默认值为 true
      */
     mask?: boolean;
     /**
-     * 点击遮罩层是否关闭弹出层，默认值为 false ，仅在 mask 为 true 时有效
+     * 点击遮罩层是否关闭弹出层
+     *
+     * - 默认值为 false ，仅在 mask 为 true 时有效
      */
     maskClickClose?: boolean;
     /**
-     * 弹出层是否禁用窗口滚动，默认值为 true
+     * 弹出层是否禁用窗口滚动
+     *
+     * - 默认值为 true
      */
     disableScroll?: boolean;
 };
 
-export declare type RenderOptions = RenderConfigOptions & RenderComponentOptions & RenderStyleOptions;
+export declare type RenderOption<TComponent extends Component = Component> = RenderComponentOptions<TComponent> & RenderConfigOptions & RenderStyleOptions;
 
 declare type RenderStyleOptions = {
     /**
-     * 弹出层宽度，默认为 auto，即自适应，支持 string 和 number 类型，string 类型更为灵活，number 类型方便计算
+     * 弹出层宽度
+     *
+     * - 默认为 auto，即自适应，支持 string 和 number 类型，string
+     *   类型更为灵活，number 类型方便计算
+     *
      * @example
-     * // px
-     * width: '300px',
-     * // rem
-     * width: '30rem',
-     * // vw
-     * width: '30vw',
-     * // 百分比
-     * width: '30%',
-     * // css 动态计算
-     * width: 'calc(50% + 20px)',
-     * // css 变量
-     * width: 'var(--width)',
-     * // number 类型，方便计算，单位为 px
-     * width: 300,
+     * 	// px
+     * 	width: '300px',
+     * 	// rem
+     * 	width: '30rem',
+     * 	// vw
+     * 	width: '30vw',
+     * 	// 百分比
+     * 	width: '30%',
+     * 	// css 动态计算
+     * 	width: 'calc(50% + 20px)',
+     * 	// css 变量
+     * 	width: 'var(--width)',
+     * 	// number 类型，方便计算，单位为 px
+     * 	width: 300,
      */
     width?: string | number;
     /**
-     * 弹出层最大宽度，默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number 类型方便计算
+     * 弹出层最大宽度
+     *
+     * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
+     *   类型方便计算
+     *
      * @example
-     * // px
-     * maxWidth: '300px',
-     * // rem
-     * maxWidth: '30rem',
-     * // vw
-     * maxWidth: '30vw',
-     * // 百分比
-     * maxWidth: '30%',
-     * // css 动态计算
-     * maxWidth: 'calc(50% + 20px)',
-     * // css 变量
-     * maxWidth: 'var(--width)',
-     * // number 类型，方便计算，单位为 px
-     * maxWidth: 300,
+     * 	// px
+     * 	maxWidth: '300px',
+     * 	// rem
+     * 	maxWidth: '30rem',
+     * 	// vw
+     * 	maxWidth: '30vw',
+     * 	// 百分比
+     * 	maxWidth: '30%',
+     * 	// css 动态计算
+     * 	maxWidth: 'calc(50% + 20px)',
+     * 	// css 变量
+     * 	maxWidth: 'var(--width)',
+     * 	// number 类型，方便计算，单位为 px
+     * 	maxWidth: 300,
      */
     maxWidth?: string | number;
     /**
-     * 弹出层最小宽度，默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number 类型方便计算
+     * 弹出层最小宽度
+     *
+     * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
+     *   类型方便计算
+     *
      * @example
-     * // px
-     * minWidth: '300px',
-     * // rem
-     * minWidth: '30rem',
-     * // vw
-     * minWidth: '30vw',
-     * // 百分比
-     * minWidth: '30%',
-     * // css 动态计算
-     * minWidth: 'calc(50% + 20px)',
-     * // css 变量
-     * minWidth: 'var(--width)',
-     * // number 类型，方便计算，单位为 px
-     * minWidth: 300,
+     * 	// px
+     * 	minWidth: '300px',
+     * 	// rem
+     * 	minWidth: '30rem',
+     * 	// vw
+     * 	minWidth: '30vw',
+     * 	// 百分比
+     * 	minWidth: '30%',
+     * 	// css 动态计算
+     * 	minWidth: 'calc(50% + 20px)',
+     * 	// css 变量
+     * 	minWidth: 'var(--width)',
+     * 	// number 类型，方便计算，单位为 px
+     * 	minWidth: 300,
      */
     minWidth?: string | number;
     /**
-     * 弹出层高度，默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number 类型方便计算
+     * 弹出层高度
+     *
+     * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
+     *   类型方便计算
+     *
      * @example
-     * // px
-     * height: '300px',
-     * // rem
-     * height: '30rem',
-     * // vh
-     * height: '30vh',
-     * // 百分比
-     * height: '30%',
-     * // css 动态计算
-     * height: 'calc(50% + 20px)',
-     * // css 变量
-     * height: 'var(--height)',
-     * // number 类型，方便计算，单位为 px
-     * height: 300,
+     * 	// px
+     * 	height: '300px',
+     * 	// rem
+     * 	height: '30rem',
+     * 	// vh
+     * 	height: '30vh',
+     * 	// 百分比
+     * 	height: '30%',
+     * 	// css 动态计算
+     * 	height: 'calc(50% + 20px)',
+     * 	// css 变量
+     * 	height: 'var(--height)',
+     * 	// number 类型，方便计算，单位为 px
+     * 	height: 300,
      */
     height?: string | number;
     /**
-     * 弹出层最大高度，默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number 类型方便计算
+     * 弹出层最大高度
+     *
+     * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
+     *   类型方便计算
+     *
      * @example
-     * // px
-     * maxHeight: '300px',
-     * // rem
-     * maxHeight: '30rem',
-     * // vh
-     * maxHeight: '30vh',
-     * // 百分比
-     * maxHeight: '30%',
-     * // css 动态计算
-     * maxHeight: 'calc(50% + 20px)',
-     * // css 变量
-     * maxHeight: 'var(--height)',
-     * // number 类型，方便计算，单位为 px
-     * maxHeight: 300,
+     * 	// px
+     * 	maxHeight: '300px',
+     * 	// rem
+     * 	maxHeight: '30rem',
+     * 	// vh
+     * 	maxHeight: '30vh',
+     * 	// 百分比
+     * 	maxHeight: '30%',
+     * 	// css 动态计算
+     * 	maxHeight: 'calc(50% + 20px)',
+     * 	// css 变量
+     * 	maxHeight: 'var(--height)',
+     * 	// number 类型，方便计算，单位为 px
+     * 	maxHeight: 300,
      */
     maxHeight?: string | number;
     /**
-     * 弹出层最小高度，默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number 类型方便计算
+     * 弹出层最小高度
+     *
+     * - 默认为 auto，支持 string 和 number 类型，string 类型更为灵活，number
+     *   类型方便计算
+     *
      * @example
-     * // px
-     * minHeight: '300px',
-     * // rem
-     * minHeight: '30rem',
-     * // vh
-     * minHeight: '30vh',
-     * // 百分比
-     * minHeight: '30%',
-     * // css 动态计算
-     * minHeight: 'calc(50% + 20px)',
-     * // css 变量
-     * minHeight: 'var(--height)',
-     * // number 类型，方便计算，单位为 px
-     * minHeight: 300,
+     * 	// px
+     * 	minHeight: '300px',
+     * 	// rem
+     * 	minHeight: '30rem',
+     * 	// vh
+     * 	minHeight: '30vh',
+     * 	// 百分比
+     * 	minHeight: '30%',
+     * 	// css 动态计算
+     * 	minHeight: 'calc(50% + 20px)',
+     * 	// css 变量
+     * 	minHeight: 'var(--height)',
+     * 	// number 类型，方便计算，单位为 px
+     * 	minHeight: 300,
      */
     minHeight?: string | number;
     /**
-     * 弹出层视图动画类型，默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看 {@link IAnimations}
+     * 弹出层位置
+     *
+     * - 默认为 center ，即居中显示
+     * - 更多位置请查看 {@link Placement}
+     * @since 1.5.0
+     */
+    placement?: Placement;
+    /**
+     * 弹出层视图动画类型
+     *
+     * - 默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看
+     *   {@link IAnimations}
      */
     viewAnimation?: Animation_2;
     /**
-     * 弹出层视图水平偏移量，默认为 0 ，单位为 px
+     * 弹出层视图水平偏移量
+     *
+     * - 默认为 0 ，单位为 px
      */
     viewTranslateX?: number;
     /**
-     * 弹出层视图垂直偏移量，默认为 0 ，单位为 px
+     * 弹出层视图垂直偏移量
+     *
+     * - 默认为 0 ，单位为 px
      */
     viewTranslateY?: number;
     /**
-     * 弹出层视图是否允许超出窗口边界，默认为 false
+     * 弹出层视图是否允许超出窗口边界
+     *
+     * - 默认为 false
      */
     viewTranslateOverflow?: boolean;
     /**
-     * 弹出层遮罩动画类型，默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看 {@link IAnimations}
+     * 弹出层遮罩动画类型
+     *
+     * - 默认为 POPUP_ANIMATIONS.FADE ，即淡入淡出，更多动画类型请查看
+     *   {@link IAnimations}
      */
     maskAnimation?: Animation_2;
     /**
-     * 弹出层遮罩是否启用模糊效果，默认为 true
+     * 弹出层遮罩是否启用模糊效果
+     *
+     * - 默认为 true
+     * @since 1.3.0
      */
     maskBlur?: boolean;
     /**
-     * 弹出层动画时长，默认为 100 ，单位为 毫秒
+     * 弹出层动画时长
+     *
+     * - 默认为 100 ，单位为 毫秒
      */
     animationDuration?: number;
     /**
-     * 弹出层 zIndex ，若不设置，则使用全局递增的 zIndex 值
+     * 弹出层 zIndex
+     *
+     * - 若不设置，则使用全局递增的 zIndex 值
      */
     zIndex?: number;
 };
 
-export declare type UpdateOptions = Partial<RenderStyleOptions>;
+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 { }