snail.vue 1.0.28 → 1.0.30

package/.code-snippets

@@ -0,0 +1,38 @@
+{
+	"vue template:": {
+		"scope": "vue",
+		"prefix": "VueTemplate",
+		"body": [
+			"<!-- 组件介绍写到这里 -->",
+			"<template>",
+			"\t",
+			"</template>",
+			"",
+			"<script setup lang=\"ts\">",
+			"import { ref, shallowRef, watch ,onActivated, onDeactivated} from \"vue\";",
+			"",
+			"// *****************************************   👉  组件定义    *****************************************",
+			"//  1、props、data",
+			"//  2、可选配置选项",
+			"defineOptions({ name: 组件名称, inheritAttrs: true, });",
+			"",
+			"// *****************************************   👉  方法+事件    ****************************************",
+			"",
+			"// *****************************************   👉  组件渲染    *****************************************",
+			"//  1、数据初始化、变化监听",
+			"//  2、生命周期响应",
+			"",
+			"//      监听组件激活和卸载，适配KeepAlive组件内使用",
+			"onActivated(() => console.log(\"onActivated\"));",
+			"onDeactivated(() => console.log(\"onDeactivated\"));",
+			"</script>",
+			"",
+			"<style lang=\"less\">",
+			"// 引入基础Mixins样式",
+			"@import \"snail.view/dist/styles/base-mixins.less\";",
+			"",
+			"</style>"
+		],
+		"description": "Vue组件模板代码"
+	}
+}

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, Ref, ShallowRef } from 'vue';
-import { IScope } from 'snail.core';
+import { Component, App, ShallowRef } from 'vue';
+import { IScope, IAsyncScope } from 'snail.core';
 
 /**
  * loading提示框的配置选项
@@ -456,6 +456,42 @@ type ButtonOptions = {
     type: "primary" | "default" | "link";
 };
 
+/**
+ * 接口：响应式管理器
+ */
+interface IReactiveManager {
+    /**
+     * 【过渡】响应式变量值
+     * - 通过设置 rv.value 的值来实现.value值过渡
+     * - 执行顺序 from、to
+     * - 开始时，设置 rv.value 值为 from；延迟time时间后，强制销毁scope
+     * - 销毁scope时，强制将 rv.value 值设置为 to 值
+     * @param rv 响应式变量对象
+     * @param effect 过渡效果配置，约束 from end 样式
+     * @param time 过渡持续时间，到时间后销毁作用域
+     * @returns 作用域对象，可销毁【值过渡】效果
+     */
+    transition<T>(rv: {
+        value?: T;
+    }, effect: {
+        from: T;
+        to: T;
+    }, time: number): IScope;
+}
+
+/**
+ * 响应式 模块；
+ *  1、针对Vue的响应式相关功能，做一些便捷封装
+ *  2、方便使用，减少重复性代码量
+ */
+
+/**
+ * 使用【响应式管理器】
+ * - 请在Vue组件的setup中使用此方法，否则 getCurrentScope 方法无法取到值
+ * @returns 全新的【响应式管理器】+作用域
+ */
+declare function useReactive(): IReactiveManager & IScope;
+
 /**
  * Vue App助手类，做一些app实例的辅助性工作
  */
@@ -486,26 +522,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;
 
 /**
- * 作用域ref，方法执行逻辑：
- * -1、初始化作用域，设置rv值： rv.value = start
- * -2、在延迟 dealy 销毁作用域，设置rv值：rv.value = end
- * - 备注示例：可和 snail.core 中的 waitInScope 方法联动实现：api请求开始时显示loading，api请求结束后隐藏loading
- * @param rv 响应式变量对象
- * @param start 起始值，scope创建时执行 rv.value = start
- * @param end 销毁值，scope销毁时执行 rv.value = end
- * @param dealy 销毁时的延迟时间；单位 ms ；实现延迟设置 end 值
- * @returns 新创建的作用域对象
- */
-declare function scopeRef<T>(rv: Ref<T> | ShallowRef<T>, start: T, end: T, dealy?: number): IScope;
+ * 公共通用数据结构：
+ *  1、在弹窗、模态弹窗、跟随弹窗的效果下复用
+ */
 
 /**
- * 模态弹窗显示的组件配置选项
+ * 弹窗配置选项
+ * - 约束弹出组件信息
+ * - 弹出组件时传递的参数信息
  */
-type DialogOptions = ComponentOptions & {
+type PopupOptions = ComponentOptions & {
     /**
      * 传递给组件的属性值，执行v-bind绑定到要显示的组件
      * - key为属性名称，遵循vue解析规则
@@ -514,29 +550,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
      * - 绑定到模态弹窗的根元素上
@@ -544,73 +652,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 = {
-    /**
-     * 弹窗Id，唯一值
-     */
-    id: string;
+type DailogExtend = {
     /**
-     * 模态弹窗显示的组件配置选项
+     * 弹窗状态
      */
-    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>;
-
 /**
  * 确认弹窗配置选项
  */
@@ -647,16 +718,6 @@ type ConfirmOptions = {
      */
     confirmDisabled?: boolean;
 };
-/**
- * 确认弹窗句柄
- */
-type ConfirmHandle = {
-    /**
-     * 关闭弹窗
-     * @param confirm 是否是点击【确认】按钮触发的关闭
-     */
-    close: (confirm: boolean) => void;
-};
 
 /**
  * Toast配置选项
@@ -671,29 +732,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: {
@@ -968,15 +1065,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, scopeRef, toast, triggerAppCreated };
-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 };