@jiangood/open-admin 1.0.0-beta.5

package/src/framework/utils/TreeUtils.ts

@@ -0,0 +1,251 @@
+import {ArrUtils} from "./ArrUtils"; // 假设 ArrUtil 已经被正确定义和导出
+
+/**
+ * 🌳 通用树节点接口
+ * 假设默认的 id, pid, children 字段存在，但支持其他字段
+ * @template T 节点数据的类型
+ */
+export interface TreeNode<T = any> {
+    /** 节点的唯一标识 */
+    id: string | number;
+    /** 父节点的标识 */
+    pid: string | number | null;
+    /** 子节点数组 */
+    children?: TreeNode<T>[];
+
+    /** 节点携带的额外数据 */
+    [key: string]: any;
+}
+
+/**
+ * 🌲 树结构操作工具类
+ * 将数组和树结构互相转换，并提供常用的遍历、查找功能。
+ */
+export class TreeUtils {
+
+    // --- 内部辅助函数 ---
+
+    /**
+     * 递归将树转换为列表的实现。
+     * @param tree 树节点数组
+     * @param level 当前层级
+     * @param result 结果列表，用于累积结果
+     * @returns 包含层级信息的列表
+     */
+    private static _treeToList<T extends TreeNode>(tree: T[], level: number, result: (T & { level: number })[]): (T & {
+        level: number
+    })[] {
+        for (const node of tree) {
+            // 复制节点并添加 level 字段
+            const newNode = {...node, level: level} as T & { level: number };
+            result.push(newNode);
+
+            if (node.children && node.children.length > 0) {
+                // 递归调用，层级加 1
+                this._treeToList(node.children as T[], level + 1, result);
+            }
+        }
+        return result;
+    }
+
+// --- 核心工具方法 ---
+
+    /**
+     * 🌲 将树结构转换为列表结构 (扁平化)。
+     * 节点会被添加一个 `level` 字段表示其层级 (从 1 开始)。
+     * @param tree 树节点数组
+     * @returns 包含层级信息的扁平化列表
+     */
+    public static treeToList<T extends TreeNode>(tree: T[]): (T & { level: number }) {
+        return TreeUtils._treeToList(tree, 1, []);
+    }
+
+    /**
+     * 🔎 根据层级查找所有节点的 ID 列表。
+     * @param tree 树节点数组
+     * @param level 要查找的层级，-1 表示所有层级的 ID。
+     * @returns 匹配层级的 ID 数组。
+     */
+    public static findKeysByLevel<T extends TreeNode>(tree: T[], level: number): (string | number)[] {
+        const list = TreeUtils.treeToList(tree);
+        // 如果 level 为 -1，则返回所有节点的 id；否则返回匹配 level 的节点 id
+        return list
+            .filter(t => level === -1 || t.level === level)
+            .map(t => t.id);
+    }
+
+    /**
+     * 🏗️ 将扁平数组转换为树结构。
+     * 默认使用 `id` 作为节点标识，`pid` 作为父节点标识。
+     * @param list 扁平化节点数组
+     * @param idKey 节点 ID 的字段名，默认为 'id'
+     * @param pidKey 父节点 ID 的字段名，默认为 'pid'
+     * @returns 根节点数组
+     */
+    public static buildTree<T extends TreeNode>(list: T[], idKey: keyof T | 'id' = 'id', pidKey: keyof T | 'pid' = 'pid'): T[] {
+        // 使用 Map 存储所有节点，方便通过 ID 查找
+        const map = new Map<string | number, T>();
+        list.forEach(node => {
+            const id = node[idKey] as string | number;
+            map.set(id, node);
+        });
+
+        const root: T[] = [];
+        for (const node of list) {
+            const pid = node[pidKey] as string | number | null | undefined;
+            // 通过 pidKey 查找父节点
+            const parent = pid ? map.get(pid) : undefined;
+
+            if (parent) {
+                // 如果找到父节点，将当前节点挂载到父节点的 children 数组
+                if (!parent.children) {
+                    parent.children = [];
+                }
+                // TypeScript 确保 children 数组的类型正确
+                (parent.children as T[]).push(node);
+            } else {
+                // 如果没有父节点 (或找不到)，则视为根节点
+                root.push(node);
+            }
+        }
+
+        return root;
+    }
+
+    /**
+     * 深度优先遍历树节点。
+     * @param tree 树节点数组
+     * @param callback 对每个节点执行的回调函数
+     */
+    public static walk<T extends TreeNode>(tree: T[], callback: (node: T) => void): void {
+        if(tree == null){
+            return
+        }
+        for (const node of tree) {
+            callback(node); // 执行回调函数
+
+            // 遍历子节点
+            if (node.children && node.children.length > 0) {
+                TreeUtils.walk(node.children as T[], callback);
+            }
+        }
+    }
+
+    /**
+     * 根据键值深度查找单个节点。
+     * @param key 要查找的键值 (例如: 节点的 id)
+     * @param list 树节点数组
+     * @param keyName 要匹配的字段名，默认为 'id'
+     * @returns 找到的节点，如果未找到则返回 undefined
+     */
+    public static findByKey<T extends TreeNode>(key: string | number, list: T[], keyName: keyof T | 'id' = 'id'): T | undefined {
+        for (const item of list) {
+            // 匹配当前节点
+            if (item[keyName] === key) {
+                return item;
+            }
+            // 递归查找子节点
+            if (item.children && item.children.length) {
+                const rs = TreeUtils.findByKey(key, item.children as T[], keyName);
+                if (rs) {
+                    return rs;
+                }
+            }
+        }
+        return undefined;
+    }
+
+
+    /**
+     * 📜 根据键值列表查找所有匹配的节点列表。
+     * @param treeData 树节点数组
+     * @param keyList 要查找的键值列表
+     * @returns 匹配的节点数组
+     */
+    public static findByKeyList<T extends TreeNode>(treeData: T[], keyList: (string | number)[]): T[] {
+        const itemList: T[] = [];
+
+        TreeUtils.walk(treeData, (item) => {
+            // 优先使用 key 字段，其次使用 id 字段
+            const key = item.key || item.id;
+
+            if (ArrUtils.contains(keyList, key)) {
+                itemList.push(item);
+            }
+        });
+
+        return itemList;
+    }
+
+    /**
+     * 获得指定节点下的所有子节点 (扁平化列表，包含自身)。
+     * @param treeNode 树节点
+     * @param buffer 结果列表，用于递归累积
+     * @returns 包含所有子节点的扁平化列表 (包含自身)
+     */
+    private static _getChild<T extends TreeNode>(treeNode: T, buffer: T[]): T[] {
+        if (treeNode.children != null && treeNode.children.length > 0) {
+            treeNode.children.forEach((c) => {
+                buffer.push(c as T);
+                TreeUtils._getChild(c as T, buffer);
+            });
+        }
+        return buffer;
+    }
+
+    /**
+     * 获得给定根节点列表下的所有节点 (扁平化列表)。
+     * @param treeNodeList 树节点数组
+     * @returns 包含所有节点的扁平化列表
+     */
+    public static getSimpleList<T extends TreeNode>(treeNodeList: T[]): T[] {
+        const buffer: T[] = [];
+
+        if (treeNodeList != null) {
+            treeNodeList.forEach((t) => {
+                buffer.push(t);
+                TreeUtils._getChild(t, buffer);
+            });
+        }
+        return buffer;
+    }
+
+
+    /**
+     * 向上追溯，获取从根节点到指定值节点的完整 Key 路径。
+     * 假设节点包含 `id` / `key` 和 `pid` / `parentKey` 字段。
+     * @param tree 完整的树结构数组
+     * @param value 目标节点的 ID 或 Key
+     * @returns 从根节点开始到目标节点的 ID/Key 数组 (包含根和目标节点)
+     */
+    public static getKeyList<T extends TreeNode>(tree: T[], value: string | number): (string | number)[] {
+        const list = TreeUtils.getSimpleList(tree);
+
+        // 使用 Map 快速通过 ID/Key 查找节点
+        const map = new Map<string | number, T>();
+        list.forEach((t) => {
+            const key = t.key || t.id;
+            map.set(key, t);
+        });
+
+        const targetNode = map.get(value);
+        if (targetNode == null) {
+            return []; // 未找到目标节点
+        }
+
+        const keys: (string | number)[] = [targetNode.key || targetNode.id];
+        let parentKey = targetNode.parentKey || targetNode.pid;
+
+        // 向上追溯
+        while (parentKey != null) {
+            const parent = map.get(parentKey);
+            if (parent == null) {
+                break; // 找不到父节点，停止追溯
+            }
+            keys.push(parent.key || parent.id);
+            parentKey = parent.parentKey || parent.pid;
+        }
+
+        return keys.reverse(); // 从根节点到目标节点的路径
+    }
+}

