ph-utils 0.20.0 → 0.20.1

package/lib/dom.js

@@ -166,19 +166,24 @@ export function replaceClass(el, oldClazz, newClazz) {
  * @param {boolean}     option  是否是只运行一次的处理函数或者配置，其中 eventFlag 为 string，如果配置该项，则表明为委托事件
  */
 export function on(element, listener, fn, option) {
-    if (element.length != null) {
-        iterate(element, (elem) => {
-            if (typeof option === "object" && option.eventFlag) {
-                elem.setAttribute(option.eventFlag, "__stop__");
-            }
-            elem.addEventListener(listener, fn, option);
-        });
-    }
-    else if (element) {
-        if (typeof option === "object" && option.eventFlag) {
-            element.setAttribute(option.eventFlag, "__stop__");
+    // 提取公共的绑定逻辑
+    const addListener = (el) => {
+        // 重要：只有 Element (包含 HTMLElement) 才有 setAttribute 方法
+        // Document 和 ShadowRoot 是没有 setAttribute 的，必须做类型守卫
+        if (typeof option === "object" && option?.eventFlag && el instanceof Element) {
+            el.setAttribute(option.eventFlag, "__stop__");
         }
-        element.addEventListener(listener, fn, option);
+        el.addEventListener(listener, fn, option);
+    };
+    // 核心识别逻辑：
+    // 如果是 Node 实例，说明是单一节点（HTMLElement, Document, ShadowRoot 都是 Node）
+    if (element instanceof Node) {
+        addListener(element);
+    }
+    else {
+        // 否则，说明是 HTMLCollection、NodeList 或 Array，直接遍历
+        // （即使 length 为 0，iterate 内部通常也会安全跳过，不需要在外部判断 length > 0）
+        iterate(element, addListener);
     }
 }
 /**
@@ -188,13 +193,18 @@ export function on(element, listener, fn, option) {
  * @param fn - 要移除的事件监听器函数。
  */
 export function off(el, listener, fn, option) {
-    if (el.length != null) {
-        iterate(el, (elem) => {
-            elem.removeEventListener(listener, fn, option);
-        });
+    // 提取公共的解绑逻辑
+    // HTMLElement、Document、ShadowRoot 本质上都实现了 EventTarget 接口
+    const removeListener = (target) => {
+        target.removeEventListener(listener, fn, option);
+    };
+    // 核心判断：只要是 Node，就是单一节点
+    if (el instanceof Node) {
+        removeListener(el);
     }
-    else if (el) {
-        el.removeEventListener(listener, fn, option);
+    else {
+        // 否则就是集合（HTMLCollection / NodeList / Array），直接遍历
+        iterate(el, removeListener);
     }
 }
 /**

package/lib/src/array.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 数组排序
+ * @param arr 待排序数组
+ * @param order 排序信息, asc - 升序, desc - 倒序
+ * @param orderKey 如果是个对象数组，按哪个字段排序
+ * @returns
+ */
+export declare function order<T>(arr: T[], order?: "asc" | "desc", orderKey?: string | null): T[];
+/**
+ * 返回一个所有集合交集的新集合
+ *
+ * 如果集合本身支持 intersection, 则调用原生 intersection 函数
+ *
+ * @param arrs
+ *
+ * @returns 新集合中的元素在传入的所有集合中同时存在
+ */
+export declare function intersection<T>(...arrs: Set<T>[]): Set<T>;
+/**
+ * 返回一个所有列表交集的新列表
+ *
+ * @param arrs
+ *
+ * @returns 新列表中的元素在传入的所有列表中同时存在
+ */
+export declare function intersection<T>(...arrs: T[][]): T[];
+/**
+ * 返回一个包含第一个集合中的元素但不包含后续给定集合中元素的新集合
+ *
+ * 如果集合本身支持 difference 方法，则调用原生 difference 方法
+ *
+ * @param arrs 集合列表
+ *
+ * @returns
+ */
+export declare function difference<T>(...arrs: Set<T>[]): Set<T>;
+/**
+ * 返回一个包含第一个列表中的元素但不包含后续给定列表中元素的新列表
+ *
+ * @param arrs 二维列表
+ *
+ * @returns
+ */
+export declare function difference<T>(...arrs: T[][]): T[];
+/**
+ * 返回多个集合的并集, 如果支持 union，则调用原生 union
+ *
+ * @param arrs
+ *
+ * @returns 一个包含所有给定集合的所有元素的新集合
+ */
+export declare function union<T>(...arrs: Set<T>[]): Set<T>;
+export declare function union<T>(...arrs: T[][]): T[];
+export declare function symmetricDifference<T>(...arrs: Set<T>[]): Set<T>;
+export declare function symmetricDifference<T>(...arrs: T[][]): T[];
+/**
+ * 返回一个布尔值，指示此集合中的所有元素是否都在给定的集合中。
+ * @param a1
+ * @param a2
+ * @returns
+ */
+export declare function isSubsetOf<T>(a1: T[] | Set<T>, a2: T[] | Set<T>): boolean;
+/**
+ * 返回一个布尔值，指示给定集合中的所有元素是否都在此集合中。
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export declare function isSupersetOf<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>): boolean;
+/**
+ * 返回一个布尔值，指示此集合是否与给定集合没有公共元素。
+ *
+ * 判断两个集合是否有交集, 也可以通过 intersection(arr1, arr2).length 判断
+ *
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export declare function isDisjointFrom<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>): boolean;

package/lib/src/array.js

@@ -0,0 +1,212 @@
+/**
+ * 数组排序
+ * @param arr 待排序数组
+ * @param order 排序信息, asc - 升序, desc - 倒序
+ * @param orderKey 如果是个对象数组，按哪个字段排序
+ * @returns
+ */
+export function order(arr, order = "asc", orderKey = null) {
+    const collator = new Intl.Collator(undefined, { numeric: true });
+    return arr.sort((a, b) => {
+        let aValue = a;
+        let bValue = b;
+        if (typeof a === "object" && orderKey != null) {
+            // @ts-ignore
+            aValue = a[orderKey];
+            // @ts-ignore
+            bValue = b[orderKey];
+        }
+        let aGtb = -1;
+        if (typeof aValue === "string") {
+            aGtb = collator.compare(aValue, bValue);
+        }
+        else {
+            aGtb = aValue >= bValue ? 1 : -1;
+        }
+        return order === "asc" ? aGtb : -aGtb;
+    });
+}
+/**
+ * 返回所有集合交集的元素的新集合
+ */ export function intersection(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (cur instanceof Set) {
+            //@ts-ignore
+            if (cur.intersection != null) {
+                //@ts-ignore
+                return acc.intersection(cur);
+            }
+            else {
+                const res = new Set();
+                for (const value of acc) {
+                    if (cur.has(value)) {
+                        res.add(value);
+                    }
+                }
+                return res;
+            }
+        }
+        else {
+            return acc.filter((x) => cur.includes(x));
+        }
+    });
+}
+/**
+ * 返回一个包含第一个集合中的元素但不包含后续给定集合中元素的新集合
+ * @param arrs 新集合
+ * @returns
+ */
+export function difference(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (acc instanceof Set) {
+            //@ts-ignore
+            if (acc.difference != null) {
+                //@ts-ignore
+                return acc.difference(cur);
+            }
+            else {
+                const res = new Set();
+                for (const value of acc) {
+                    if (!cur.has(value)) {
+                        res.add(value);
+                    }
+                }
+                return res;
+            }
+        }
+        else {
+            const res = [];
+            for (const value of acc) {
+                if (!cur.includes(value)) {
+                    res.push(value);
+                }
+            }
+            return res;
+        }
+    });
+}
+export function union(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (cur instanceof Set) {
+            //@ts-ignore
+            if (cur.union != null) {
+                //@ts-ignore
+                return acc.union(cur);
+            }
+            return new Set([...acc, ...cur]);
+        }
+        else {
+            return [...acc, ...cur];
+        }
+    });
+}
+/**
+ * 对称差: 返回一个包含此集合或给定集合中的元素的新集合，但不包含同时存在于这两个集合中的元素。
+ * @param arrs
+ * @returns
+ */
+export function symmetricDifference(...arrs) {
+    return arrs.reduce((acc, cur) => {
+        if (cur instanceof Set) {
+            //@ts-ignore
+            if (cur.symmetricDifference != null) {
+                //@ts-ignore
+                return acc.symmetricDifference(cur);
+            }
+            const res = new Set();
+            for (const item of acc) {
+                if (!cur.has(item)) {
+                    res.add(item);
+                }
+            }
+            for (const item of cur) {
+                if (!acc.has(item)) {
+                    res.add(item);
+                }
+            }
+            return res;
+        }
+        const res = [];
+        for (const item of acc) {
+            if (!cur.includes(item)) {
+                res.push(item);
+            }
+        }
+        for (const item of cur) {
+            if (!acc.includes(item)) {
+                res.push(item);
+            }
+        }
+        return res;
+    });
+}
+/**
+ * 返回一个布尔值，指示此集合中的所有元素是否都在给定的集合中。
+ * @param a1
+ * @param a2
+ * @returns
+ */
+export function isSubsetOf(a1, a2) {
+    //@ts-ignore
+    if (a1 instanceof Set && a1.isSubsetOf != null) {
+        //@ts-ignore
+        return a1.isSubsetOf(a2);
+    }
+    let is = true;
+    for (const item of a1) {
+        if (a2 instanceof Set) {
+            if (!a2.has(item)) {
+                is = false;
+                break;
+            }
+        }
+        else {
+            if (!a2.includes(item)) {
+                is = false;
+                break;
+            }
+        }
+    }
+    return is;
+}
+/**
+ * 返回一个布尔值，指示给定集合中的所有元素是否都在此集合中。
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export function isSupersetOf(arr1, arr2) {
+    return isSubsetOf(arr2, arr1);
+}
+/**
+ * 返回一个布尔值，指示此集合是否与给定集合没有公共元素。
+ *
+ * 判断两个集合是否有交集, 也可以通过 intersection(arr1, arr2).length 判断
+ *
+ * @param arr1
+ * @param arr2
+ * @returns
+ */
+export function isDisjointFrom(arr1, arr2) {
+    //@ts-ignore
+    if (arr1 instanceof Set && arr1.isDisjointFrom != null) {
+        //@ts-ignore
+        return arr1.isDisjointFrom(arr2);
+    }
+    let is = true;
+    for (const item of arr1) {
+        if (arr2 instanceof Set) {
+            if (arr2.has(item)) {
+                is = false;
+                break;
+            }
+        }
+        else {
+            if (arr2.includes(item)) {
+                is = false;
+                break;
+            }
+        }
+    }
+    return is;
+}

