ph-utils 0.16.5 → 0.17.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Tenny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/date.js

@@ -12,17 +12,11 @@ const ofArgs = {
 const units = {
     Date: ["date", "Date", "day", "Day", "D", "d"],
     Month: ["Month", "month", "m"],
-    Year: ["Year", "year", "y"],
+    FullYear: ["Year", "year", "y"],
     Hours: ["Hours", "hours", "H"],
     Minutes: ["Minutes", "Minute", "minute", "minutes", "M"],
     Seconds: ["Seconds", "seconds", "Second", "second", "s"],
-    Milliseconds: [
-        "Milliseconds",
-        "Millisecond",
-        "milliseconds",
-        "illisecond",
-        "S",
-    ],
+    Milliseconds: ["Milliseconds", "Millisecond", "milliseconds", "illisecond", "S"],
 };
 /**
  * 不足位数, 前位补 0
@@ -135,15 +129,7 @@ export function parse(date) {
  */
 export function dateOf(date, unit, isEnd = false) {
     /* 如果是设置某一天的开始时刻, 就需要将时、分、秒、毫秒设置为0，依次类推设置 */
-    const periods = [
-        "Year",
-        "Month",
-        "Date",
-        "Hours",
-        "Minutes",
-        "Seconds",
-        "Milliseconds",
-    ];
+    const periods = ["Year", "Month", "Date", "Hours", "Minutes", "Seconds", "Milliseconds"];
     let index = periods.indexOf(getUnit(unit || "Date"));
     const clone = parse(date);
     index++;
@@ -154,9 +140,7 @@ export function dateOf(date, unit, isEnd = false) {
             // 设置为某个月的最后一天的日期
             value = getLastDayOfMonth(clone);
         }
-        Date.prototype["set" + periods[index]].apply(clone, [
-            setValues[index],
-        ]);
+        Date.prototype["set" + periods[index]].apply(clone, [setValues[index]]);
     }
     return clone;
 }

package/lib/dom.d.ts

@@ -119,7 +119,7 @@ export declare function html(element: HTMLElement, htmlstr?: string): string | u
  * @param textstr 可选，如果传递该参数，则表示设置；否则表示获取
  * @returns
  */
-export declare function text(element: HTMLElement, textstr?: string): string | undefined;
+export declare function text(element: HTMLElement, textstr?: string): string | undefined | null;
 export declare function iterate<T>(elems: T[], fn: (el: T, index: number) => any): void;
 export declare function iterate(elems: NodeList | HTMLCollection | NodeListOf<HTMLElement>, fn: (el: HTMLElement, index: number) => any): void;
 /**
@@ -222,4 +222,31 @@ export declare function formatStyle(styleObj: FormatStyleParam): string;
  * transition($el, [["opacity", "0", "0.3s"]], "leave", () => {  $el.remove(); });
  */
 export declare function transition(el: HTMLElement, nameOrProperties: string | [string, string, string][], dir?: "leave" | "enter", finish?: () => void): void;
+/**
+ * 计算光标位置
+ *
+ * 根据输入值的变化计算新的光标位置，主要用于输入框内容变化时的光标位置调整
+ *
+ * @param start - 光标起始位置，通常为: input.selectionStart
+ * @param end - 光标结束位置（通常与起始位置相同，用于选择范围），通常为: input.selectionEnd
+ * @param oldValue - 变化前的值
+ * @param newValue - 变化后的值
+ * @returns 新的光标位置对象，包含新的起始和结束位置
+ *
+ * @example
+ * // 删除字符时，光标向前移动
+ * calcuteCursorPosition(2, 2, "abc", "ac"); // 返回 { start: 1, end: 1 }
+ *
+ * @example
+ * // 添加字符时，光标向后移动
+ * calcuteCursorPosition(2, 2, "ac", "abc"); // 返回 { start: 3, end: 3 }
+ *
+ * @example
+ * // 替换字符时，保持位置
+ * calcuteCursorPosition(2, 2, "abc", "axc"); // 返回 { start: 2, end: 2 }
+ */
+export declare function calcuteCursorPosition(start: number, end: number, oldValue: string, newValue: string): {
+    start: number;
+    end: number;
+};
 export {};

package/lib/dom.js

@@ -550,3 +550,50 @@ export function transition(el, nameOrProperties, dir = "enter", finish) {
         }
     }, { once: true });
 }
+/**
+ * 计算光标位置
+ *
+ * 根据输入值的变化计算新的光标位置，主要用于输入框内容变化时的光标位置调整
+ *
+ * @param start - 光标起始位置，通常为: input.selectionStart
+ * @param end - 光标结束位置（通常与起始位置相同，用于选择范围），通常为: input.selectionEnd
+ * @param oldValue - 变化前的值
+ * @param newValue - 变化后的值
+ * @returns 新的光标位置对象，包含新的起始和结束位置
+ *
+ * @example
+ * // 删除字符时，光标向前移动
+ * calcuteCursorPosition(2, 2, "abc", "ac"); // 返回 { start: 1, end: 1 }
+ *
+ * @example
+ * // 添加字符时，光标向后移动
+ * calcuteCursorPosition(2, 2, "ac", "abc"); // 返回 { start: 3, end: 3 }
+ *
+ * @example
+ * // 替换字符时，保持位置
+ * calcuteCursorPosition(2, 2, "abc", "axc"); // 返回 { start: 2, end: 2 }
+ */
+export function calcuteCursorPosition(start, end, oldValue, newValue) {
+    // 5. 【关键】计算新光标位置并恢复
+    let newStart = start;
+    let newEnd = end;
+    // 简单策略：如果新值比旧值短，说明删了字符，光标前移
+    // 更健壮的做法：对比差异，但通常可简化处理
+    if (newValue.length < oldValue.length) {
+        // 例如：用户在中间删了一个非法字符
+        newStart = Math.max(0, start - (oldValue.length - newValue.length));
+        newEnd = newStart;
+    }
+    else if (newValue.length > oldValue.length) {
+        // 插入合法字符，光标通常就在插入点后，可保持原偏移
+        // 但需防止超出长度
+        newStart = Math.min(newValue.length, start + (newValue.length - oldValue.length));
+        newEnd = newStart;
+    }
+    else {
+        // 长度不变（如替换），保持原位置（但要限制范围）
+        newStart = Math.min(newValue.length, start);
+        newEnd = newStart;
+    }
+    return { start: newStart, end: newEnd };
+}

