ph-utils 0.9.2 → 0.9.4

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

@@ -1,9 +1,9 @@
 /**
- * 验证字符串是否为空
- * @param str               待验证的字符串
- * @param ignoreWhitespace  是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
+ * 验证参数是否为空
+ * @param str               待验证的参数
+ * @param ignoreWhitespace  如果是字符串是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
  */
-export declare function isBlank(str?: string | null, ignoreWhitespace?: boolean): boolean;
+export declare function isBlank(str?: any, ignoreWhitespace?: boolean): boolean;
 /**
  * 屏蔽手机号，中间部分用 * 展示
  * @param mobile 待屏蔽的手机号

package/lib/index.js

@@ -6,15 +6,17 @@ const RANDOM_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz012345
 /** 只包含字母的随机数字符 */
 const NUMBER_RANDOM_CHARTS = "0123456789";
 /**
- * 验证字符串是否为空
- * @param str               待验证的字符串
- * @param ignoreWhitespace  是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
+ * 验证参数是否为空
+ * @param str               待验证的参数
+ * @param ignoreWhitespace  如果是字符串是否忽略空格(包括空白字符串以及[\r\t\n]之类的制表符)，默认为true
  */
 export function isBlank(str, ignoreWhitespace = true) {
     if (str == null) {
         return true;
     }
-    return (ignoreWhitespace ? str.trim().length : str.length) === 0;
+    return ((ignoreWhitespace && typeof str === "string"
+        ? str.trim().length
+        : str.length) === 0);
 }
 /**
  * 屏蔽手机号，中间部分用 * 展示

package/lib/theme.js

@@ -136,7 +136,7 @@ export async function toggleColorTheme(color) {
  */
 export function applyColorTheme(color, cache = true) {
     if (cache === true) {
-        localStorage.setItem("web-theme-color", color.substring(1));
+        localStorage.setItem("web-theme-color", color);
     }
     return toggleColorTheme(color);
 }

package/lib/validator.d.ts

@@ -26,7 +26,20 @@ declare class Validator {
     };
     /**
      * 构造数据验证转换器
+     *
+     * See {@link https://gitee.com/towardly/ph/wikis/utils/validator|Validator文档}.
+     *
      * @param schemas 配置验证转换规则
+     *
+     * @example
+     *
+     * const validator = new Validator([
+     *  { key: 'mobile', rules: ['required', 'mobile'] },
+     *  { key: 'code': rules: /^\d{6}$/, message: '请输入正确的验证码' },
+     *  { key: 'confirmPassword', rules: ['required', 'same:password'] }
+     * ])
+     * // 验证某一个字段
+     * validator.validateKey().then(res => {})
      */
     constructor(schemas: SchemaType[]);
     /**

package/lib/validator.js

@@ -47,7 +47,20 @@ class Validator {
     rules;
     /**
      * 构造数据验证转换器
+     *
+     * See {@link https://gitee.com/towardly/ph/wikis/utils/validator|Validator文档}.
+     *
      * @param schemas 配置验证转换规则
+     *
+     * @example
+     *
+     * const validator = new Validator([
+     *  { key: 'mobile', rules: ['required', 'mobile'] },
+     *  { key: 'code': rules: /^\d{6}$/, message: '请输入正确的验证码' },
+     *  { key: 'confirmPassword', rules: ['required', 'same:password'] }
+     * ])
+     * // 验证某一个字段
+     * validator.validateKey().then(res => {})
      */
     constructor(schemas) {
         let parsedRules = {};

package/package.json

@@ -64,7 +64,7 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.9.2",
+  "version": "0.9.4",
   "type": "module",
   "repository": {
     "type": "git",