ph-utils 0.10.0 → 0.10.2

package/README.md

@@ -1,7 +1,7 @@
-## ph-utils
-
-整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
-
-### 包含如下工具文件
-
-`index` 基础工具类、`date` 跟日期相关的工具类、`file` 文件操作相关工具类[**服务端**]、`server` 服务端工具类、`validator` 数据验证、`dom` 浏览器节点操作相关[**前端**]、`web` 一些只适用于前端相关的工具、`color` 颜色相关工具
+## 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/array.d.ts

@@ -59,14 +59,14 @@ export declare function symmetricDifference<T>(...arrs: T[][]): T[];
  * @param a2
  * @returns
  */
-export declare function isSubsetOf<T>(a1: T[] | Set<T>, a2: T[] | Set<T>): any;
+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>): any;
+export declare function isSupersetOf<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>): boolean;
 /**
  * 返回一个布尔值，指示此集合是否与给定集合没有公共元素。
  *
@@ -76,4 +76,4 @@ export declare function isSupersetOf<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>):
  * @param arr2
  * @returns
  */
-export declare function isDisjointFrom<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>): any;
+export declare function isDisjointFrom<T>(arr1: T[] | Set<T>, arr2: T[] | Set<T>): boolean;

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/dom.d.ts

@@ -2,21 +2,21 @@
  * 根据选择器获取节点
  * @param {string} selector 选择器
  */
-export declare function elem(selector: string | HTMLElement, dom?: HTMLElement): NodeListOf<HTMLElement> | HTMLElement[];
+export declare function elem(selector: string | HTMLElement, dom?: HTMLElement | ShadowRoot | Document): NodeListOf<HTMLElement> | HTMLElement[];
 /**
  * 根据选择器获取 DOM 元素。
  * @param selector - 选择器字符串或 HTMLElement 实例。
  * @param dom - 可选参数，指定在哪个 DOM 节点下查找元素，默认为 document。
  * @returns 返回匹配到的 HTMLElement 实例。
  */
-export declare function $(selector: string | HTMLElement, dom?: HTMLElement): NodeListOf<HTMLElement> | HTMLElement[];
+export declare function $(selector: string | HTMLElement, dom?: HTMLElement | ShadowRoot | Document): NodeListOf<HTMLElement> | HTMLElement[];
 /**
  * 根据选择器获取匹配的第一个 DOM 元素。
  * @param selector - 选择器字符串或直接的 HTMLElement。
  * @param dom - 可选的父级 DOM 元素，默认为当前文档。
  * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 undefined。
  */
-export declare function $one(selector: string | HTMLElement, dom?: HTMLElement): HTMLElement;
+export declare function $one(selector: string | HTMLElement, dom?: HTMLElement | ShadowRoot | Document): HTMLElement;
 /**
  * 为节点添加 class
  * @param {HTMLElement} elem 待添加 class 的节点
@@ -152,10 +152,11 @@ export declare function isMobile(): boolean;
  */
 export declare function formatClass(classObj: (boolean | string | undefined | null)[] | Record<string, boolean | string | undefined | null>): string;
 /**
- * 在下一个动画帧执行回调函数。
- * @param cb - 要在下一个动画帧执行的回调函数。
+ * 将样式对象格式化为 CSS 样式字符串。
+ * @param styleObj - 样式对象，可以是字符串数组或键值对对象。
+ * @returns 格式化后的 CSS 样式字符串。
  */
-export declare function nextTick(cb: () => void): void;
+export declare function formatStyle(styleObj: (string | undefined | null | "")[] | Record<string, string>): string;
 /**
  * 对指定的 HTML 元素应用显示过渡效果。
  * @param target - 要应用过渡效果的 HTML 元素。
@@ -179,9 +180,3 @@ export declare function startTransition(target: HTMLElement, properties: [string
  * @param finish - 过渡结束后可选的回调函数。
  */
 export declare function endTransition(target: HTMLElement, properties: [string, string][], finish?: () => void): void;
-/**
- * 隐藏 Transition 组件
- * @param el Transition 组件或者选择器, 不传则为: l-transition
- * @param remove 是否在隐藏后移除元素, 对应 vue-vIf
- */
-export declare function hideTransition(el?: string | HTMLElement, remove?: boolean): void;

package/lib/dom.js

@@ -317,13 +317,28 @@ export function formatClass(classObj) {
     return classes.trim();
 }
 /**
- * 在下一个动画帧执行回调函数。
- * @param cb - 要在下一个动画帧执行的回调函数。
+ * 将样式对象格式化为 CSS 样式字符串。
+ * @param styleObj - 样式对象，可以是字符串数组或键值对对象。
+ * @returns 格式化后的 CSS 样式字符串。
  */
