ph-utils 0.16.4 → 0.17.1

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

@@ -1,7 +1,7 @@
 /**
  * 将日期格式化为指定形式的字符串
  * @param date      日期
- * @param pattern   格式化字符串 yyyy - 年, mm - 月, dd - 日, HH - 小时, MM - 分钟, ss - 秒, S - 毫秒, 默认: yyyy-mm-dd HH:MM:ss
+ * @param pattern   格式化字符串 yyyy - 年, mm - 月, dd - 日, HH - 小时(24时制), MM - 分钟, ss - 秒, S - 毫秒, 默认: yyyy-mm-dd HH:MM:ss
  */
 export declare function format(date?: Date | string | number | null, pattern?: string): string;
 /**
@@ -13,24 +13,24 @@ export declare function parse(date?: Date | string | number | null): Date;
 /**
  * 设置日期的开始或者结束的点
  * @param date 日期，能够被 parse 解析的日期
- * @param unit 单位，Date|date, 默认为 Date
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
  * @param isEnd true则为 endOf
  */
-export declare function dateOf(date?: Date | string | number, unit?: string, isEnd?: boolean): Date;
+export declare function dateOf(date?: Date | string | number | null, unit?: string, isEnd?: boolean): Date;
 /**
  * 设置日期的开始的点
  * @param date 日期，能够被 parse 解析的日期
- * @param unit 单位，Date|date, 默认为 Date
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
  * @returns
  */
-export declare function startOf(date?: Date | string | number, unit?: string): Date;
+export declare function startOf(date?: Date | string | number | null, unit?: string): Date;
 /**
  * 设置日期的结束点
  * @param date 日期，能够被 parse 解析的日期
- * @param unit 单位，Date|date, 默认为 Date
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
  * @returns
  */
-export declare function endOf(date?: Date | string | number, unit?: string): Date;
+export declare function endOf(date?: Date | string | number | null, unit?: string): Date;
 /**
  * 获取时间戳
  * @param ctime 时间

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
@@ -72,7 +66,7 @@ function getLastDayOfMonth(date, month) {
 /**
  * 将日期格式化为指定形式的字符串
  * @param date      日期
- * @param pattern   格式化字符串 yyyy - 年, mm - 月, dd - 日, HH - 小时, MM - 分钟, ss - 秒, S - 毫秒, 默认: yyyy-mm-dd HH:MM:ss
+ * @param pattern   格式化字符串 yyyy - 年, mm - 月, dd - 日, HH - 小时(24时制), MM - 分钟, ss - 秒, S - 毫秒, 默认: yyyy-mm-dd HH:MM:ss
  */
 export function format(date, pattern = "yyyy-mm-dd HH:MM:ss") {
     // eslint-disable-next-line
@@ -130,20 +124,12 @@ export function parse(date) {
 /**
  * 设置日期的开始或者结束的点
  * @param date 日期，能够被 parse 解析的日期
- * @param unit 单位，Date|date, 默认为 Date
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
  * @param isEnd true则为 endOf
  */
 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,16 +140,14 @@ 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;
 }
 /**
  * 设置日期的开始的点
  * @param date 日期，能够被 parse 解析的日期
- * @param unit 单位，Date|date, 默认为 Date
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
  * @returns
  */
 export function startOf(date, unit) {
@@ -172,7 +156,7 @@ export function startOf(date, unit) {
 /**
  * 设置日期的结束点
  * @param date 日期，能够被 parse 解析的日期
- * @param unit 单位，Date|date, 默认为 Date
+ * @param unit 单位，Date[D]、Minute[M], 默认为 Date
  * @returns
  */
 export function endOf(date, unit) {

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/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

@@ -1,10 +1,34 @@
 {
   "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",
-  "types": "lib/index.d.ts",
   "browser": "lib/index.js",
+  "types": "lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
@@ -68,32 +92,8 @@
     },
     "./*": "./lib/*"
   },
-  "version": "0.16.4",
-  "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"
-  ]
+  }
 }