package/src/framework/utils/UrlUtils.ts

@@ -0,0 +1,152 @@
+// 假设 StrUtil 已经转换为 StrUtils 或有一个对应的类型定义
+// 如果 StrUtil 是一个工具对象，这里可能需要导入它
+import {StringUtils} from "./StringUtils";
+
+/**
+ * URL 相关操作的工具类
+ */
+export class UrlUtils {
+
+    /**
+     * 定义一个类型别名，用于 URL 参数对象
+     */
+    public type
+    ParamsObject = Record<string, string | number | boolean | null | undefined>;
+
+    /**
+     * 获取 URL 的参数对象。
+     * 如果不传参数，则使用当前路径 (location.href)。
+     * @param url 完整的 URL 字符串，可选。
+     * @returns 包含 URL 参数的键值对对象。
+     */
+    public static getParams(url: string | null = null): UrlUtils.ParamsObject {
+        // 1. 确定要解析的 URL
+        let targetUrl: string;
+        if (url === null || url === undefined) {
+            targetUrl = location.href;
+        } else {
+            targetUrl = url;
+        }
+
+        // 2. 检查是否有查询参数
+        if (!StringUtils.contains(targetUrl, '?')) {
+            return {};
+        }
+
+        // 3. 提取查询字符串 (问号后面的部分)
+        // 假设 StrUtil.subAfter 能够正确获取 '?' 之后的部分
+        const search = StringUtils.subAfter(targetUrl, '?');
+
+        // 4. 使用 URLSearchParams 进行解析 (现代浏览器环境)
+        // 注意：在某些旧环境或非浏览器环境中，可能需要不同的解析逻辑
+        const params = new URLSearchParams(search);
+
+        // 5. 转换为普通对象
+        const result: UrlUtils.ParamsObject = {} as UrlUtils.ParamsObject;
+        for (const [key, value] of params.entries()) {
+            // URLSearchParams 的值总是 string，因此这里赋值为 string
+            result[key] = value;
+        }
+
+        return result;
+    }
+
+    /**
+     * 获取不带参数的基础 URL (pathname)。
+     * @param url 完整的 URL 字符串。
+     * @returns 不包含查询参数的 URL 部分，如果 url 为 null/undefined，则返回 null。
+     */
+    public static getPathname(url: string | null | undefined): string | null {
+        if (!url) {
+            return null;
+        }
+        // 假设 StrUtil.subBefore 能够正确获取 '?' 之前的部分
+        return StringUtils.subBefore(url, '?');
+    }
+
+    /**
+     * 将参数对象转换为 URL 中的查询字符串（例如 k1=v1&k2=v2）。
+     * @param params 包含参数的键值对对象。
+     * @returns 查询字符串，不包含开头的问号 (?)。如果 params 为空，则返回空字符串。
+     */
+    public static paramsToSearch(params: UrlUtils.ParamsObject | null | undefined): string {
+        if (!params) {
+            return "";
+        }
+
+        const buffer: string[] = [];
+        // 迭代对象的自身属性
+        for (const k in params) {
+            // 确保只处理对象自身的属性，排除原型链上的属性
+            if (Object.prototype.hasOwnProperty.call(params, k)) {
+                const v = params[k];
+                // 忽略值为 null 或 undefined 的参数，或根据需要进行编码
+                if (v !== null && v !== undefined) {
+                    // 这里对值进行简单的连接，实际应用中建议使用 encodeURIComponent
+                    buffer.push(`${k}=${v}`);
+                }
+            }
+        }
+        return buffer.join('&');
+    }
+
+    /**
+     * 设置或删除 URL 中的一个参数，并返回新的 URL。
+     * @param url 原始 URL 字符串。
+     * @param key 要设置或删除的参数名。
+     * @param value 要设置的参数值。如果传入 null 或 undefined，则删除该参数。
+     * @returns 带有新参数的新 URL 字符串。
+     */
+    public static setParam(url: string, key: string, value: string | number | boolean | null | undefined): string {
+        // 1. 获取现有参数
+        const currentParams = this.getParams(url);
+
+        // 2. 根据 value 设置或删除参数
+        if (value === null || value === undefined) {
+            delete currentParams[key];
+        } else {
+            // 强制转换为 string 存储，以符合 URL 参数的惯例
+            currentParams[key] = String(value);
+        }
+
+        // 3. 获取基础路径
+        const pathname = this.getPathname(url);
+
+        // 4. 将新的参数对象转换为查询字符串
+        const newSearch = this.paramsToSearch(currentParams);
+
+        // 5. 组合新的 URL
+        if (newSearch.length > 0) {
+            return `${pathname}?${newSearch}`;
+        }
+        // 如果没有参数，则不带问号
+        return pathname || url; // 如果 pathname 为 null，则返回原始 url
+    }
+
+    /**
+     * @deprecated 使用 setParam 代替。
+     * 设置或替换 URL 中的一个参数，功能与 setParam 相同。
+     * @param url 原始 URL 字符串。
+     * @param key 要替换的参数名。
+     * @param value 要替换的参数值。
+     * @returns 带有新参数的新 URL 字符串。
+     */
+    public static replaceParam(url: string, key: string, value: string | number | boolean | null | undefined): string {
+        // 直接调用 setParam，并返回结果
+        return this.setParam(url, key, value);
+    }
+
+    /**
+     * 连接两个路径片段，确保中间只有一个斜杠 (/)。
+     * @param path1 第一个路径片段。
+     * @param path2 第二个路径片段。
+     * @returns 连接后的路径字符串。
+     */
+    public static join(path1: string, path2: string): string {
+        // 假设 StrUtil.removeSuffix/removePrefix 能够处理字符串前后的斜杠
+        const cleanPath1 = StringUtils.removeSuffix(path1, "/");
+        const cleanPath2 = StringUtils.removePrefix(path2, "/");
+
+        return `${cleanPath1}/${cleanPath2}`;
+    }
+}

