ph-utils 0.9.14 → 0.10.0

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

@@ -3,6 +3,20 @@
  * @param {string} selector 选择器
  */
 export declare function elem(selector: string | HTMLElement, dom?: HTMLElement): NodeListOf<HTMLElement> | HTMLElement[];
+/**
+ * 根据选择器获取 DOM 元素。
+ * @param selector - 选择器字符串或 HTMLElement 实例。
+ * @param dom - 可选参数，指定在哪个 DOM 节点下查找元素，默认为 document。
+ * @returns 返回匹配到的 HTMLElement 实例。
+ */
+export declare function $(selector: string | HTMLElement, dom?: HTMLElement): NodeListOf<HTMLElement> | HTMLElement[];
+/**
+ * 根据选择器获取匹配的第一个 DOM 元素。
+ * @param selector - 选择器字符串或直接的 HTMLElement。
+ * @param dom - 可选的父级 DOM 元素，默认为当前文档。
+ * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 undefined。
+ */
+export declare function $one(selector: string | HTMLElement, dom?: HTMLElement): HTMLElement;
 /**
  * 为节点添加 class
  * @param {HTMLElement} elem 待添加 class 的节点
@@ -46,6 +60,13 @@ export declare function on<T extends Event>(element: HTMLElement, listener: stri
     eventFlag?: string;
     eventStop?: boolean;
 }): void;
+/**
+ * 移除指定元素的事件监听器。
+ * @param el - 要移除监听器的 HTML 元素。
+ * @param listener - 事件名称。
+ * @param fn - 要移除的事件监听器函数。
+ */
+export declare function off(el: HTMLElement, listener: string, fn: EventListener): void;
 /**
  * 设置或获取节点的 innerHTML 属性
  * @param element
@@ -74,6 +95,20 @@ export declare function iterate(elems: NodeList | HTMLElement[], fn: (el: HTMLEl
  * @returns
  */
 export declare function attr(elem: HTMLElement, key: string, value?: string): string | null | undefined;
+/**
+ * 获取属性值
+ * @param key 属性名称
+ */
+export declare function getAttr(el: HTMLElement, key: string): string;
+/**
+ * 获取属性值，同时将值转换为默认值的类型，如果未赋值，则返回默认值；
+ * @param key 属性名称
+ * @param defaultValue 默认值
+ */
+export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: string): string;
+export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: number): number;
+export declare function getAttr(el: HTMLElement, filepath: string, defaultValue: boolean): boolean;
+export declare function getAttr<T extends Record<string, string | number | boolean>>(el: HTMLElement, filepath: string, defaultValue: T): T;
 /**
  * 获取指定节点的父节点
  * @param el
@@ -108,3 +143,45 @@ export declare function isVisible(el: HTMLElement, parent?: HTMLElement | null |
  * @returns {boolean} 如果设备是移动设备，则返回true；否则返回false。
  */
 export declare function isMobile(): boolean;