-export function nextTick(cb) {
-    requestAnimationFrame(() => {
-        cb();
-    });
+export function formatStyle(styleObj) {
+    let styleStr = "";
+    if (Array.isArray(styleObj)) {
+        for (let i = 0, len = styleObj.length; i < len; i++) {
+            const item = styleObj[i];
+            if (item) {
+                styleStr += `${item};`;
+            }
+        }
+    }
+    else {
+        for (const key in styleObj) {
+            if (styleObj[key]) {
+                styleStr += `${key}:${styleObj[key]};`;
+            }
+        }
+    }
+    return styleStr;
 }
 /**
  * 对指定的 HTML 元素应用显示过渡效果。
@@ -351,9 +366,9 @@ export function startTransition(target, properties, duration) {
     if (duration) {
         target.style.setProperty("transition", trans.join(", "));
     }
-    nextTick(() => {
+    queueMicrotask(() => {
         target.style.removeProperty("display");
-        nextTick(() => {
+        queueMicrotask(() => {
             for (let i = 0, len = properties.length; i < len; i++) {
                 const rec = properties[i];
                 target.style.removeProperty(rec[0]);
@@ -383,21 +398,3 @@ export function endTransition(target, properties, finish) {
         }
     }, { once: true });
 }
-/**
- * 隐藏 Transition 组件
- * @param el Transition 组件或者选择器, 不传则为: l-transition
- * @param remove 是否在隐藏后移除元素, 对应 vue-vIf
- */
-export function hideTransition(el, remove = false) {
-    el = el || "l-transition";
-    let $el = el;
-    if (typeof el === "string") {
-        $el = document.querySelector(el);
-    }
-    if ($el) {
-        $el.hide(() => {
-            if (remove)
-                $el.remove();
-        });
-    }
-}

package/lib/server.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type { SpawnOptions } from "node:child_process";
 /**
  * 执行命令

package/lib/theme.js

@@ -19,10 +19,10 @@ export async function initTheme() {
     if ($themeStyle == null) {
         $themeStyle = document.createElement("style");
         $themeStyle.id = "theme-style";
-        $themeStyle.innerHTML = `
-      :root{color-scheme:light dark;}
-      html.light{color-scheme: light;}
-      html.dark {color-scheme: dark;}
+        $themeStyle.innerHTML = `
+      :root{color-scheme:light dark;}
+      html.light{color-scheme: light;}
+      html.dark {color-scheme: dark;}
     `;
         document.head.appendChild($themeStyle);
     }

package/lib/validator.d.ts

@@ -45,19 +45,17 @@ declare class Validator {
     /**
      * 进行数据验证
      * @param data 待验证的数据
+     * @param all 是否全部验证, false - 只要验证错误一个则停止验证
      * @returns
      */
-    validate(data: any): Promise<boolean>;
+    validate(data: any, all?: boolean): Promise<boolean>;
     /**
      * 只验证指定 key 的数据格式
      * @param key   指定待验证的 key
      * @param value 待验证的数据
      * @param data 原始数据，当验证确认密码时需要使用
      */
-    validateKey(key: string, value: any, data?: any): Promise<{
-        key: string;
-        value: any;
-    }>;
+    validateKey(key: string, value: any, data?: any): Promise<boolean>;
     private _validateRule;
     private _parseStringRule;
 }

package/lib/validator.js

@@ -32,10 +32,11 @@ const ruleFns = {
     },
 };
 class ValidateError extends Error {
-    constructor(key, msg) {
-        super(msg);
+    constructor(errors) {
+        super(errors[0].message);
         this.name = "ValidateError";
-        this.key = key;
+        this.key = errors[0].key;
+        this.errors = errors;
     }
 }
 /**
@@ -109,28 +110,31 @@ class Validator {
     /**
      * 进行数据验证
      * @param data 待验证的数据
+     * @param all 是否全部验证, false - 只要验证错误一个则停止验证
      * @returns
      */
-    async validate(data) {
-        let errMsg = "";
-        let errKey = "";
-        for (let key in this.rules) {
-            // eslint-disable-next-line no-prototype-builtins
-            if (this.rules.hasOwnProperty(key)) {
-                errMsg = this._validateRule(this.rules[key], data[key], data);
-                if (errMsg !== "") {
-                    errKey = key;
-                    errMsg = errMsg.replace("%s", key);
-                    break;
+    async validate(data, all = false) {
+        return new Promise((resolve, reject) => {
+            const errors = [];
+            for (let key in this.rules) {
+                // eslint-disable-next-line no-prototype-builtins
+                if (this.rules.hasOwnProperty(key)) {
+                    let errMsg = this._validateRule(this.rules[key], data[key], data);
+                    if (errMsg !== "") {
+                        errMsg = errMsg.replace("%s", key);
+                        errors.push({ message: errMsg, key });
+                        if (all)
+                            break;
+                    }
                 }
             }
-        }
-        if (errMsg === "") {
-            return true;
-        }
-        else {
-            throw new ValidateError(errKey, errMsg);
-        }
+            if (errors.length === 0) {
+                resolve(true);
+            }
+            else {
+                reject(new ValidateError(errors));
+            }
+        });
     }
     /**
      * 只验证指定 key 的数据格式
@@ -139,15 +143,17 @@ class Validator {
      * @param data 原始数据，当验证确认密码时需要使用
      */
     async validateKey(key, value, data) {
-        let keyRules = this.rules[key];
-        let errMsg = this._validateRule(keyRules, value, data);
-        if (errMsg !== "") {
-            errMsg = errMsg.replace("%s", key);
-            throw new ValidateError(key, errMsg);
-        }
-        else {
-            return { key, value };
-        }
+        return new Promise((resolve, reject) => {
+            let keyRules = this.rules[key];
+            let errMsg = this._validateRule(keyRules, value, data);
+            if (errMsg !== "") {
+                errMsg = errMsg.replace("%s", key);
+                reject(new ValidateError([{ key, message: errMsg }]));
+            }
+            else {
+                resolve(true);
+            }
+        });
     }
     _validateRule(rules, value, data) {
         let errMsg = "";

package/package.json

@@ -68,7 +68,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.10.0",
+  "version": "0.10.2",
   "type": "module",
   "repository": {
     "type": "git",