package/src/framework/utils/UuidUtils.ts

@@ -0,0 +1,88 @@
+/**
+ * 基于 https://github.com/jchook/uuid-random 的工作进行封装
+ */
+export class UuidUtils {
+    // 静态属性用于存储随机字节缓冲区和索引
+    private static buf: Uint8Array | undefined = undefined;
+    private static bufIdx: number = 0;
+
+    // 预计算 toString(16) 以提高速度
+    private static readonly hexBytes: string[] = (() => {
+        const bytes = new Array<string>(256);
+        for (let i = 0; i < 256; i++) {
+            // (i + 0x100).toString(16).substring(1) 确保总是两位十六进制
+            bytes[i] = (i + 0x100).toString(16).substring(1);
+        }
+        return bytes;
+    })();
+
+    // 缓冲区大小，可调整
+    private static readonly BUFFER_SIZE: number = 4096;
+
+    // 随机字节生成函数，使用最佳可用 PRNG
+    private static readonly randomBytes = ((n: number): Uint8Array => {
+        // Node & Browser 支持
+        const lib = typeof crypto !== 'undefined'
+            ? crypto
+            : (
+                typeof window !== 'undefined'
+                    ? window.crypto || (window as any).msCrypto // window.msCrypto 在 TypeScript 中可能不存在
+                    : undefined
+            );
+
+        if (lib !== undefined) {
+            // Node.js 支持
+            if ((lib as any).randomBytes !== undefined) {
+                return (lib as any).randomBytes(n);
+            }
+// 浏览器支持
+            if (lib.getRandomValues !== undefined) {
+                return (() => {
+                    const bytes = new Uint8Array(n);
+                    lib.getRandomValues(bytes);
+                    return bytes;
+                })();
+            }
+        }
+
+// 降级使用 Math.random
+        const r = new Uint8Array(n);
+        for (let i = 0; i < n; i++) {
+            r[i] = Math.floor(Math.random() * 256);
+        }
+        return r;
+    });
+
+    /**
+     * 生成一个符合 v4 标准的 UUID。
+     * @returns 一个 UUID 字符串。
+     */
+    public static uuidV4(): string {
+        // 为加速而缓冲一些随机字节
+        if (UuidUtils.buf === undefined || (UuidUtils.bufIdx + 16 > UuidUtils.BUFFER_SIZE)) {
+            UuidUtils.bufIdx = 0;
+            // randomBytes 的返回类型已确定为 Uint8Array
+            UuidUtils.buf = UuidUtils.randomBytes(UuidUtils.BUFFER_SIZE);
+        }
+
+        // 提取 16 个字节。使用 Array.prototype.slice.call 转化为 Array 并不能保证性能，
+        // 且 TypeScript 中操作 Uint8Array 更直接。我们直接使用 subarray 提取，性能更优。
+        const b = UuidUtils.buf.subarray(UuidUtils.bufIdx, (UuidUtils.bufIdx += 16));
+
+        // 设置 UUID 版本 (Version 4: 0100)
+        b[6] = (b[6] & 0x0f) | 0x40;
+        // 设置时钟序列高位 (Variant 1: 10xx)
+        b[8] = (b[8] & 0x3f) | 0x80;
+
+        // 将字节转换为十六进制字符串格式
+        const h = UuidUtils.hexBytes;
+        return h[b[0]] + h[b[1]]
+            + h[b[2]] + h[b[3]] + '-'
+            + h[b[4]] + h[b[5]] + '-'
+            + h[b[6]] + h[b[7]] + '-'
+            + h[b[8]] + h[b[9]] + '-'
+            + h[b[10]] + h[b[11]]
+            + h[b[12]] + h[b[13]]
+            + h[b[14]] + h[b[15]];
+    }
+}