+/**
+ * 格式化类名，支持数组和对象两种形式。
+ * - 数组形式：数组中的每个元素代表一个类名，非空元素将被添加到结果字符串中。
+ * - 对象形式：对象的键代表类名，值为真（非空、非undefined、非null）时，键将被添加到结果字符串中。
+ * @param classObj - 类名对象或数组
+ * @returns 格式化后的类名字符串
+ */
+export declare function formatClass(classObj: (boolean | string | undefined | null)[] | Record<string, boolean | string | undefined | null>): string;
+/**
+ * 在下一个动画帧执行回调函数。
+ * @param cb - 要在下一个动画帧执行的回调函数。
+ */
+export declare function nextTick(cb: () => void): void;
+/**
+ * 对指定的 HTML 元素应用显示过渡效果。
+ * @param target - 要应用过渡效果的 HTML 元素。
+ * @param properties - 包含要改变的 CSS 属性及其目标值的数组。eg. [['opacity', '0.5']]
+ * @param duration - 过渡效果的持续时间，默认为 "0.3s"。
+ * 该方法首先将元素的 display 属性设置为 "none"，然后设置过渡属性，
+ * 在下一个 DOM 更新周期后显示元素并移除设置的属性，从而实现过渡效果。
+ *
+ * ```
+ * startTransition($msg, [
+    ["opacity", "0"],
+    ["transform", "translate3d(-50%, -100%, 0)"],
+  ]);
+ * ```
+ */
+export declare function startTransition(target: HTMLElement, properties: [string, string][], duration?: string): void;
+/**
+ * 结束元素的过渡效果，并在过渡结束后隐藏元素。
+ * @param target - 要操作的 HTML 元素。
+ * @param properties - 包含要设置的 CSS 属性和值的数组。
+ * @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

@@ -16,6 +16,24 @@ export function elem(selector, dom) {
         return [selector];
     }
 }
+/**
+ * 根据选择器获取 DOM 元素。
+ * @param selector - 选择器字符串或 HTMLElement 实例。
+ * @param dom - 可选参数，指定在哪个 DOM 节点下查找元素，默认为 document。
+ * @returns 返回匹配到的 HTMLElement 实例。
+ */
+export function $(selector, dom) {
+    return elem(selector, dom);
+}
+/**
+ * 根据选择器获取匹配的第一个 DOM 元素。
+ * @param selector - 选择器字符串或直接的 HTMLElement。
+ * @param dom - 可选的父级 DOM 元素，默认为当前文档。
+ * @returns 返回匹配的第一个 HTMLElement，如果没有找到则返回 undefined。
+ */
+export function $one(selector, dom) {
+    return elem(selector, dom)[0];
+}
 /**
  * 为节点添加 class
  * @param {HTMLElement} elem 待添加 class 的节点
@@ -98,6 +116,15 @@ export function on(element, listener, fn, once = false) {
         element.addEventListener(listener, fn, eventExtra);
     }
 }
+/**
+ * 移除指定元素的事件监听器。
+ * @param el - 要移除监听器的 HTML 元素。
+ * @param listener - 事件名称。
+ * @param fn - 要移除的事件监听器函数。
+ */
+export function off(el, listener, fn) {
+    el.removeEventListener(listener, fn);
+}
 /**
  * 设置或获取节点的 innerHTML 属性
  * @param element
@@ -156,6 +183,32 @@ export function attr(elem, key, value) {
         return elem.getAttribute("data-" + key);
     }
 }
+export function getAttr(el, key, defaultValue) {
+    const value = el.getAttribute(key);
+    if (defaultValue == null)
+        return value;
+    const valueType = typeof defaultValue;
+    if (value == null)
+        return defaultValue;
+    // 类型转换
+    if (valueType === "bigint" || valueType === "number") {
+        if (value === "")
+            return defaultValue;
+        return Number(value);
+    }
+    if (valueType === "boolean") {
+        if (value === "" || value === "1" || value === "true" || value === key) {
+            return true;
+        }
+        return false;
+    }
+    if (valueType === "object") {
+        if (value === "")
+            return defaultValue;
+        return JSON.parse(value);
+    }
+    return value;
+}
 /**
  * 获取指定节点的父节点
  * @param el
@@ -237,3 +290,114 @@ export function isMobile() {
     // 如果是移动设备或屏幕尺寸符合移动设备特征，则返回true
     return isMobile || isScreenMobile;
 }
+/**
+ * 格式化类名，支持数组和对象两种形式。
+ * - 数组形式：数组中的每个元素代表一个类名，非空元素将被添加到结果字符串中。
+ * - 对象形式：对象的键代表类名，值为真（非空、非undefined、非null）时，键将被添加到结果字符串中。
+ * @param classObj - 类名对象或数组
+ * @returns 格式化后的类名字符串
+ */
+export function formatClass(classObj) {
+    let classes = "";
+    if (Array.isArray(classObj)) {
+        for (let i = 0, len = classObj.length; i < len; i++) {
+            const item = classObj[i];
+            if (item) {
+                classes += `${item} `;
+            }
+        }
+    }
+    else {
+        for (const key in classObj) {
+            if (classObj[key]) {
+                classes += `${key} `;
+            }
+        }
+    }
+    return classes.trim();
+}
+/**
+ * 在下一个动画帧执行回调函数。
+ * @param cb - 要在下一个动画帧执行的回调函数。
+ */
+export function nextTick(cb) {
+    requestAnimationFrame(() => {
+        cb();
+    });
+}
+/**
+ * 对指定的 HTML 元素应用显示过渡效果。
+ * @param target - 要应用过渡效果的 HTML 元素。
+ * @param properties - 包含要改变的 CSS 属性及其目标值的数组。eg. [['opacity', '0.5']]
+ * @param duration - 过渡效果的持续时间，默认为 "0.3s"。
+ * 该方法首先将元素的 display 属性设置为 "none"，然后设置过渡属性，
+ * 在下一个 DOM 更新周期后显示元素并移除设置的属性，从而实现过渡效果。
+ *
+ * ```
+ * startTransition($msg, [
+    ["opacity", "0"],
+    ["transform", "translate3d(-50%, -100%, 0)"],
+  ]);
+ * ```
+ */
+export function startTransition(target, properties, duration) {
+    target.style.setProperty("display", "none");
+    const trans = [];
+    for (let i = 0, len = properties.length; i < len; i++) {
+        const rec = properties[i];
+        target.style.setProperty(rec[0], rec[1]);
+        trans.push(`${rec[0]} ${duration}`);
+    }
+    if (duration) {
+        target.style.setProperty("transition", trans.join(", "));
+    }
+    nextTick(() => {
+        target.style.removeProperty("display");
+        nextTick(() => {
+            for (let i = 0, len = properties.length; i < len; i++) {
+                const rec = properties[i];
+                target.style.removeProperty(rec[0]);
+            }
+        });
+    });
+}
+/**
+ * 结束元素的过渡效果，并在过渡结束后隐藏元素。
+ * @param target - 要操作的 HTML 元素。
+ * @param properties - 包含要设置的 CSS 属性和值的数组。
+ * @param finish - 过渡结束后可选的回调函数。
+ */
+export function endTransition(target, properties, finish) {
+    for (let i = 0, len = properties.length; i < len; i++) {
+        const rec = properties[i];
+        target.style.setProperty(rec[0], rec[1]);
+    }
+    target.addEventListener("transitionend", () => {
+        target.style.display = "none";
+        for (let i = 0, len = properties.length; i < len; i++) {
+            const rec = properties[i];
+            target.style.removeProperty(rec[0]);
+        }
+        if (finish != null) {
+            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

@@ -5,9 +5,18 @@ import type { SpawnOptions } from "node:child_process";
  * @param command 待执行的命令
  * @param args    命令参数
  */
-export declare function exec(command: string, args?: string[]): Promise<string>;
-export declare function exec(command: string, options?: SpawnOptions): Promise<string>;
-export declare function exec(command: string, args?: string[], options?: SpawnOptions): Promise<string>;
+export declare function exec(command: string, args?: string[]): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function exec(command: string, options?: SpawnOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function exec(command: string, args?: string[], options?: SpawnOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
 /**
  * 解析环境变量;
  * 同时读取多个环境变量文件: .env, .env.local, .env.[development|test|production];

package/lib/server.js

@@ -1,48 +1,32 @@
 import { execFile } from "node:child_process";
-import { parseEnv, parseArgs } from "node:util";
+import { parseEnv, parseArgs, promisify } from "node:util";
 import { readFileSync } from "node:fs";
+const execFilePromise = promisify(execFile);
 /**
  * 执行命令
  * @param cmd 执行的命令
  * @returns
  */
 export function exec(command, ...params) {
-  let argvs = [];
-  const commandItems = command.split(" ");
-  const cmd = commandItems.shift();
-  if (commandItems.length > 0) {
-    argvs = commandItems;
-  }
-  let opts = {};
-  if (params[0] != null) {
-    if (params[0] instanceof Array) {
-      argvs.push(...params[0]);
-      if (params[1] != null) {
-        opts = params[1];
-      }
-    } else {
-      opts = params[0];
+    let argvs = [];
+    const commandItems = command.split(" ");
+    const cmd = commandItems.shift();
+    if (commandItems.length > 0) {
+        argvs = commandItems;
     }
-  }
-  return new Promise((resolve, reject) => {
-    execFile(cmd, argvs, opts || {}, (err, stdout, stderr) => {
-      if (err) {
-        reject(err);
-      } else {
-        let msg = stdout || stderr;
-        if (
-          stderr != null &&
-          (stderr.includes("error") || stderr.includes("Error"))
-        ) {
-          const error = new Error(stderr);
-          error.type = "StdErr";
-          reject(error);
-        } else {
-          resolve(msg);
+    let opts = { shell: true };
+    if (params[0] != null) {
+        if (params[0] instanceof Array) {
+            argvs.push(...params[0]);
+            if (params[1] != null) {
+                opts = params[1];
+            }
         }
-      }
-    });
-  });
+        else {
+            opts = params[0];
+        }
+    }
+    return execFilePromise(cmd, argvs, opts);
 }
 /**
  * 解析环境变量;
@@ -64,37 +48,39 @@ export function exec(command, ...params) {
  * @returns
  */
 export function parseEnvs() {
-  // development, test, production
-  const files = [".env", ".env.local"];
-  let nodeEnv = process.env.NODE_ENV;
-  const { values } = parseArgs({
-    options: {
-      NODE_ENV: {
-        type: "string",
-        short: "n",
-      },
-    },
-    strict: false,
-  });
-  if (values.NODE_ENV != null && typeof values.NODE_ENV === "string") {
-    nodeEnv = values.NODE_ENV;
-  }
-  if (nodeEnv == null) {
-    nodeEnv = "production";
-  }
-  process.env.NODE_ENV = nodeEnv;
-  files.push(`.env.${nodeEnv}`);
-  let envParsed = {};
-  for (let i = 0, len = files.length; i < len; i++) {
-    const file = files[i];
-    try {
-      const envContent = readFileSync(file, { encoding: "utf-8" });
-      const envValue = parseEnv(envContent);
-      envParsed = { ...envParsed, ...envValue };
-    } catch (err) {}
-  }
-  for (const key in envParsed) {
-    process.env[key] = envParsed[key];
-  }
-  return envParsed;
+    // development, test, production
+    const files = [".env", ".env.local"];
+    let nodeEnv = process.env.NODE_ENV;
+    const { values } = parseArgs({
+        options: {
+            NODE_ENV: {
+                type: "string",
+                short: "n",
+            },
+        },
+        strict: false,
+    });
+    if (values.NODE_ENV != null && typeof values.NODE_ENV === "string") {
+        nodeEnv = values.NODE_ENV;
+    }
+    if (nodeEnv == null) {
+        nodeEnv = "production";
+    }
+    process.env.NODE_ENV = nodeEnv;
+    files.push(`.env.${nodeEnv}`);
+    let envParsed = {};
+    for (let i = 0, len = files.length; i < len; i++) {
+        const file = files[i];
+        try {
+            const envContent = readFileSync(file, { encoding: "utf-8" });
+            const envValue = parseEnv(envContent);
+            envParsed = { ...envParsed, ...envValue };
+            // eslint-disable-next-line
+        }
+        catch (err) { }
+    }
+    for (const key in envParsed) {
+        process.env[key] = envParsed[key];
+    }
+    return envParsed;
 }

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/package.json

@@ -68,7 +68,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.9.14",
+  "version": "0.10.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -82,7 +82,7 @@
   },
   "homepage": "https://gitee.com/towardly/ph/tree/master/packages/utils",
   "devDependencies": {
-    "@types/node": "^22.7.9",
+    "@types/node": "^22.8.2",
     "typescript": "^5.6.3"
   },
   "files": [

package/lib/clipboard.d.ts

@@ -1,11 +0,0 @@
-/**
- * 复制数据, 可以从多种类型的数据
- *    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

@@ -1,101 +0,0 @@
-/**
- * 创建一个临时节点缓存待复制数据
- * @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);
-}