package/lib/src/color.d.ts

@@ -0,0 +1,55 @@
+type RGBColorObject = {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+};
+type HSVColorObject = {
+    h: number;
+    s: number;
+    v: number;
+};
+type ColorType = string | RGBColorObject | HSVColorObject;
+/**
+ * 将输入的颜色值转换为RGB对象格式。
+ *
+ * @param color 可以是字符串, 也可以是一个 HSV 对象[一个包含 h、s、v 属性的对象]
+ * @returns 返回一个包含r、g、b和a（透明度）属性的RGB对象。
+ * @throws 如果输入的字符串不是有效的颜色表示，则抛出错误。
+ */
+export declare function toRgb(color: ColorType): RGBColorObject;
+/**
+ * 将颜色转换为HSV颜色模型。
+ *
+ * @param color - 字符串或者RGB对象
+ * @returns 返回一个包含h、s、v属性的对象，代表HSV颜色值，其中h是色相（取值范围0到360），s是饱和度（取值范围0到1），v是明度（取值范围0到1）。
+ */
+export declare function toHsv(color: ColorType): HSVColorObject;
+/**
+ * 将RGB颜色对象转换为十六进制颜色字符串。
+ * @param rgb - 包含红色(r), 绿色(g), 蓝色(b)成分的对象。
+ * @returns 返回一个表示RGB颜色的十六进制字符串，例如"#FF0000"。
+ */
+export declare function rgbToHex(rgb: RGBColorObject): string;
+/**
+ * 将颜色转换为 16 进制字符串
+ * @param color - 颜色, 可以 rgb(0,0,0),rgba(0,0,0,0)字符串, 也可以是 rgb、hsv对象
+ * @returns 返回颜色的十六进制字符串，例如"#FF0000"
+ */
+export declare function toHex(color: ColorType): string;
+/**
+ * 调整给定颜色深[darken]浅[lighten]
+ * @param color - 输入的颜色，可以是任意颜色表示方式
+ * @param level - 调整深浅级别, 可以是小数。默认: 1
+ * @param light - 控制调整的方向。如果为true，[lighten] 变浅，如果为false，[darken] 变深。默认: true
+ *
+ * #### 1. 颜色变浅
+ *
+ * ```
+ * adjust('#4998f4', 3, true)
+ * ```
+ *
+ * @returns 返回调整后颜色的十六进制字符串表示。
+ */
+export declare function adjust(color: ColorType, level?: number, light?: boolean): string;
+export {};