package/src/framework/utils/ValidateUtils.ts

@@ -0,0 +1,28 @@
+/**
+ * 验证工具类
+ */
+export class ValidateUtils {
+
+    /**
+     * 检查给定的字符串是否为有效的电子邮件地址。
+     * @param emailStr 要检查的字符串。
+     * @returns 如果是有效的电子邮件地址，则返回 true；否则返回 false。
+     */
+    public static isEmail(emailStr: string): boolean {
+        // 匹配大多数常见电子邮件格式的正则表达式
+        const reg = /^([\w+.-])+@\w+([.]\w+)+$/;
+        return reg.test(emailStr);
+    }
+
+    // 可以在这里添加其他验证方法，例如：
+    /*
+    public static isPhone(phoneStr: string): boolean {
+        // ... 手机号验证逻辑
+        return /^\d{10}$/.test(phoneStr);
+    }
+    */
+}
+
+// 示例用法：
+// const isValid = ValidateUtils.isEmail("test@example.com");
+// console.log(isValid); // true

package/src/framework/utils/index.ts

@@ -0,0 +1,15 @@
+export * from "./DateUtils";
+export * from "./ArrUtils";
+export * from "./UrlUtils"
+export * from "./StringUtils"
+export * from "./EventBusUtils";
+export * from "./ColorsUtils"
+export * from "./DomUtils"
+export * from "./UuidUtils";
+export * from "./TreeUtils";
+export * from './StorageUtils'
+export * from './DeviceUtils'
+export * from './ObjectUtils'
+export * from './ValidateUtils'
+export * from './system'
+export * from './MessageUtils'

