clickgo 4.0.0 → 4.0.2

package/dist/lib/dom.d.ts

@@ -0,0 +1,491 @@
+/**
+ * Copyright 2007-2025 MAIYUN.NET
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as clickgo from '../clickgo';
+import * as lCore from './core';
+/**
+ * --- 初始化系统级 ID，仅能设置一次 ---
+ * @param id 系统级 ID
+ */
+export declare function initSysId(id: string): void;
+/**
+ * --- 判断一个元素是否还存在于页面当中 ---
+ * @param el 要判断的元素
+ */
+export declare function inPage(el: HTMLElement): boolean;
+export declare const dpi: number;
+/**
+ * --- 设置全局鼠标样式 ---
+ * @param type 样式或留空，留空代表取消
+ */
+export declare function setGlobalCursor(type?: string): void;
+/**
+ * --- 判断当前的事件是否是含有 touch 的设备触发的，如果当前就是 touch 则直接返回 false（false 代表 OK，true 代表 touch 设备却触发了 mouse 事件） ---
+ */
+export declare function hasTouchButMouse(e: MouseEvent | TouchEvent | PointerEvent): boolean;
+/**
+ * --- 创建任务时连同一起创建的 style 标签 ---
+ * @param taskId 任务 id
+ */
+export declare function createToStyleList(taskId: string): void;
+/**
+ * --- 任务结束时需要移除 task 的所有 style ---
+ * @param taskId 任务 id
+ */
+export declare function removeFromStyleList(taskId: string): void;
+/**
+ * --- 将 style 内容写入 dom ---
+ * @param taskId 当前任务 ID
+ * @param style 样式内容
+ * @param type 插入的类型
+ * @param formId 当前窗体 ID（global 下可空，theme 下为主题唯一标识符，control 下为控件名）
+ * @param panelId 若是 panel 中创建的则需要指定 panelId，仅 type 为 form 有效
+ */
+export declare function pushStyle(taskId: string, style: string, type?: 'global' | 'theme' | 'control' | 'form', formId?: string, panelId?: string): void;
+/**
+ * --- 移除 style 样式 dom ---
+ * @param taskId 要移除的任务 ID
+ * @param type 移除的类型
+ * @param formId 要移除的窗体 ID
+ * @param panelId type 为 form 模式下若不指定则当前 form 包含 panel 的样式都会被移除
+ */
+export declare function removeStyle(taskId: string, type?: 'global' | 'theme' | 'control' | 'form', formId?: string, panelId?: string): void;
+/**
+ * --- 获取任务中子类有几个子元素 ---
+ * @param taskId 任务 ID
+ * @param type 类型
+ */
+export declare function getStyleCount(taskId: clickgo.core.TCurrent, type: 'theme' | 'control' | 'form'): number;
+/**
+ * --- 添加监视 Element 对象位置，元素移除后自动停止监视，已经监视中的不会再次监视，请短时间使用（虽然本方法也可以监听 element 的大小改变，但这是监听位置改变的副产品，如果仅仅监听大小改变请使用效率更高的 watch size） ---
+ * @param el 要监视的大小
+ * @param cb 回调函数
+ * @param immediate 立刻先执行一次回调
+ */
+export declare function watchPosition(el: HTMLElement, cb: (state: {
+    'position': boolean;
+    'size': boolean;
+}) => void | Promise<void>, immediate?: boolean): boolean;
+/**
+ * --- 移除监视 Element 对象位置 ---
+ * @param el 要移除监视
+ */
+export declare function unwatchPosition(el: HTMLElement): void;
+/**
+ * --- 检测一个标签是否正在被 watchSize ---
+ * @param el 要检测的标签
+ */
+export declare function isWatchPosition(el: HTMLElement): boolean;
+/**
+ * --- 清除某个窗体的所有 watch position 监视，虽然窗体结束后相关监视永远不会再被执行，但是会形成冗余 ---
+ * @param formId 窗体 id
+ * @param panelId 若指定则只清除当前窗体的某个 panel 的 watch
+ */
+export declare function clearWatchPosition(formId: string, panelId?: string): void;
+/**
+ * --- 获取当前 watch size 中的元素总数 ---
+ * @param taskId 留空则获取全部总数 ---
+ */
+export declare function getWatchSizeCount(taskId?: lCore.TCurrent): number;
+/**
+ * --- 添加监视 Element 对象大小，元素移除后自动停止监视（浏览器原生效果），已经监视中的不会再次监视 ---
+ * @param current 当前执行的任务
+ * @param el 要监视的大小
+ * @param cb 回调函数
+ * @param immediate 立刻先执行一次回调
+ */
+export declare function watchSize(current: lCore.TCurrent, el: HTMLElement, cb: () => void | Promise<void>, immediate?: boolean): boolean;
+/**
+ * --- 移除监视 Element 对象大小 ---
+ * @param el 要移除监视
+ */
+export declare function unwatchSize(el: HTMLElement): void;
+/**
+ * --- 检测一个标签是否正在被 watchSize ---
+ * @param el 要检测的标签
+ */
+export declare function isWatchSize(el: HTMLElement): boolean;
+/**
+ * --- 清除某个任务的所有 watch size 监视 ---
+ * @param taskId 任务 id
+ */
+export declare function clearWatchSize(taskId: lCore.TCurrent): void;
+/**
+ * --- 获取当前 watch 中的元素总数 ---
+ * @param taskId 留空则获取全部总数 ---
+ */
+export declare function getWatchCount(taskId?: string): number;
+/**
+ * --- 添加 DOM 内容变化监视 ---
+ * @param current 当前任务 id
+ * @param el dom 对象
+ * @param cb 回调
+ * @param mode 监听模式
+ */
+export declare function watch(current: lCore.TCurrent, el: HTMLElement, cb: (mutations: MutationRecord[]) => void | Promise<void>, mode?: 'child' | 'childsub' | 'style' | 'text' | 'default', immediate?: boolean): boolean;
+/**
+ * --- 移除监视 Element 对象变动 ---
+ * @param taskId 任务 id
+ * @param el 要移除监视
+ */
+export declare function unwatch(taskId: lCore.TCurrent, el: HTMLElement): void;
+/**
+ * --- 检测一个标签是否正在被 watchSize ---
+ * @param el 要检测的标签
+ */
+export declare function isWatch(el: HTMLElement): boolean;
+/**
+ * --- 清除某个任务下面的所有 watch 监视 ---
+ * @param taskId 任务 id
+ */
+export declare function clearWatch(taskId: lCore.TCurrent): void;
+/**
+ * --- 监听一个标签的计算后样式的变化 ---
+ * @param el 对象
+ * @param name 样式名
+ * @param cb 变更回调
+ * @param immediate 是否立刻执行一次
+ */
+export declare function watchStyle(el: HTMLElement, name: string | string[], cb: (name: string, value: string, old: string) => void | Promise<void>, immediate?: boolean): void;
+/**
+ * --- 检测一个标签是否正在被 watchStyle ---
+ * @param el 要检测的标签
+ */
+export declare function isWatchStyle(el: HTMLElement): boolean;
+/**
+ * --- 清除某个窗体的所有 watch style 监视 ---
+ * @param formId 窗体 id
+ * @param panelId 若指定则只清除当前窗体的某个 panel 的 watch
+ */
+export declare function clearWatchStyle(formId: string, panelId?: string): void;
+/**
+ * --- 监听一个对象的属性变化 ---
+ * @param el 对象
+ * @param name 属性名
+ * @param cb 回调函数
+ * @param immediate 是否立即执行一次
+ */
+export declare function watchProperty(el: HTMLElement, name: string | string[], cb: (name: string, value: any) => void | Promise<void>, immediate?: boolean): void;
+/**
+ * --- 检测一个标签是否正在被 watchProperty ---
+ * @param el 要检测的标签
+ */
+export declare function isWatchProperty(el: HTMLElement): boolean;
+/**
+ * --- 清除某个窗体的所有 watch property 监视，虽然窗体结束后相关监视永远不会再被执行，但是会形成冗余 ---
+ * @param formId 窗体 id
+ * @param panelId 若指定则只清除当前窗体的某个 panel 的 watch
+ */
+export declare function clearWatchProperty(formId: string, panelId?: string): void;
+export declare function getWatchInfo(): IGetWatchInfoResult;
+/**
+ * --- 鼠标/手指没移动时，click 才生效 ---
+ * @param e 事件对象
+ * @param handler 回调
+ */
+export declare function bindClick(e: MouseEvent | TouchEvent, handler: (e: MouseEvent | TouchEvent, x: number, y: number) => void | Promise<void>): void;
+/**
+ * --- 相当于鼠标/手指两次 click 的效果，并且两次位置差别不太大，dblclick 才生效 ---
+ * @param e 事件对象
+ * @param handler 回调
+ */
+export declare function bindDblClick(e: MouseEvent | TouchEvent, handler: (e: MouseEvent | TouchEvent, x: number, y: number) => void | Promise<void>): void;
+/**
+ * --- 绑定按下以及弹起事件，touch 和 mouse 只会绑定一个 ---
+ * @param oe MouseEvent | TouchEvent
+ * @param opt 回调选项
+ */
+export declare function bindDown<T extends MouseEvent | TouchEvent>(oe: T, opt: IBindDownOptions<T>): void;
+/**
+ * --- 绑定缩放，要绑定到 mousedown、touchstart、touchmove、touchend、wheel 上 ---
+ * @param oe 触发的时间
+ * @param handler 回调函数
+ */
+export declare function bindScale(oe: MouseEvent | TouchEvent | WheelEvent, handler: (e: MouseEvent | TouchEvent | WheelEvent, scale: number, cpos: {
+    'x': number;
+    'y': number;
+}) => void | Promise<void>): void;
+/**
+ * --- 绑定上拉、下拉、左拉、右拉 ---
+ * @param oe 响应事件
+ * @param before before 事件，返回 1 则显示 gesture，0 则不处理（可能会向上传递事件），-1 则 stopPropagation（本层可拖动，若实际不可拖动则可能导致浏览器页面滚动）
+ * @param handler 执行完毕的话才会回调
+ */
+export declare function bindGesture(oe: MouseEvent | TouchEvent | WheelEvent, before: (e: MouseEvent | TouchEvent | WheelEvent, dir: 'top' | 'right' | 'bottom' | 'left') => number, handler?: (dir: 'top' | 'right' | 'bottom' | 'left') => void | Promise<void>): void;
+export declare function allowEvent(e: MouseEvent | TouchEvent | KeyboardEvent): boolean;
+/**
+ * --- 绑定长按事件 ---
+ * @param e 事件原型
+ * @param long 回调
+ */
+export declare function bindLong(e: MouseEvent | TouchEvent, long: (e: MouseEvent | TouchEvent) => void | Promise<void>): void;
+/**
+ * --- 重新绑定 drag 数据 ---
+ * @param data 要绑定的数据
+ */
+export declare function setDragData(data?: string | number | boolean | Record<string, any>): void;
+/**
+ * --- 绑定拖动 ---
+ * @param e 鼠标事件
+ * @param opt 参数
+ */
+export declare function bindDrag(e: MouseEvent | TouchEvent, opt: {
+    'el': HTMLElement;
+    'data'?: any;
+    'start'?: (x: number, y: number) => any;
+    'move'?: (e: MouseEvent | TouchEvent, opt: IBindMoveMoveOptions) => void;
+    'end'?: (moveTimes: Array<{
+        'time': number;
+        'ox': number;
+        'oy': number;
+    }>, e: MouseEvent | TouchEvent) => void;
+}): void;
+/** --- 目前是否已绑定了 bindMove --- */
+export declare let is: {
+    'move': boolean;
+    'shift': boolean;
+    'ctrl': boolean;
+    'meta': boolean;
+    'full': boolean;
+    'dark': boolean;
+};
+/**
+ * --- 绑定拖动事件 ---
+ * @param e mousedown 或 touchstart 的 event
+ * @param opt 回调选项
+ */
+export declare function bindMove(e: MouseEvent | TouchEvent, opt: IBindMoveOptions): IBindMoveResult;
+/**
+ * --- 绑定拖动改变大小事件 ---
+ * @param e mousedown 或 touchstart 的 event
+ * @param opt 选项，width, height 当前对象宽高
+ */
+export declare function bindResize(e: MouseEvent | TouchEvent, opt: IBindResizeOptions): void;
+/**
+ * --- 通过 data 名查找上层所有标签是否存在 ---
+ * @param el 当前标签
+ * @param name 要查找的 data 名
+ * @param value data 对应的值，留空则代表只要匹配了名就可以
+ */
+export declare function findParentByData(el: HTMLElement, name: string, value?: string): HTMLElement | null;
+/**
+ * --- 通过 class 名查找上层所有标签是否存在 ---
+ * @param el 当前标签
+ * @param name 要查找的 class 名
+ */
+export declare function findParentByClass(el: HTMLElement, name: string): HTMLElement | null;
+/**
+ * --- 通过 tagname 查找上层所有标签是否存在 ---
+ * @param el 当前标签
+ * @param name 要查找的 tagname 名，小写，如 table
+ */
+export declare function findParentByTag(el: HTMLElement, name: string): HTMLElement | null;
+/**
+ * --- 判断一个元素是当前同级的第几位 ---
+ * @param el 要判断的元素
+ */
+export declare function index(el: HTMLElement): number;
+/**
+ * --- 查找指定 el 的同级所有元素 ---
+ * @param el 基准
+ * @returns HTMLElement[]
+ */
+export declare function siblings(el: HTMLElement): HTMLElement[];
+/**
+ * --- 查找指定 el 的同级的存在 data 的元素 ---
+ * @param el 基准
+ * @param name data 名，不含 data-
+ * @returns HTMLElement[]
+ */
+export declare function siblingsData(el: HTMLElement, name: string): HTMLElement[];
+/**
+ * --- 全屏 ---
+ */
+export declare function fullscreen(): Promise<boolean>;
+/**
+ * --- 退出全屏 ---
+ */
+export declare function exitFullscreen(): Promise<boolean>;
+/**
+ * --- 创建 element ---
+ * @param tagName 标签名
+ */
+export declare function createElement<T extends keyof HTMLElementTagNameMap>(tagName: T): HTMLElementTagNameMap[T];
+export declare function init(): void;
+/** --- 方向类型，从左上开始 --- */
+export type TDomBorder = 'lt' | 't' | 'tr' | 'r' | 'rb' | 'b' | 'bl' | 'l' | '';
+export type TDomBorderCustom = TDomBorder | {
+    'left': number;
+    'top'?: number;
+    'width': number;
+    'height'?: number;
+};
+/** --- Element 的大小 --- */
+export interface IDomSize {
+    'top': number;
+    'right': number;
+    'bottom': number;
+    'left': number;
+    'width': number;
+    'height': number;
+    'padding': {
+        'top': number;
+        'right': number;
+        'bottom': number;
+        'left': number;
+    };
+    'border': {
+        'top': number;
+        'right': number;
+        'bottom': number;
+        'left': number;
+    };
+    'clientHeight': number;
+    'clientWidth': number;
+    'innerWidth': number;
+    'innerHeight': number;
+    'scrollWidth': number;
+    'scrollHeight': number;
+}
+/** --- 绑定鼠标事件选项 --- */
+export interface IBindDownOptions<T extends MouseEvent | TouchEvent> {
+    'down'?: (e: T) => void;
+    'start'?: (e: T) => any;
+    'move'?: (e: T, dir: 'top' | 'right' | 'bottom' | 'left') => any;
+    'up'?: (e: T) => void | Promise<void>;
+    'end'?: (e: T) => void | Promise<void>;
+}
+/** --- 绑定拖动选项 move 回调的回调参数 --- */
+export interface IBindMoveMoveOptions {
+    'ox': number;
+    'oy': number;
+    'x': number;
+    'y': number;
+    'border': TDomBorder;
+    'inBorder': {
+        'top': boolean;
+        'right': boolean;
+        'bottom': boolean;
+        'left': boolean;
+    };
+    'dir': 'top' | 'right' | 'bottom' | 'left';
+}
+/** --- 绑定拖动选项 --- */
+export interface IBindMoveOptions {
+    'areaObject'?: HTMLElement | lCore.IVue;
+    'left'?: number;
+    'top'?: number;
+    'right'?: number;
+    'bottom'?: number;
+    'offsetLeft'?: number;
+    'offsetTop'?: number;
+    'offsetRight'?: number;
+    'offsetBottom'?: number;
+    'objectLeft'?: number;
+    'objectTop'?: number;
+    'objectWidth'?: number;
+    'objectHeight'?: number;
+    'object'?: HTMLElement | lCore.IVue;
+    'showRect'?: boolean;
+    'cursor'?: string;
+    'start'?: (x: number, y: number) => any;
+    'move'?: (e: MouseEvent | TouchEvent, opt: IBindMoveMoveOptions) => void;
+    'up'?: (moveTimes: Array<{
+        'time': number;
+        'ox': number;
+        'oy': number;
+    }>, e: MouseEvent | TouchEvent) => void;
+    'end'?: (moveTimes: Array<{
+        'time': number;
+        'ox': number;
+        'oy': number;
+    }>, e: MouseEvent | TouchEvent) => void;
+    'borderIn'?: (x: number, y: number, border: TDomBorder, e: MouseEvent | TouchEvent) => void;
+    'borderOut'?: () => void;
+}
+/** --- 绑定拖动返回值 --- */
+export interface IBindMoveResult {
+    'left': number;
+    'top': number;
+    'right': number;
+    'bottom': number;
+}
+/** --- 绑定改变大小选项 --- */
+export interface IBindResizeOptions {
+    'objectLeft'?: number;
+    'objectTop'?: number;
+    'objectWidth'?: number;
+    'objectHeight'?: number;
+    'object'?: HTMLElement | lCore.IVue;
+    'minWidth'?: number;
+    'minHeight'?: number;
+    'maxWidth'?: number;
+    'maxHeight'?: number;
+    'border': TDomBorder;
+    'start'?: (x: number, y: number) => any;
+    'move'?: (left: number, top: number, width: number, height: number, x: number, y: number, border: TDomBorder) => void;
+    'end'?: () => void;
+}
+/** --- 监视位置中的元素 --- */
+export interface IWatchPositionItem {
+    'el': HTMLElement;
+    'rect': DOMRect;
+    'handler': (state: {
+        'position': boolean;
+        'size': boolean;
+    }) => void | Promise<void>;
+}
+/** --- 监视大小中的元素 --- */
+export interface IWatchSizeItem {
+    'el': HTMLElement;
+    'handler': () => void | Promise<void>;
+    'taskId': string | null;
+}
+/** --- 监视变化中的元素 --- */
+export interface IWatchItem {
+    'el': HTMLElement;
+    'mo': MutationObserver;
+    'taskId'?: string;
+}
+/** --- 获取当前正在监视中的 property、style 和 position 的元素信息 --- */
+export interface IGetWatchInfoResult {
+    'formId': string;
+    'default': Record<string, {
+        'style': {
+            'list': string[];
+            'count': number;
+        };
+        'property': {
+            'list': string[];
+            'count': number;
+        };
+        'position': {
+            'count': number;
+        };
+    }>;
+    'panels': Record<string, Record<string, {
+        'style': {
+            'list': string[];
+            'count': number;
+        };
+        'property': {
+            'list': string[];
+            'count': number;
+        };
+        'position': {
+            'count': number;
+        };
+    }>>;
+}