ph-utils 0.8.3 → 0.9.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/array.js

@@ -6,9 +6,10 @@
  * @returns
  */
 export function order(arr, order = "asc", orderKey = null) {
-    const collator = new Intl.Collator();
+    const collator = new Intl.Collator(undefined, { numeric: true });
     return arr.sort((a, b) => {
-        let aValue = a, bValue = b;
+        let aValue = a;
+        let bValue = b;
         if (typeof a === "object" && orderKey != null) {
             // @ts-ignore
             aValue = a[orderKey];

package/lib/date.js

@@ -116,8 +116,6 @@ export function format(date, pattern = "yyyy-mm-dd HH:MM:ss") {
 export function parse(date) {
     if (date == null)
         return new Date();
-    if (date instanceof Date)
-        return date;
     if (typeof date === "string" && !/Z$/i.test(date)) {
         const d = date.match(REGEX_PARSE);
         if (d) {
@@ -127,7 +125,7 @@ export function parse(date) {
     if (typeof date === "number") {
         return new Date(date <= 9999999999 ? date * 1000 : date);
     }
-    return new Date();
+    return new Date(date);
 }
 /**
  * 设置日期的开始或者结束的点

package/lib/index.d.ts

@@ -29,37 +29,55 @@ export declare function isNumeric(str: string, numericParam?: {
  */
 export declare function isBoolean(str: string): boolean;
 /** 生成随机数的选项 */
-interface RandomConfig {
+interface RandomStringOption {
     /** 生成指定长度的随机字符串 */
-    length?: number;
+    length: number;
     /** 是否包含英文字母, 默认为: true */
     hasLetter?: boolean;
     /** 生成纯数字的随机数时, 首位是否允许为 0, 默认为: true */
     firstIsZero?: boolean;
+}
+interface RangeRandomOption {
     /** 配合 max 生成 [min~max] 之间的随机数 */
-    min?: number;
+    min: number;
     /** 配合 min 生成 [min~max] 之间的随机数 */
-    max?: number;
+    max: number;
     /** 生成的随机数，是否包含 max, 默认: false */
     hasEnd?: boolean;
     /** 生成的随机数是否是整数, 默认: true */
     isInteger?: boolean;
 }
 /**
- * 生成随机数
- *  1. 生成指定长度的随机数
- *  2. 生成介于 [min, max] 之间的随机数
- * @param opts 生成随机数的配置
+ * 生成指定长度的随机数
+ *
+ * @param len - 生成的随机数长度
  *
  * @example <caption>1. 生成指定长度的随机字符串</caption>
  * random(1); // 长度为 1 的随机字符串
+ */
+export declare function random(len: number): string;
+/**
+ * 生成介于 [min, max] 之间的随机数
  *
- * @example <caption>2. 生成纯数字且不能为0长度为1的随机字符</caption>
- * random({ length: 1, hasLetter: false, firstIsZero: false })
+ * @param option 配置项
+ * @param option.min 生成介于 [min, max] 之间的随机数
+ * @param option.max 生成介于 [min, max] 之间的随机数
+ * @param option.hasEnd 生成的随机数，是否包含 max, 默认: false
+ * @param option.isInteger 生成的随机数是否是整数, 默认: true
+ */
+export declare function random(option: RangeRandomOption): number;
+/**
+ * 生成指定长度随机数
  *
- * @returns
+ * @param option 配置项
+ * @param option.length 生成的随机数长度
+ * @param option.hasLetter 是否包含英文字母, 默认为: true
+ * @param option.firstIsZero 生成纯数字的随机数时, 首位是否允许为 0, 默认为: true
+ *
+ * @example <caption>2. 生成纯数字且首位不能为0长度为1的随机字符</caption>
+ * random({ length: 1, hasLetter: false, firstIsZero: false })
  */
-export declare function random(opts: number | RandomConfig): string | number;
+export declare function random(option: RandomStringOption): string;
 /**
  * 带有错误名称标记的错误类型
  */

package/lib/index.js

@@ -53,20 +53,6 @@ export function isNumeric(str, numericParam) {
 export function isBoolean(str) {
     return ["true", "false"].indexOf(str) >= 0;
 }
-/**
- * 生成随机数
- *  1. 生成指定长度的随机数
- *  2. 生成介于 [min, max] 之间的随机数
- * @param opts 生成随机数的配置
- *
- * @example <caption>1. 生成指定长度的随机字符串</caption>
- * random(1); // 长度为 1 的随机字符串
- *
- * @example <caption>2. 生成纯数字且不能为0长度为1的随机字符</caption>
- * random({ length: 1, hasLetter: false, firstIsZero: false })
- *
- * @returns
- */
 export function random(opts) {
     if (typeof opts === "object" && opts.min != null && opts.max != null) {
         const randomNum = Math.random();
@@ -79,13 +65,13 @@ export function random(opts) {
         if (typeof opts === "object" && opts.length == null) {
             throw new Error("random_length_cannot_null");
         }
-        const len = typeof opts === "object" ? opts.length : opts;
+        let len = typeof opts === "object" ? opts.length : opts;
         /* 生成指定长度的随机数 */
         let chars = RANDOM_CHARS;
         if (typeof opts === "object" && opts.hasLetter === false) {
             chars = NUMBER_RANDOM_CHARTS;
         }
-        const resRandom = Array.from({ length: len }, () => chars.charAt(random({ min: 0, max: 9, hasEnd: true }))).join("");
+        const resRandom = Array.from({ length: len }, () => chars.charAt(random({ min: 0, max: chars.length - 1, hasEnd: true }))).join("");
         if (typeof opts === "object" &&
             opts.firstIsZero === false &&
             resRandom.indexOf("0") === 0) {

package/lib/storage.d.ts

@@ -11,8 +11,8 @@ interface StorageSetOption {
  * 存储值到 Storage 中
  * @param key 设置的 key
  * @param value 设置的值
- * @param storage session 或 local
- * @param expire 数据有效期, 单位秒, 默认: -1 - 永久存储
+ * @param [option.storage] session 或 local, 默认: session
+ * @param [option.expire] 数据有效期, 单位秒, 默认: -1 - 永久存储
  */
 export declare function set(key: string, value: any, option?: StorageSetOption): void;
 /**
@@ -37,8 +37,8 @@ interface StorageQueryOption {
  * 从 Storage 中取出数据
  * @param key 保存时的 key
  * @param defaultValue 没有数据时的默认值
- * @param delete 是否在取出后，删除数据，默认：false - 取出后删除数据
- * @param storage 使用的 Storage ，可以是 localStorage、sessionStorage
+ * @param [option.delete] 是否在取出后，删除数据，默认：false - 取出后删除数据
+ * @param [option.storage] 使用的 Storage ，可以是 localStorage、sessionStorage, 默认: localStorage、sessionStorage
  * @returns Storage 中 key 对应的数据
  */
 export declare function get<T>(key: string, defaultValue?: T, option?: StorageQueryOption): T;

package/lib/storage.js

@@ -5,8 +5,8 @@ function getStorage(storage = "session") {
  * 存储值到 Storage 中
  * @param key 设置的 key
  * @param value 设置的值
- * @param storage session 或 local
- * @param expire 数据有效期, 单位秒, 默认: -1 - 永久存储
+ * @param [option.storage] session 或 local, 默认: session
+ * @param [option.expire] 数据有效期, 单位秒, 默认: -1 - 永久存储
  */
 export function set(key, value, option) {
     const opts = {
@@ -40,8 +40,8 @@ export function remove(key, storage) {
  * 从 Storage 中取出数据
  * @param key 保存时的 key
  * @param defaultValue 没有数据时的默认值
- * @param delete 是否在取出后，删除数据，默认：false - 取出后删除数据
- * @param storage 使用的 Storage ，可以是 localStorage、sessionStorage
+ * @param [option.delete] 是否在取出后，删除数据，默认：false - 取出后删除数据
+ * @param [option.storage] 使用的 Storage ，可以是 localStorage、sessionStorage, 默认: localStorage、sessionStorage
  * @returns Storage 中 key 对应的数据
  */
 export function get(key, defaultValue, option) {

package/lib/theme.d.ts

@@ -0,0 +1,42 @@
+/** 获取当前系统的主题 */
+export declare function getSystemTheme(): "dark" | "light";
+/**
+ * 初始化主题, 让网页能够适应系统主题, 同时根据缓存的主题切换主题
+ * @returns 当前应用的主题
+ */
+export declare function initTheme(): Promise<"dark" | "light">;
+/**
+ * 切换主题, 通常用于预览
+ * @param theme 切换的主题
+ * @returns 切换后的主题
+ */
+export declare function toggleTheme(theme?: "light" | "dark" | "auto"): Promise<"dark" | "light">;
+/** 获取当前主题 */
+export declare function getTheme(): string;
+/**
+ * 应用主题
+ * @param theme 待应用的主题
+ * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
+ * @returns 应用的主题
+ */
+export declare function applyTheme(theme?: "light" | "dark" | "auto", cache?: boolean): Promise<"dark" | "light">;
+/** 获取当前主题色 */
+export declare function getColorTheme(defaultValue?: string): string | undefined;
+/**
+ * 初始化主题色, 让网页能够适应系统主题色, 同时根据缓存的主题色切换主题色
+ * @returns 当前应用的主题色
+ */
+export declare function initColorTheme(): Promise<string> | null;
+/**
+ * 切换主题色, 通常用于预览
+ * @param color 待切换的主题色
+ * @returns 切换后的主题色
+ */
+export declare function toggleColorTheme(color: string): Promise<string>;
+/**
+ * 应用主题色
+ * @param color 主题色
+ * @param cache 是否缓存主题色, 让应用下一次启动的时候, 可以应用主题色, 默认: true
+ * @returns 切换后的主题色
+ */
+export declare function applyColorTheme(color: string, cache?: boolean): Promise<string>;

package/lib/theme.js

@@ -0,0 +1,136 @@
+import { adjust } from "./color.js";
+/** 获取当前系统的主题 */
+export function getSystemTheme() {
+    if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
+        return "dark";
+    }
+    return "light";
+}
+/**
+ * 初始化主题, 让网页能够适应系统主题, 同时根据缓存的主题切换主题
+ * @returns 当前应用的主题
+ */
+export async function initTheme() {
+    // 让网页能够适应系统主题
+    let $themeStyle = document.getElementById("theme-style");
+    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;}
+    `;
+        document.head.appendChild($themeStyle);
+    }
+    // 获取已经应用的主题设置
+    const cacheTheme = localStorage.getItem("web-theme-appearance");
+    return toggleTheme(cacheTheme);
+}
+/**
+ * 切换主题, 通常用于预览
+ * @param theme 切换的主题
+ * @returns 切换后的主题
+ */
+export async function toggleTheme(theme) {
+    if (theme !== "light" && theme !== "dark") {
+        theme = getSystemTheme();
+    }
+    const classList = document.documentElement.classList;
+    if (theme === "light") {
+        classList.add("light");
+        classList.remove("dark");
+    }
+    else if (theme === "dark") {
+        classList.add("dark");
+        classList.remove("light");
+    }
+    return theme;
+}
+/** 获取当前主题 */
+export function getTheme() {
+    // 1. 从根节点获取
+    let theme = document.documentElement.className.match(/light|dark/);
+    if (theme != null) {
+        theme = theme[0];
+    }
+    if (theme == null) {
+        theme = localStorage.getItem("web-theme-appearance");
+    }
+    if (theme == null) {
+        theme = getSystemTheme();
+    }
+    return theme;
+}
+/**
+ * 应用主题
+ * @param theme 待应用的主题
+ * @param cache 是否缓存应用的主题, 让应用下一次启动的时候, 可以应用主题, 默认: true
+ * @returns 应用的主题
+ */
+export async function applyTheme(theme, cache = true) {
+    if (cache === true) {
+        localStorage.setItem("web-theme-appearance", theme == null ? "auto" : theme);
+    }
+    return toggleTheme(theme);
+}
+/** 获取当前主题色 */
+export function getColorTheme(defaultValue) {
+    const root = document.documentElement;
+    const match = root.className.match(/color-([0-9a-fA-F]{6})/);
+    if (match == null) {
+        // 获取 --nt-primary-color 的值
+        let color = getComputedStyle(root).getPropertyValue("--nt-primary-color");
+        if (color === "") {
+            color = localStorage.getItem("web-theme-color");
+        }
+        return color ? color : defaultValue;
+    }
+    return `#${match[1]}`;
+}
+/**
+ * 初始化主题色, 让网页能够适应系统主题色, 同时根据缓存的主题色切换主题色
+ * @returns 当前应用的主题色
+ */
+export function initColorTheme() {
+    // 获取缓存主题色
+    const color = localStorage.getItem("web-theme-color");
+    if (color != null) {
+        return toggleColorTheme(color);
+    }
+    return color;
+}
+/**
+ * 切换主题色, 通常用于预览
+ * @param color 待切换的主题色
+ * @returns 切换后的主题色
+ */
+export async function toggleColorTheme(color) {
+    const vars = [
+        `--nt-primary-color: ${color};`,
+        `--nt-primary-color-dark1: ${adjust(color, 1, false)};`,
+    ];
+    for (let i = 1; i <= 5; i++) {
+        vars.push(`--nt-primary-color-light${i}: ${adjust(color, i)};`);
+    }
+    let $style = document.getElementById("color-theme-style");
+    if ($style == null) {
+        $style = document.createElement("style");
+        $style.id = "color-theme-style";
+        document.head.appendChild($style);
+    }
+    $style.innerHTML = `:root{${vars.join("")}}`;
+    return color;
+}
+/**
+ * 应用主题色
+ * @param color 主题色
+ * @param cache 是否缓存主题色, 让应用下一次启动的时候, 可以应用主题色, 默认: true
+ * @returns 切换后的主题色
+ */
+export function applyColorTheme(color, cache = true) {
+    if (cache === true) {
+        localStorage.setItem("web-theme-color", color.substring(1));
+    }
+    return toggleColorTheme(color);
+}

package/package.json

@@ -58,9 +58,13 @@
       "types": "./lib/array.d.ts",
       "import": "./lib/array.js"
     },
+    "./theme": {
+      "types": "./lib/theme.d.ts",
+      "import": "./lib/theme.js"
+    },
     "./*": "./lib/*"
   },
-  "version": "0.8.3",
+  "version": "0.9.0",
   "type": "module",
   "repository": {
     "type": "git",

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);
-}