@whitesev/utils 2.11.7 → 2.11.9

package/dist/types/src/Utils.d.ts

@@ -351,17 +351,26 @@ declare class Utils {
     /**
      * 获取页面的坐标中最大的z-index的元素信息
      *
-     * 其中坐标为
-     *
-     * + 左上角（宽: 1/8，高: 1/8）
-     * + 右上角（宽: 7/8，高: 1/8）
-     * + 左下角（宽: 1/8，高: 7/8）
-     * + 右下角（宽: 7/8，高: 7/8）
-     * + 中间（宽: 1/2，高: 1/2）
+     * 矩阵坐标计算
      * @param $el 仅检测目标元素最大的z-index（自动往上层找）
      * @param deviation 将对所有获取到的z-index处理偏移量（增加或减少），默认为10
+     * @example
+     * Utils.getMaxZIndexNodeInfoFromPoint(document.querySelector("a"));
+     * @example
+     * Utils.getMaxZIndexNodeInfoFromPoint(document.querySelector("a"), 20);
+     * @example
+     * Utils.getMaxZIndexNodeInfoFromPoint([document.querySelector("a"), document.querySelector("div")]);
+     * @example
+     * Utils.getMaxZIndexNodeInfoFromPoint({x: 500, y: 500});
+     * @example
+     * Utils.getMaxZIndexNodeInfoFromPoint({x: 500, y: 500}, 20);
+     * @example
+     * Utils.getMaxZIndexNodeInfoFromPoint(() => {x: 500, y: 500}, 20);
      */
-    getMaxZIndexNodeInfoFromPoint($el?: IFunction<HTMLElement | HTMLElement[]>, deviation?: number): {
+    getMaxZIndexNodeInfoFromPoint($el?: IFunction<IArray<HTMLElement> | IArray<{
+        x: number;
+        y: number;
+    }>>, deviation?: number): {
         /** 处理了偏移量后的z-index值 */
         zIndex: number;
         /** 原始z-index值 */
@@ -378,14 +387,10 @@ declare class Utils {
     /**
      * 获取页面的坐标中最大的z-index的元素信息
      *
-     * 其中坐标为
-     *
-     * + 左上角（宽: 1/8，高: 1/8）
-     * + 右上角（宽: 7/8，高: 1/8）
-     * + 左下角（宽: 1/8，高: 7/8）
-     * + 右下角（宽: 7/8，高: 7/8）
-     * + 中间（宽: 1/2，高: 1/2）
+     * 矩阵坐标计算
      * @param deviation 将对所有获取到的z-index处理偏移量（增加或减少）
+     * @example
+     * Utils.getMaxZIndexNodeInfoFromPoint(20);
      */
     getMaxZIndexNodeInfoFromPoint(deviation: IFunction<number>): {
         /** 处理了偏移量后的z-index值 */
@@ -1491,8 +1496,22 @@ declare class Utils {
      * 深度获取对象的某个属性
      * @param target 待获取的对象
      * @param handler 获取属性的回调
+     * @example
+     * Utils.queryProperty(window,(target)=>{
+     *   if(target.xxx){
+     *     return {
+     *       isFind: true,
+     *       data: target.xxx,
+     *     }
+     *   }else{
+     *     return {
+     *       isFind: false,
+     *       data: target.aabbcc,
+     *     }
+     *   }
+     * })
      */
-    queryProperty<T = any>(target: any, handler: (
+    queryProperty<T = any, R = any>(target: any, handler: (
     /**
      * 该值为返回的data值
      */
@@ -1505,26 +1524,37 @@ declare class Utils {
         isFind: boolean;
         /**
          * 对象/目标值
+         *
+         * 若`isFind`为true，那该值为返回的结果
+         *
+         * 若`isFind`为false，那该值为下次迭代传入的`target`
          */
-        data: any;
-    }): any;
+        data: T | R | null | void;
+    }): R | void | null;
     /**
      * 异步-深度获取对象属性
      * @param target 待获取的对象
      * @param handler 获取属性的回调
+     * @example
+     * Utils.asyncQueryProperty(window, async (target)=>{
+     *   if(target.xxx){
+     *     return {
+     *       isFind: true,
+     *       data: target.xxx,
+     *     }
+     *   }else{
+     *     return {
+     *       isFind: false,
+     *       data: target.aabbcc,
+     *     }
+     *   }
+     * })
      */
-    asyncQueryProperty<T = any>(target: any, handler: (target: T) => {
-        /**
-         * 是否是需要的属性
-         * + true 将目标值赋值给data
-         * + false 不是需要的，data为下一个处理的对象
-         */
-        isFind: boolean;
-        /**
-         * 对象/目标值
-         */
-        data: any;
-    } | Promise<{
+    asyncQueryProperty<T = any, R = any>(target: any, handler: (
+    /**
+     * 该值为返回的data值
+     */
+    target: T) => IPromise<{
         /**
          * 是否是需要的属性
          * + true 将目标值赋值给data
@@ -1533,13 +1563,18 @@ declare class Utils {
         isFind: boolean;
         /**
          * 对象/目标值
+         *
+         * 若`isFind`为true，那该值为返回的结果
+         *
+         * 若`isFind`为false，那该值为下次迭代传入的`target`
          */
-        data: any;
-    }>): Promise<Awaited<T>>;
+        data: T | R | null | void;
+    }>): Promise<R | void | null>;
     /**
      * 创建一个新的Utils实例
      * @param option
-     * @returns
+     * @example
+     * Utils.createUtils();
      */
     createUtils(option?: WindowApiOption): Utils;
     /**
@@ -1567,7 +1602,9 @@ declare class Utils {
     /**
      * 覆盖对象中的函数this指向
      * @param target 需要覆盖的对象
-     * @param [objectThis] 覆盖的this指向，如果为传入，则默认为对象本身
+     * @param objectThis 覆盖的this指向，如果为传入，则默认为对象本身
+     * @example
+     * Utils.coverObjectFunctionThis({})
      */
     coverObjectFunctionThis: (target: any, objectThis?: any) => void;
     /**
@@ -1618,7 +1655,7 @@ declare class Utils {
     /**
      * 自动使用 Worker 执行 setTimeout
      * @param callback 回调函数
-     * @param [timeout=0] 延迟时间，默认为0
+     * @param timeout 延迟时间，默认为0
      */
     workerSetTimeout(callback: (...args: any[]) => any, timeout?: number): number;
     /**
@@ -1678,6 +1715,10 @@ declare class Utils {
     /**
      * 判断页面中是否存在`worker-src`的CSP规则
      * @param timeout 超时时间，默认为`1500ms`
+     * @example
+     * Utils.hasWorkerCSP().then((hasCSP) => {
+     *   console.log(hasCSP);
+     * })
      */
     hasWorkerCSP(timeout?: number): Promise<boolean>;
     /**
@@ -1686,12 +1727,18 @@ declare class Utils {
      * @param positionY 坐标y信息
      * @param otherPositionX 坐标x信息
      * @param otherPositionY 坐标y信息
+     * @example
+     * Utils.calcPositionDistance(1, 2, 3, 4);
+     * > 2.8284271247461903
      */
     calcPositionDistance(positionX: number | string, positionY: number | string, otherPositionX: number | string, otherPositionY: number | string): number;
     /**
      * 计算两个坐标的直线距离
      * @param position 坐标信息
      * @param otherPosition 坐标信息
+     * @example
+     * Utils.calcPositionDistance({x: 1, y: 2}, {x: 3, y: 4});
+     * > 2.8284271247461903
      */
     calcPositionDistance(position: {
         x: number | string;

package/dist/types/src/types/env.d.ts

@@ -9,3 +9,5 @@ declare var msIndexedDB: IDBFactory | null;
 declare type IPromise<T> = T | Promise<T>;
 
 declare type IFunction<T> = T | (() => T);
+
+declare type IArray<T> = T | Array<T>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@whitesev/utils",
-  "version": "2.11.7",
+  "version": "2.11.9",
   "description": "一个常用的工具库",
   "keywords": [
     "ScriptCat",