ph-utils 0.3.5 → 0.4.0

package/README.md

@@ -1,11 +1,11 @@
-## ph-utils
-
-整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
-
-### 后端(node server)
-
-包含了一些 node 后端开发(web server) 时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`file` 文件操作相关工具类、`server` 一些只适用于后端的工具(使用了后端的 API 列表)、`validator` 数据验证
-
-### 前端(web)
-
-包含了一些前端网站开发时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`dom` 浏览器节点操作相关、`web` 一些只适用于前端相关的工具、`validator` 数据验证
+## ph-utils
+
+整理了 js 前后端开发(web + nodejs)时常用的一些工具；[详细文档](https://gitee.com/towardly/ph/wikis/Home?sort_id=4035190)
+
+### 后端(node server)
+
+包含了一些 node 后端开发(web server) 时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`file` 文件操作相关工具类、`server` 一些只适用于后端的工具(使用了后端的 API 列表)、`validator` 数据验证
+
+### 前端(web)
+
+包含了一些前端网站开发时常用的工具类，包括 `index` 基础工具类(这个类里面的函数同样也适用于前端)、`date` 跟日期相关的工具类、`dom` 浏览器节点操作相关、`web` 一些只适用于前端相关的工具、`validator` 数据验证

package/lib/copy.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/copy.js

@@ -0,0 +1,105 @@
+/**
+ * 创建一个临时节点缓存待复制数据
+ * @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) {
+    let theClipboard = navigator.clipboard;
+    if (theClipboard != null) {
+        return theClipboard
+            .writeText(text)
+            .then(() => {
+            Promise.resolve(true);
+        })
+            .catch(() => Promise.resolve(false));
+    }
+    else {
+        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);
+    }
+    else {
+        return Promise.resolve(true);
+    }
+}

package/lib/server.js

@@ -1,5 +1,5 @@
 import { exec as execCmd, spawn } from 'child_process';
-import { isBlank } from './index';
+import { isBlank } from './index.js';
 /**
  * 执行命令
  * @param cmd 执行的命令

package/lib/storage.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 缓存相关
+ */
+type StorageType = 'session' | 'local';
+interface StorageSetOption {
+    storage?: StorageType;
+    /** 数据有效期, 单位秒, 默认: -1 - 永久存储 */
+    expire?: number;
+}
+/**
+ * 存储值到 Storage 中
+ * @param key 设置的 key
+ * @param value 设置的值
+ * @param storage session 或 local
+ * @param expire 数据有效期, 单位秒, 默认: -1 - 永久存储
+ */
+export declare function set(key: string, value: any, option?: StorageSetOption): void;
+/**
+ * 清空所有的缓存内容
+ * @param storage 待清空的缓存对象
+ */
+export declare function clear(storage?: StorageType): void;
+/**
+ * 删除存储到 Storage 中的数据
+ * @param key
+ * @param storage
+ */
+export declare function remove(key: string, storage?: StorageType): void;
+/** 从 Storage 中获取数据时的配置 */
+interface StorageQueryOption {
+    /** 数据是否持久化, 默认为: false, 设置为 true 则会在每一次取出数据后删除 */
+    delete?: boolean;
+    /** 存储对象, session、local */
+    storage?: StorageType;
+}
+/**
+ * 从 Storage 中取出数据
+ * @param key 保存时的 key
+ * @param defaultValue 没有数据时的默认值
+ * @param delete 是否在取出后，删除数据，默认：false - 取出后删除数据
+ * @param storage 使用的 Storage ，可以是 localStorage、sessionStorage
+ * @returns Storage 中 key 对应的数据
+ */
+export declare function get<T>(key: string, defaultValue?: T, option?: StorageQueryOption): T;
+export {};

package/lib/storage.js

@@ -0,0 +1,63 @@
+function getStorage(storage = 'session') {
+    return storage === 'session' ? sessionStorage : localStorage;
+}
+/**
+ * 存储值到 Storage 中
+ * @param key 设置的 key
+ * @param value 设置的值
+ * @param storage session 或 local
+ * @param expire 数据有效期, 单位秒, 默认: -1 - 永久存储
+ */
+export function set(key, value, option) {
+    const opts = { expire: -1, storage: 'session', ...(option || {}) };
+    const saveData = JSON.stringify({
+        value,
+        time: Date.now(),
+        expire: opts.expire === -1 ? -1 : Math.floor(Date.now() / 1000) + opts.expire,
+    });
+    getStorage(opts.storage).setItem(key, saveData);
+}
+/**
+ * 清空所有的缓存内容
+ * @param storage 待清空的缓存对象
+ */
+export function clear(storage) {
+    getStorage(storage).clear();
+}
+/**
+ * 删除存储到 Storage 中的数据
+ * @param key
+ * @param storage
+ */
+export function remove(key, storage) {
+    getStorage(storage).removeItem(key);
+}
+/**
+ * 从 Storage 中取出数据
+ * @param key 保存时的 key
+ * @param defaultValue 没有数据时的默认值
+ * @param delete 是否在取出后，删除数据，默认：false - 取出后删除数据
+ * @param storage 使用的 Storage ，可以是 localStorage、sessionStorage
+ * @returns Storage 中 key 对应的数据
+ */
+export function get(key, defaultValue, option) {
+    let opts = (option || { delete: false });
+    const storage = getStorage(opts.storage);
+    let data = storage.getItem(key);
+    if (data == null) {
+        return defaultValue || null;
+    }
+    data = JSON.parse(data);
+    let d = data.value;
+    if (data.expire !== -1) {
+        // 数据过期
+        if (Math.floor(Date.now() / 1000) > data.expire) {
+            d = null;
+            storage.removeItem(key);
+        }
+    }
+    if (opts.delete) {
+        storage.removeItem(key);
+    }
+    return d || defaultValue;
+}

package/lib/web.js

@@ -1,7 +1,7 @@
 /**
  * web(浏览器) 端工具类
  */
-import { isBlank } from './index';
+import { isBlank } from './index.js';
 /**
  * 解析 Form 表单中的 input 元素的数据为 JSON 格式，key: input-name；value: input-value
  * @param form {object} Form 节点对象

package/package.json

@@ -38,9 +38,17 @@
       "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"
+    },
     "./*": "./lib/*"
   },
-  "version": "0.3.5",
+  "version": "0.4.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -54,8 +62,8 @@
   },
   "homepage": "https://gitee.com/towardly/ph/tree/master/packages/utils",
   "devDependencies": {
-    "@types/node": "^20.3.1",
-    "typescript": "^5.1.3"
+    "@types/node": "^20.9.0",
+    "typescript": "^5.2.2"
   },
   "files": [
     "lib"