package/src/framework/utils/system/DictUtils.ts

@@ -0,0 +1,97 @@
+// 假设的类型定义，你需要确保与你的实际数据结构匹配
+import {SysUtils} from "./SysUtils";
+
+export interface DictItem {
+    value: string | number;
+    label: string;
+    color?: string;
+}
+
+
+// 假设 SysUtil 和 StrUtil 的引入和类型
+// 实际使用时需要确保路径和模块存在
+import {Tag} from 'antd';
+import React from 'react';
+import {StringUtils} from "../StringUtils";
+
+// 字典选项的格式
+export interface DictOption {
+    value: string|number;
+    label: string;
+}
+
+/**
+ * 字典相关的工具类
+ */
+export class DictUtils {
+
+    /**
+     * 根据字典类型code返回字典数据列表。
+     * code 支持 驼峰或下划线（都转为下划线进行匹配）。
+     * @param code 字典类型编码 (如 'userStatus', 'USER_STATUS')
+     * @returns 对应的字典项列表，未找到返回空数组
+     */
+    public static dictList(code: string): DictItem[] {
+        const map = SysUtils.getDictInfo();
+        if (!map) {
+            return [];
+        }
+
+        code = StringUtils.toUnderlineCase(code).toUpperCase();
+
+        return map[code] || [];
+    }
+
+    /**
+     * 将字典列表转换为 Ant Design Select/Options 格式
+     * @param typeCode 字典类型编码
+     * @returns 包含 value/label 的选项列表
+     */
+    public static dictOptions(typeCode: string): DictOption[] {
+        const list: DictItem[] = DictUtils.dictList(typeCode);
+        return list.map(i => {
+            return {
+                value: i.value,
+                label: i.label,
+            }
+        });
+    }
+
+
+    /**
+     * 根据字典类型和字典项code获取对应的名称(name)
+     * @param typeCode 字典类型编码
+     * @param code 字典项编码
+     * @returns 对应的名称，未找到返回 undefined
+     */
+    public static dictLabel(typeCode: string, code: string | number): string | undefined {
+        const items = DictUtils.dictList(typeCode);
+        const item = items.find(i => i.value === code);
+        return item ? item.label : undefined;
+    }
+
+    /**
+     * 根据字典类型和字典项code获取对应的名称，并使用 Ant Design Tag 组件包装 (如果存在 color 属性)
+     * @param typeCode 字典类型编码
+     * @param code 字典项编码
+     * @returns Antd Tag 元素或纯字符串名称或空字符串
+     */
+    public static dictTag(typeCode: string, code: string | number ): React.ReactElement | string {
+        if (typeCode == null || code == null) {
+            return null;
+        }
+        const item = DictUtils.dictList(typeCode).find(i => i.value === code);
+
+        if (item == null) {
+            return null;
+        }
+        const {label, color} = item;
+
+        if (color == null) {
+            // 如果没有颜色，返回纯文本
+            return label;
+        }
+
+        return React.createElement(Tag, {color: color}, label);
+    }
+}