package/lib/src/color.js

@@ -0,0 +1,294 @@
+const hueStep = 2; // 色相阶梯
+const saturationStep = 0.16; // 饱和度阶梯，浅色部分
+const saturationStep2 = 0.05; // 饱和度阶梯，深色部分
+const brightnessStep1 = 0.05; // 亮度阶梯，浅色部分
+const brightnessStep2 = 0.15; // 亮度阶梯，深色部分
+/* 解析: rgb(0,0,0), rgba(0,0,0,0.1) 格式的正则 */
+const rgbRegex = /rgba?\s*\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})(?:\s*,\s*(\d*\.?\d+))?\s*\)/;
+/* 匹配 16 进制颜色字符串的正则: #fff, #ffffff */
+const hexRegex = /^#(?:([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})|([0-9A-Fa-f]{1})([0-9A-Fa-f]{1})([0-9A-Fa-f]{1}))$/;
+function isRgb(color) {
+    return color.r != null && color.g != null && color.b != null;
+}
+function isHsv(color) {
+    return color.h != null && color.s != null && color.v != null;
+}
+function parseRgbString(color) {
+    let colorValue = color.match(rgbRegex);
+    if (colorValue != null) {
+        const r = parseInt(colorValue[1].trim());
+        const g = parseInt(colorValue[2].trim());
+        const b = parseInt(colorValue[3].trim());
+        // 检查RGB值是否为NaN
+        if (isNaN(r) || isNaN(g) || isNaN(b)) {
+            throw new Error("Invalid RGB color.");
+        }
+        let a = 1;
+        // 如果是RGBA，解析透明度值
+        if (colorValue[4] != null) {
+            a = parseFloat(colorValue[4].trim());
+            if (isNaN(a)) {
+                a = 1;
+            }
+        }
+        return {
+            r,
+            g,
+            b,
+            a,
+        };
+    }
+}
+function parseHexString(color) {
+    const colorMatch = color.match(hexRegex);
+    if (colorMatch != null) {
+        // 判断是否是缩写形式的颜色（3个字符）
+        const isShortForm = colorMatch[4] !== undefined;
+        const r = parseInt(isShortForm ? colorMatch[4] + colorMatch[4] : colorMatch[1], 16);
+        const g = parseInt(isShortForm ? colorMatch[5] + colorMatch[5] : colorMatch[2], 16);
+        const b = parseInt(isShortForm ? colorMatch[6] + colorMatch[6] : colorMatch[3], 16);
+        return {
+            r,
+            g,
+            b,
+        };
+    }
+}
+/**
+ * 将输入的颜色值转换为RGB对象格式。
+ *
+ * @param color 可以是字符串, 也可以是一个 HSV 对象[一个包含 h、s、v 属性的对象]
+ * @returns 返回一个包含r、g、b和a（透明度）属性的RGB对象。
+ * @throws 如果输入的字符串不是有效的颜色表示，则抛出错误。
+ */
+export function toRgb(color) {
+    if (typeof color === "string") {
+        let rgb = parseHexString(color);
+        if (rgb == null) {
+            rgb = parseRgbString(color);
+        }
+        if (rgb != null) {
+            return rgb;
+        }
+        throw new Error("Invalid color string");
+    }
+    else {
+        // 处理RGB对象输入
+        if (isRgb(color)) {
+            return color;
+        }
+        else if (isHsv(color)) {
+            return hsvToRgb(color);
+        }
+        throw new Error("Invalid color");
+    }
+}
+/**
+ * 将颜色转换为HSV颜色模型。
+ *
+ * @param color - 字符串或者RGB对象
+ * @returns 返回一个包含h、s、v属性的对象，代表HSV颜色值，其中h是色相（取值范围0到360），s是饱和度（取值范围0到1），v是明度（取值范围0到1）。
+ */
+export function toHsv(color) {
+    if (isHsv(color))
+        return color;
+    const rgbColor = toRgb(color);
+    // 将RGB值标准化到0到1的范围
+    const r = rgbColor.r / 255;
+    const g = rgbColor.g / 255;
+    const b = rgbColor.b / 255;
+    // 获取最大和最小值，计算色彩的明度（V）
+    let max = Math.max(r, g, b);
+    let min = Math.min(r, g, b);
+    let delta = max - min;
+    let v = max;
+    // 计算饱和度（S）
+    let s = max === 0 ? 0 : delta / max;
+    // 计算色相（H）
+    let h = 0;
+    if (max === min) {
+        h = 0; // achromatic (no hue)
+    }
+    else {
+        // 根据最大值和最小值的不同，计算色相
+        switch (max) {
+            case r:
+                h = ((g - b) / delta + (g < b ? 6 : 0)) / 6;
+                break;
+            case g:
+                h = ((b - r) / delta + 2) / 6;
+                break;
+            case b:
+                h = ((r - g) / delta + 4) / 6;
+                break;
+        }
+    }
+    // 将色相值乘以360，转换为度数
+    h = h * 360;
+    return { h, s, v };
+}
+/**
+ * 将HSV颜色模型转换为RGB颜色模型。
+ * @param hsv 包含色相(h)、饱和度(s)和明度(v)的对象。s 和 v 可以是 0~1之间的小数, 也可以是 0~100 直接的整数, 推荐为小数，结果更精准
+ * @returns 返回一个包含红色(r)、绿色(g)和蓝色(b)值的对象，范围为0-255。
+ */
+function hsvToRgb(hsv) {
+    // 将百分比形式的饱和度和明度转换为0-1的数值
+    let s = hsv.s;
+    let v = hsv.v;
+    if (s > 1) {
+        s /= 100;
+    }
+    if (v > 1) {
+        v /= 100;
+    }
+    const h = hsv.h;
+    // 根据色相值计算色相角，并计算出六个区域中的位置
+    var hi = Math.floor(h / 60) % 6;
+    var f = h / 60 - Math.floor(h / 60);
+    var p = v * (1 - s);
+    var q = v * (1 - f * s);
+    var t = v * (1 - (1 - f) * s);
+    // 根据色相角确定RGB值的具体计算
+    let r = 0, g = 0, b = 0;
+    switch (hi) {
+        case 0:
+            r = v;
+            g = t;
+            b = p;
+            break;
+        case 1:
+            r = q;
+            g = v;
+            b = p;
+            break;
+        case 2:
+            r = p;
+            g = v;
+            b = t;
+            break;
+        case 3:
+            r = p;
+            g = q;
+            b = v;
+            break;
+        case 4:
+            r = t;
+            g = p;
+            b = v;
+            break;
+        case 5:
+            r = v;
+            g = p;
+            b = q;
+            break;
+    }
+    // 将计算得到的RGB值从0-1范围转换为0-255范围
+    r = Math.round(r * 255);
+    g = Math.round(g * 255);
+    b = Math.round(b * 255);
+    return { r, g, b };
+}
+function getHue(hsv, i, light) {
+    let hue;
+    // 根据色相不同，色相转向不同
+    if (Math.round(hsv.h) >= 60 && Math.round(hsv.h) <= 240) {
+        hue = light
+            ? Math.round(hsv.h) - hueStep * i
+            : Math.round(hsv.h) + hueStep * i;
+    }
+    else {
+        hue = light
+            ? Math.round(hsv.h) + hueStep * i
+            : Math.round(hsv.h) - hueStep * i;
+    }
+    if (hue < 0) {
+        hue += 360;
+    }
+    else if (hue >= 360) {
+        hue -= 360;
+    }
+    return hue;
+}
+function getSaturation(hsv, i, light) {
+    // grey color don't change saturation
+    if (hsv.h === 0 && hsv.s === 0) {
+        return hsv.s;
+    }
+    let saturation;
+    if (light) {
+        saturation = hsv.s - saturationStep * i;
+    }
+    else {
+        saturation = hsv.s + saturationStep2 * i;
+    }
+    // 边界值修正
+    if (saturation > 1) {
+        saturation = 1;
+    }
+    if (saturation < 0.06) {
+        saturation = 0.06;
+    }
+    return Number(saturation.toFixed(2));
+}
+function getValue(hsv, i, light) {
+    let value;
+    if (light) {
+        value = hsv.v + brightnessStep1 * i;
+    }
+    else {
+        value = hsv.v - brightnessStep2 * i;
+    }
+    if (value > 1) {
+        value = 1;
+    }
+    return Number(value.toFixed(2));
+}
+/**
+ * 将RGB颜色对象转换为十六进制颜色字符串。
+ * @param rgb - 包含红色(r), 绿色(g), 蓝色(b)成分的对象。
+ * @returns 返回一个表示RGB颜色的十六进制字符串，例如"#FF0000"。
+ */
+export function rgbToHex(rgb) {
+    // 将一个数字转换为两位数的十六进制字符串
+    const toHex = (n) => n.toString(16).padStart(2, "0");
+    // 将RGB颜色值转换为十六进制字符串并大写化
+    return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`.toUpperCase();
+}
+/**
+ * 将颜色转换为 16 进制字符串
+ * @param color - 颜色, 可以 rgb(0,0,0),rgba(0,0,0,0)字符串, 也可以是 rgb、hsv对象
+ * @returns 返回颜色的十六进制字符串，例如"#FF0000"
+ */
+export function toHex(color) {
+    if (typeof color === "string") {
+        if (hexRegex.test(color)) {
+            return color;
+        }
+    }
+    return rgbToHex(toRgb(color));
+}
+/**
+ * 调整给定颜色深[darken]浅[lighten]
+ * @param color - 输入的颜色，可以是任意颜色表示方式
+ * @param level - 调整深浅级别, 可以是小数。默认: 1
+ * @param light - 控制调整的方向。如果为true，[lighten] 变浅，如果为false，[darken] 变深。默认: true
+ *
+ * #### 1. 颜色变浅
+ *
+ * ```
+ * adjust('#4998f4', 3, true)
+ * ```
+ *
+ * @returns 返回调整后颜色的十六进制字符串表示。
+ */
+export function adjust(color, level = 1, light = true) {
+    // 将输入的颜色转换为HSV格式
+    const hsv = toHsv(color);
+    // 根据level和light参数调整颜色的H、S、V值，并转换回十六进制颜色表示
+    return toHex({
+        h: getHue(hsv, level, light),
+        s: getSaturation(hsv, level, light),
+        v: getValue(hsv, level, light),
+    });
+}