ph-utils 0.4.2 → 0.4.4

package/README.md

@@ -1,11 +1,7 @@
-## ph-utils
-
-整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
-
-### 后端(node server)
-
-包含了一些 node 后端开发(web server) 时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`file` 文件操作相关工具类、`server` 一些只适用于后端的工具(使用了后端的 API 列表)、`validator` 数据验证
-
-### 前端(web)
-
-包含了一些前端网站开发时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`dom` 浏览器节点操作相关、`web` 一些只适用于前端相关的工具、`validator` 数据验证
+## ph-utils
+
+整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
+
+### 包含如下工具文件
+
+`index` 基础工具类、`date` 跟日期相关的工具类、`file` 文件操作相关工具类[**服务端**]、`server` 服务端工具类、`validator` 数据验证、`dom` 浏览器节点操作相关[**前端**]、`web` 一些只适用于前端相关的工具、`color` 颜色相关工具

package/lib/clipboard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 复制数据, 可以从多种类型的数据
+ *    1. 直接复制文本: await copy("待复制的文本")
+ *    2. 复制节点上的 data-copy-text:
+ *      <button data-copy-text="这是待复制的文本">复制</button>
+ *      await copy(e.target) // or await copy("#a") or await copy(document.querySelector('#a'))
+ *    3. 直接复制节点本身数据: await copy('#a')
+ * @param {string | HTMLElement} source 复制源, 从中解析待复制的数据
+ * @returns {Promise<boolean>} 是否复制成功
+ */
+export declare function copy(source: string | HTMLElement): Promise<boolean>;

package/lib/clipboard.js

@@ -0,0 +1,101 @@
+/**
+ * 创建一个临时节点缓存待复制数据
+ * @param {String} value - 待复制文本
+ * @return {HTMLElement}
+ */
+function createFakeElement(value) {
+    const fakeElement = document.createElement("textarea");
+    fakeElement.style.border = "0";
+    fakeElement.style.padding = "0";
+    fakeElement.style.margin = "0";
+    fakeElement.style.position = "absolute";
+    fakeElement.style.left = "-9999px";
+    fakeElement.style.top = "-9999";
+    fakeElement.setAttribute("readonly", "");
+    fakeElement.value = value;
+    return fakeElement;
+}
+/** 通过执行 execCommand 来执行复制 */
+function copyFromCommand(text) {
+    // 添加节点
+    const fakeEl = createFakeElement(text);
+    document.body.append(fakeEl);
+    fakeEl.focus();
+    fakeEl.select();
+    // 执行复制
+    const res = document.execCommand("copy");
+    fakeEl.remove(); // 删除节点
+    return Promise.resolve(res);
+}
+/** 使用 navigator.clipboard 复制 */
+function copyFromClipboard(text) {
+    const theClipboard = navigator.clipboard;
+    if (theClipboard != null) {
+        return theClipboard
+            .writeText(text)
+            .then(() => {
+            Promise.resolve(true);
+        })
+            .catch(() => Promise.resolve(false));
+    }
+    return Promise.resolve(false);
+}
+/** 解析待复制的文本 */
+function parseCopyText(source) {
+    let copyText = null; // 待复制文本
+    let sourceEl = null;
+    // 获取待复制数据
+    if (typeof source === "string") {
+        // 从节点拿数据
+        if (source.startsWith("#") || source.startsWith(".")) {
+            sourceEl = document.querySelector(source);
+            if (sourceEl == null) {
+                copyText = source;
+            }
+        }
+        else {
+            copyText = source;
+        }
+    }
+    if (source instanceof HTMLElement) {
+        sourceEl = source;
+    }
+    // 从节点获取待复制数据
+    if (sourceEl != null) {
+        if (sourceEl.hasAttribute("data-copy-text")) {
+            copyText = sourceEl.getAttribute("data-copy-text");
+        }
+        else {
+            const tagName = sourceEl.tagName;
+            if (tagName === "INPUT" || tagName === "TEXTAREA") {
+                copyText = sourceEl.value;
+            }
+            else {
+                copyText = sourceEl.textContent;
+            }
+        }
+    }
+    return copyText;
+}
+/**
+ * 复制数据, 可以从多种类型的数据
+ *    1. 直接复制文本: await copy("待复制的文本")
+ *    2. 复制节点上的 data-copy-text:
+ *      <button data-copy-text="这是待复制的文本">复制</button>
+ *      await copy(e.target) // or await copy("#a") or await copy(document.querySelector('#a'))
+ *    3. 直接复制节点本身数据: await copy('#a')
+ * @param {string | HTMLElement} source 复制源, 从中解析待复制的数据
+ * @returns {Promise<boolean>} 是否复制成功
+ */
+export async function copy(source) {
+    // 待复制文本
+    const copyText = parseCopyText(source);
+    if (copyText == null) {
+        return Promise.resolve(false);
+    }
+    const v = await copyFromClipboard(copyText);
+    if (v === false) {
+        return copyFromCommand(copyText);
+    }
+    return Promise.resolve(true);
+}

package/lib/color.d.ts

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

