snail.vue 1.0.29 → 1.0.31

package/dist/snail.vue.d.ts

@@ -1,8 +1,8 @@
 import * as snail_view from 'snail.view';
 import { BaseStyle, WidthStyle, FlexBoxStyle, HeightStyle, BorderStyle, PaddingStyle } from 'snail.view';
 import * as vue from 'vue';
-import { Component, App, ShallowRef } from 'vue';
-import { IScope } from 'snail.core';
+import { Component, ShallowRef, Ref, App } from 'vue';
+import { IScope, IAsyncScope } from 'snail.core';
 
 /**
  * loading提示框的配置选项
@@ -461,7 +461,7 @@ type ButtonOptions = {
  */
 interface IReactiveManager {
     /**
-     * 【过渡】响应式变量值
+     * 【过渡】变量值
      * - 通过设置 rv.value 的值来实现.value值过渡
      * - 执行顺序 from、to
      * - 开始时，设置 rv.value 值为 from；延迟time时间后，强制销毁scope
@@ -471,20 +471,28 @@ interface IReactiveManager {
      * @param time 过渡持续时间，到时间后销毁作用域
      * @returns 作用域对象，可销毁【值过渡】效果
      */
-    transition<T>(rv: {
-        value?: T;
-    }, effect: {
+    transition<T>(rv: ShallowRef<T> | Ref<T>, effect: {
         from: T;
         to: T;
     }, time: number): IScope;
+    /**
+     * 【任务】响应式
+     * - 任务运行时，设置loading.value=true
+     * - 任务完成后，设置loading.value=false
+     * - 可通过delay值，延迟执行 loading.value=false 操作
+     * - 可在api请求等耗时操作任务过程中，实现响应式显隐Loading组件
+     * @param task 要运行的任务
+     * @param loading 正在加载的响应式变量
+     * @param delay 延迟时间，单位ms；不传则不延迟
+     * @returns 任务自身
+     */
+    task<T, E>(task: Promise<T>, loading: ShallowRef<boolean> | Ref<boolean>, delay: number): Promise<{
+        success: boolean;
+        data?: T;
+        error?: E;
+    }>;
 }
 
-/**
- * 响应式 模块；
- *  1、针对Vue的响应式相关功能，做一些便捷封装
- *  2、方便使用，减少重复性代码量
- */
-
 /**
  * 使用【响应式管理器】
  * - 请在Vue组件的setup中使用此方法，否则 getCurrentScope 方法无法取到值
@@ -522,9 +530,26 @@ declare function triggerAppCreated(app: App): App;
 declare function getSvgIcon(options: IconOptions): IconPathOptions;
 
 /**
- * 模态弹窗显示的组件配置选项
+ * 挂载vue组件
+ * - 全新创建一个Vue实例挂载的传入组件
+ * - 用于在非vue环境下渲染vue组件内容
+ * @param options 挂载配置选项
+ * @param onDestroyed  监听【调用方】的销毁时机，用于自动销毁挂载的实力
+ * @returns
+ */
+declare function mount(options: ComponentMountOptions, onDestroyed?: (fn: () => void) => void): IScope;
+
+/**
+ * 公共通用数据结构：
+ *  1、在弹窗、模态弹窗、跟随弹窗的效果下复用
+ */
+
+/**
+ * 弹窗配置选项
+ * - 约束弹出组件信息
+ * - 弹出组件时传递的参数信息
  */
-type DialogOptions = ComponentOptions & {
+type PopupOptions = ComponentOptions & {
     /**
      * 传递给组件的属性值，执行v-bind绑定到要显示的组件
      * - key为属性名称，遵循vue解析规则
@@ -533,29 +558,101 @@ type DialogOptions = ComponentOptions & {
     props?: Record<string, any>;
     /**
      * 自定义class
-     * - 绑定模块弹窗显示的组件根元素上
-     */
+     * - 绑定到内容组件根元素上
+     * - 可以直接在props中指定，无需特殊设置
     class?: string | string[];
+     */
     /**
      * 自定义style
-     * - 绑定模块弹窗显示的组件根元素上
+     * - 绑定到内容组件根元素上
+     * - 可以直接在props中指定，无需特殊设置
+    style?: AllStyle;
      */
-    style?: string | string[];
     /**
-     * 按下esc健时是否关闭弹窗
-     * - 默认值：false
+     * 弹窗的z-index值
+     * - 无特殊情况，建议不指定，内部会自动生成，确保弹窗正确性
      */
-    closeOnEscape?: boolean;
+    zIndex?: number;
+};
+/**
+ * 弹窗标识信息
+ */
+type PopupFlagOptions = {
     /**
-     * 点击遮罩层时是否关闭弹窗
-     * - 默认值：false
+     * 分配给弹窗的Id值
+     */
+    id: number;
+    /**
+     * 实际分配的zIndex值
+     */
+    zIndex: number;
+};
+/**
+ * 弹出组件句柄
+ */
+type PopupHandle<T> = {
+    /**
+     * 组件是否在【弹出窗口】中
+     */
+    inPopup: Readonly<boolean>;
+    /**
+     * 关闭弹窗
+     * @param data 关闭时传递数据
+     */
+    closePopup(data?: T): void;
+};
+/**
+ * 弹窗状态：响应式
+ * - open       打开
+ * - active     激活
+ * - unactive   非激活
+ * - close      关闭
+ */
+type PopupStatus = ShallowRef<"open" | "active" | "unactive" | "close">;
+/**
+ * 弹窗扩展信息
+ */
+type PopupExtend = {
+    /**
+     * 弹窗状态
+     */
+    popupStatus: PopupStatus;
+};
+
+/**
+ * 模态弹窗数据结构
+ */
+
+/**
+ * 模态弹窗配置选项
+ * - 继承 ComponentOptions ，动态加载组件
+ */
+type DialogOptions = PopupOptions & {
+    /**
+     * 禁用【遮罩层】
+     * - 目前没实现，先忽略
+    maskDisabled?: boolean;
+     */
+    /**
+     * 点击【遮罩层】时是否关闭弹窗
+     * - 针对无遮罩层的弹窗，则点击非【弹窗组件】区域时是否关闭
      */
     closeOnMask?: boolean;
     /**
-     * 弹窗的z-index值
-     * - 无特殊情况，建议不粗韩，内部会自动生成，确保弹窗正确性
+     * 按下【ESC】健时是否关闭弹窗
      */
-    zIndex?: number;
+    closeOnEscape?: boolean;
+    /**
+     * 模态弹窗动画名
+     * - 不传则使用默认，具体有弹窗容器确认，如dialog为 snail-dialog
+     */
+    transition?: string;
+    /**
+     * 动画持续时间
+     * - 配合 transition 使用；单位ms，默认100ms
+     * - 外部传入自定义动画时，传入动画持续时间，否则可能导致关闭时动画失效
+     */
+    transitionDuration?: number;
     /**
      * 模态弹窗的自定义class
      * - 绑定到模态弹窗的根元素上
@@ -563,73 +660,36 @@ type DialogOptions = ComponentOptions & {
     rootClass?: string | string[];
 };
 /**
- * 模块弹窗打开后的结果
- * - 执行destroy方法时，强制关闭，不会执行onDialogClose
- */
-type DialogOpenResult<T> = Promise<T> & IScope;
-/**
- * 弹窗句柄：绑定给子组件使用
+ * 弹窗组件句柄
+ * - 用于在弹窗内容组件中进行模式判断和关闭
  */
 type DialogHandle<T> = {
-    /**  组件是否处于【弹窗】模式下 */
-    inDialog: boolean;
     /**
-     * 关闭弹窗的方法
+     * 组件是否处于【模态弹窗】模式
+     */
+    inDialog: Readonly<boolean>;
+    /**
+     * 关闭弹窗
      * @param data 关闭时传递数据
      */
     closeDialog(data?: T): void;
     /**
-     * 注册监听【弹窗关闭的方法】
+     * 注册监听【弹窗关闭】事件方法
      * - 仅支持注册一次，多次注册以最后一次的为准
      * @param fn 关闭时执行的钩子函数，支持异步，返回false时将阻止弹窗关闭
      */
     onDialogClose(fn: () => false | undefined | Promise<false | undefined>): void;
 };
 /**
- * 模态弹窗；配合【../components/dialog-wrapper.vue】使用
+ * 弹窗扩展信息
  */
-type Dialog = {
+type DailogExtend = {
     /**
-     * 弹窗Id，唯一值
+     * 弹窗状态
      */
-    id: string;
-    /**
-     * 模态弹窗显示的组件配置选项
-     */
-    options: DialogOptions;
-    /**
-     * 弹窗句柄
-     * - 提供关闭弹窗等操作
-     * - 将挂载到内容组件的属性上，方便使用
-     */
-    handle: DialogHandle<any>;
+    dialogStatus: PopupStatus;
 };
 
-/**
- * 模态弹窗助手；提供模态弹窗相关功能
- *      1、内部维护一个VueApp实例，专门用于进行模态弹窗操
- *      2、模态弹窗展示效果，通过 @see ../componets/dialog-wrapper.vue 实现
- */
-
-/**
- * 打开模态弹窗
- * @param options 弹窗组件配置选项
- * @param onDestroyed 监听【调用方】的销毁时机，用于自动销毁打开的弹窗
- * @returns 弹窗打开结果，可手动关闭弹窗
- */
-declare function openDialog<T>(options: DialogOptions, onDestroyed?: (fn: () => void) => void): DialogOpenResult<T>;
-/**
- * 作用域弹窗：方法执行逻辑：
- * - 1、打开弹窗前：若scopeRef有值，则强制执行 scopeRef.value.destroy() 做销毁
- * - 2、打开弹窗 ：构建IScope赋值给 scopeRef.value ；外部可 scopeRef.value.destroy() 强制关闭弹窗
- * - 3、等待弹窗关闭 ：得到弹窗返回值，置空scopeRef值，并返回弹窗返回值：scopeRef.value = undefined
- * - 备注说明：封装重复性代码，简化外部开发逻辑；无实际业务意义
- * @param options 弹窗配置选项
- * @param scopeRef 作用域响应式对象
- * @returns 弹窗关闭时传递的数据
- */
-declare function scopeDialog<T>(options: DialogOptions, scopeRef: ShallowRef<IScope | undefined>): Promise<T>;
-
 /**
  * 确认弹窗配置选项
  */
@@ -666,16 +726,6 @@ type ConfirmOptions = {
      */
     confirmDisabled?: boolean;
 };
-/**
- * 确认弹窗句柄
- */
-type ConfirmHandle = {
-    /**
-     * 关闭弹窗
-     * @param confirm 是否是点击【确认】按钮触发的关闭
-     */
-    close: (confirm: boolean) => void;
-};
 
 /**
  * Toast配置选项
@@ -690,29 +740,65 @@ type ToastOptions = {
      */
     message: string;
 };
+
 /**
- * Toast弹窗句柄
+ * 弹窗管理器
  */
-type ToastHandle = {
+interface IPopupManager {
     /**
-     * 关闭toast弹窗
+     * 弹出
+     * - 弹窗位置位置、大小、动画效果等由组件自己完成
+     * @param options 弹窗配置选项
+     * @returns 弹窗打开结果，外部可手动关闭弹窗
      */
-    close: () => void;
-};
-
+    popup<T>(options: PopupOptions): IAsyncScope<T>;
+    /**
+     * 对话框
+     * - 支持指定模态和非模态对话框
+     * - 默认垂直水平居中展示
+     * @param options 弹窗配置选项
+     * @returns 弹窗打开结果，外部可手动关闭弹窗
+     */
+    dialog<T>(options: DialogOptions): IAsyncScope<T>;
+    /**
+     * 打开【确认】弹窗
+     * @param title  弹窗标题
+     * @param message 确认提示信息，支持html片段
+     * @param options 确认弹窗其他配置信息
+     * @returns 弹窗打开结果，外部可手动关闭弹窗
+     */
+    confirm(title: string, message: string, options?: Omit<ConfirmOptions, "title" | "message">): IAsyncScope<boolean>;
+    /**
+     * Toast 提示框
+     * @param type 提示类型：成功、失败、、、
+     * @param message 提示消息
+     * @param options 提示框配置选项
+     */
+    toast(type: IconType, message: string, options?: Omit<ToastOptions, "type" | "message">): void;
+}
 /**
- * toast提示
- * @param type 提示类型：成功、失败、、、
- * @param message 提示消息
+ * 弹窗描述器
  */
-declare function toast(type: IconType, message: string): void;
+type PopupDescriptor<Options extends PopupOptions, ExtOptions> = PopupFlagOptions & {
+    /**
+     * 弹窗打开的容器组件：如DialogContainer、PopupContainer、、、
+     */
+    container: Component;
+    /**
+     * 弹窗配置选项
+     */
+    options: Options;
+    /**
+     * 扩展数据
+     */
+    extOptions: ExtOptions;
+};
+
 /**
- * 打开【确认】弹窗
- * @param title 弹窗标题
- * @param message 确认提示信息，支持html片段
- * @returns 弹窗句柄
+ * 使用【弹窗管理器】
+ * @returns 全新的【弹窗管理器】实例+作用域对象
  */
-declare function confirm(title: string, message: string): DialogOpenResult<boolean>;
+declare function usePopup(): IPopupManager & IScope;
 
 declare const components: {
     Button: {
@@ -987,15 +1073,5 @@ declare const components: {
     });
 };
 
-/**
- * 挂载vue组件
- * - 全新创建一个Vue实例挂载的传入组件
- * - 用于在非vue环境下渲染vue组件内容
- * @param options 挂载配置选项
- * @param onDestroyed  监听【调用方】的销毁时机，用于自动销毁挂载的实力
- * @returns
- */
-declare function mount(options: ComponentMountOptions, onDestroyed?: (fn: () => void) => void): IScope;
-
-export { components, confirm, getSvgIcon, mount, onAppCreated, openDialog, scopeDialog, toast, triggerAppCreated, useReactive };
-export type { ButtonOptions, ComponentMountOptions, ComponentOptions, ConfirmHandle, ConfirmOptions, Dialog, DialogHandle, DialogOpenResult, DialogOptions, DragVerifyInfo, DragVerifyOptions, EmptyOptions, FoldEvents, FoldOptions, FoldStatus, FooterEvents, FooterOptions, HeaderEvents, HeaderOptions, IconOptions, IconPathOptions, IconType, InputEvents, InputOptions, LoadingOptions, ScrollEvents, ScrollOptions, ScrollTouchType, SwitchEvents, SwitchOptions, TableColOptions, TableOptions, TableRowOptions, ToastHandle, ToastOptions };
+export { components, getSvgIcon, mount, onAppCreated, triggerAppCreated, usePopup, useReactive };
+export type { ButtonOptions, ComponentMountOptions, ComponentOptions, ConfirmOptions, DailogExtend, DialogHandle, DialogOptions, DragVerifyInfo, DragVerifyOptions, EmptyOptions, FoldEvents, FoldOptions, FoldStatus, FooterEvents, FooterOptions, HeaderEvents, HeaderOptions, IPopupManager, IReactiveManager, IconOptions, IconPathOptions, IconType, InputEvents, InputOptions, LoadingOptions, PopupDescriptor, PopupExtend, PopupFlagOptions, PopupHandle, PopupOptions, PopupStatus, ScrollEvents, ScrollOptions, ScrollTouchType, SwitchEvents, SwitchOptions, TableColOptions, TableOptions, TableRowOptions, ToastOptions };