package/package.json

@@ -1,99 +1,99 @@
-{
-  "name": "ph-utils",
-  "description": "js 开发工具集，前后端都可以使用(commonjs和es module)",
-  "main": "lib/index.js",
-  "module": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "browser": "lib/index.js",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "import": "./lib/index.js"
-    },
-    "./file": {
-      "types": "./lib/file.d.ts",
-      "import": "./lib/file.js"
-    },
-    "./date": {
-      "types": "./lib/date.d.ts",
-      "import": "./lib/date.js"
-    },
-    "./server": {
-      "types": "./lib/server.d.ts",
-      "import": "./lib/server.js"
-    },
-    "./validator": {
-      "types": "./lib/validator.d.ts",
-      "import": "./lib/validator.js"
-    },
-    "./crypto": {
-      "types": "./lib/crypto.d.ts",
-      "import": "./lib/crypto.js"
-    },
-    "./crypto_node": {
-      "types": "./lib/crypto_node.d.ts",
-      "import": "./lib/crypto_node.js"
-    },
-    "./web": {
-      "types": "./lib/web.d.ts",
-      "import": "./lib/web.js"
-    },
-    "./dom": {
-      "types": "./lib/dom.d.ts",
-      "import": "./lib/dom.js"
-    },
-    "./copy": {
-      "types": "./lib/copy.d.ts",
-      "import": "./lib/copy.js"
-    },
-    "./storage": {
-      "types": "./lib/storage.d.ts",
-      "import": "./lib/storage.js"
-    },
-    "./color": {
-      "types": "./lib/color.d.ts",
-      "import": "./lib/color.js"
-    },
-    "./logger": {
-      "types": "./lib/logger.d.ts",
-      "import": "./lib/logger.js"
-    },
-    "./array": {
-      "types": "./lib/array.d.ts",
-      "import": "./lib/array.js"
-    },
-    "./theme": {
-      "types": "./lib/theme.d.ts",
-      "import": "./lib/theme.js"
-    },
-    "./*": "./lib/*"
-  },
-  "version": "0.16.5",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https//gitee.com/towardly/ph.git",
-    "directory": "packages/utils"
-  },
-  "license": "MIT",
-  "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": "^22.8.2",
-    "typescript": "^5.6.3"
-  },
-  "files": [
-    "lib"
-  ],
-  "keywords": [
-    "node",
-    "utils",
-    "javascript",
-    "date",
-    "dom",
-    "file"
-  ]
-}
+{
+  "name": "ph-utils",
+  "version": "0.17.1",
+  "description": "js 开发工具集，前后端都可以使用(commonjs和es module)",
+  "keywords": [
+    "date",
+    "dom",
+    "file",
+    "javascript",
+    "node",
+    "utils"
+  ],
+  "homepage": "https://gitee.com/towardly/ph/tree/master/packages/utils",
+  "bugs": {
+    "url": "https://gitee.com/towardly/ph/issues"
+  },
+  "license": "MIT",
+  "author": "Tenny <tenny.shu@foxmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https//gitee.com/towardly/ph.git",
+    "directory": "packages/utils"
+  },
+  "files": [
+    "lib"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "browser": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./file": {
+      "types": "./lib/file.d.ts",
+      "import": "./lib/file.js"
+    },
+    "./date": {
+      "types": "./lib/date.d.ts",
+      "import": "./lib/date.js"
+    },
+    "./server": {
+      "types": "./lib/server.d.ts",
+      "import": "./lib/server.js"
+    },
+    "./validator": {
+      "types": "./lib/validator.d.ts",
+      "import": "./lib/validator.js"
+    },
+    "./crypto": {
+      "types": "./lib/crypto.d.ts",
+      "import": "./lib/crypto.js"
+    },
+    "./crypto_node": {
+      "types": "./lib/crypto_node.d.ts",
+      "import": "./lib/crypto_node.js"
+    },
+    "./web": {
+      "types": "./lib/web.d.ts",
+      "import": "./lib/web.js"
+    },
+    "./dom": {
+      "types": "./lib/dom.d.ts",
+      "import": "./lib/dom.js"
+    },
+    "./copy": {
+      "types": "./lib/copy.d.ts",
+      "import": "./lib/copy.js"
+    },
+    "./storage": {
+      "types": "./lib/storage.d.ts",
+      "import": "./lib/storage.js"
+    },
+    "./color": {
+      "types": "./lib/color.d.ts",
+      "import": "./lib/color.js"
+    },
+    "./logger": {
+      "types": "./lib/logger.d.ts",
+      "import": "./lib/logger.js"
+    },
+    "./array": {
+      "types": "./lib/array.d.ts",
+      "import": "./lib/array.js"
+    },
+    "./theme": {
+      "types": "./lib/theme.d.ts",
+      "import": "./lib/theme.js"
+    },
+    "./*": "./lib/*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.8.2",
+    "typescript": "^5.6.3"
+  }
+}