package/lib/color.js

@@ -0,0 +1,292 @@
+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;
+    }
+    // 第一格的 s 限制在 0.06-0.1 之间
+    if (light && saturation > 0.1) {
+        saturation = 0.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));
+    }
+    return rgbToHex(toRgb(color));
+}
+/**
+ * 调整给定颜色深[darken]浅[lighten]
+ * @param color - 输入的颜色，可以是任意颜色表示方式
+ * @param level - 调整深浅级别, 可以是小数
+ * @param light - 控制调整的方向。如果为true，[lighten] 变浅，如果为false，[darken] 变深。
+ * @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),
+    });
+}

package/lib/index.d.ts

@@ -81,9 +81,20 @@ export declare class BaseError extends Error {
  */
 export declare function formatMoney(number: number): string;
 /**
- * 将风格由大写风格转换为下划线风格: IconFont -> icon_font
- * @param name 命名, 例如: IconFont
+ * 将风格由大写风格转换为下划线风格: HelloWorld -> hello-world
+ * @param name 命名, 例如: HelloWorld
  * @param connector 连接符, 默认为: _
  */
 export declare function snakeCaseStyle(name: string, connector?: string): string;
+/**
+ * 对数字进行四舍五入处理
+ * @param num 需要进行四舍五入的数字
+ * @param precision 精度，默认为2，即保留小数点后两位
+ * @param roundType 舍入类型，默认为0，提供三种取值:
+ *        0: 标准四舍五入
+ *        1: 向上取整
+ *        2: 向下取整
+ * @returns 返回经过指定方式舍入后的数字
+ */
+export declare function round(num: number, precision?: number, roundType?: 0 | 1 | 2): number;
 export {};

package/lib/index.js

@@ -143,13 +143,38 @@ export function formatMoney(number) {
     }
 }
 /**
- * 将风格由大写风格转换为下划线风格: IconFont -> icon_font
- * @param name 命名, 例如: IconFont
+ * 将风格由大写风格转换为下划线风格: HelloWorld -> hello-world
+ * @param name 命名, 例如: HelloWorld
  * @param connector 连接符, 默认为: _
  */
-export function snakeCaseStyle(name, connector = "_") {
-    const snakeName = name.replace(/([A-Z])/g, (match) => {
-        return `${connector}${match.toLowerCase()}`;
-    });
-    return snakeName[0] === connector ? snakeName.substring(1) : snakeName;
+export function snakeCaseStyle(name, connector = "-") {
+    return name.replace(/([A-Z])/g, (match, p1, offset) => (offset > 0 ? connector : "") + match.toLowerCase());
+}
+/**
+ * 对数字进行四舍五入处理
+ * @param num 需要进行四舍五入的数字
+ * @param precision 精度，默认为2，即保留小数点后两位
+ * @param roundType 舍入类型，默认为0，提供三种取值:
+ *        0: 标准四舍五入
+ *        1: 向上取整
+ *        2: 向下取整
+ * @returns 返回经过指定方式舍入后的数字
+ */
+export function round(num, precision = 2, roundType = 0) {
+    // 计算精度因子，用于后续四舍五入计算
+    const factor = Math.pow(10, precision);
+    switch (roundType) {
+        case 0:
+            // 标准四舍五入
+            return Math.round(num * factor) / factor;
+        case 1:
+            // 向上取整
+            return Math.ceil(num * factor) / factor;
+        case 2:
+            // 向下取整
+            return Math.floor(num * factor) / factor;
+        default:
+            // 如果传入的roundType不是预期的值，则直接返回原始数字
+            return num;
+    }
 }

package/lib/storage.js

@@ -12,7 +12,7 @@ export function set(key, value, option) {
     const opts = {
         expire: -1,
         storage: "session",
-        ...(option || {}),
+        ...option,
     };
     const saveData = JSON.stringify({
         value,

package/package.json

@@ -46,9 +46,13 @@
       "types": "./lib/storage.d.ts",
       "import": "./lib/storage.js"
     },
+    "./color": {
+      "types": "./lib/color.d.ts",
+      "import": "./lib/color.js"
+    },
     "./*": "./lib/*"
   },
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "module",
   "repository": {
     "type": "git",
@@ -56,14 +60,14 @@
     "directory": "packages/utils"
   },
   "license": "MIT",
-  "author": "DvShu <1456207945@qq.com>",
+  "author": "Tenny <tenny.shu@foxmail.com>",
   "bugs": {
     "url": "https://gitee.com/towardly/ph/issues"
   },
   "homepage": "https://gitee.com/towardly/ph/tree/master/packages/utils",
   "devDependencies": {
-    "@types/node": "^20.9.0",
-    "typescript": "^5.2.2"
+    "@types/node": "^20.12.12",
+    "typescript": "^5.4.5"
   },
   "files": [
     "lib"
@@ -76,6 +80,9 @@
     "dom",
     "file"
   ],
+  "dependencies": {
+    "@ctrl/tinycolor": "^4.1.0"
+  },
   "scripts": {
     "build": "node scripts/build.js"
   }