ui-utils-kit/dist/index.d.cts

ui-utils-kit 是一个高效的偏业务前端工具函数库

import { Options } from 'html2canvas-pro';

/**
 * 输出选项接口
 */
interface OutputOptions {
    /** 是否自动下载生成的图片 */
    download?: boolean;
    /** 下载图片的文件名（不含扩展名） */
    downloadName?: string;
    /** 是否返回 Blob 格式的图片数据 */
    blob?: boolean;
}
/**
 * 捕获结果接口
 */
interface CaptureResult {
    /** 生成的 Canvas 元素 */
    canvas: HTMLCanvasElement | null;
    /** 图片的 Data URL 字符串（若启用了下载，则存在） */
    dataUrl: string | null;
    /** 图片的 Blob 对象（若启用了 blob 输出，则存在） */
    blob: Blob | null;
}

/**
 * =====================
 * ==业务相关的工具类函数==
 * =====================
 */
/**
 * 将 DOM 元素转换为图片（canvas），并支持自动下载或返回 Blob 格式数据。
 *
 * @param element - 需要捕捉的 DOM 元素。
 * @param canvasConfig - html2canvas 的配置项，例如 scale、backgroundColor 等。
 * @param outputOptions - 输出选项。
 * @returns 返回 Promise，包含 { canvas, dataUrl, blob } 对象。
 */
declare function captureElementAsImage(element: HTMLElement | null, canvasConfig?: Partial<Options>, outputOptions?: OutputOptions): Promise<CaptureResult>;

declare const business_captureElementAsImage: typeof captureElementAsImage;
declare namespace business {
  export { business_captureElementAsImage as captureElementAsImage };
}

/**
 * 自校正时钟管理器接口
 */
interface SelfCorrectingClock {
    /** 获取最新的当前时间戳（毫秒） */
    getCurrentTime: () => number;
    /** 停止内部定时器，释放资源 */
    stop: () => void;
}
/**
 * 自校正倒计时管理器接口
 */
interface SelfCorrectingCountdown {
    /**
     * 获取最新的剩余时间（毫秒）
     * @returns 剩余时间（毫秒）
     */
    getRemainingTime: () => number;
    /**
     * 手动停止倒计时，释放资源
     * @returns 无返回值
     */
    stop: () => void;
}

/**
 * =====================
 * =======公共函数=======
 * =====================
 */
/**
 * 安全地解析 JSON 字符串。
 *
 * @param jsonString - 要解析的 JSON 字符串。
 * @param defaultValue - 解析失败时返回的默认值。
 * @returns 一个元组，第一个元素为错误对象（若无错误则为 null），第二个元素为解析结果或默认值。
 */
declare function safeJsonParse<T>(jsonString: string, defaultValue: T): [Error | null, T];
/**
 * 数据脱敏函数
 *
 * @param value - 原始数据
 * @param type - 脱敏类型
 * @returns 脱敏后的数据
 */
declare function desensitize(value: string, type: "mobile" | "idcard" | "email" | "bankcard" | "name"): string;
/**
 * 模拟互斥锁（Mutex）机制，用于控制异步操作对共享资源的访问
 */
declare class Mutex {
    #private;
    /**
     * 获取锁。如果当前已锁定，则将请求加入队列，等待解锁后依次获取。
     * @returns Promise<void> - 当获取到锁时，Promise 被 resolve。
     */
    lock(): Promise<void>;
    /**
     * 释放锁。如果有等待队列，则唤醒队列中的下一个请求；否则将锁状态设为未锁定。
     */
    unlock(): void;
    /**
     * 查询当前锁的状态
     * @returns boolean - true 表示已锁定，false 表示未锁定
     */
    isLocked(): boolean;
    /**
     * 获取当前等待队列的长度
     * @returns number - 等待队列中的请求数量
     */
    queueLength(): number;
}
/**
 * 创建零漂移的自校正实时时钟
 * @param interval 更新间隔（毫秒），默认 1000
 */
declare function createSelfCorrectingClock(interval?: number): SelfCorrectingClock;
/**
 * 创建零漂移的自校正倒计时器
 * @param targetTimestamp 目标时间戳（毫秒）
 * @param interval 更新间隔（毫秒），默认值为 1000
 * @returns 自校正倒计时管理器实例，包含获取剩余时间和停止定时器的方法
 */
declare function createSelfCorrectingCountdown(targetTimestamp: number, interval?: number): SelfCorrectingCountdown;

type common_Mutex = Mutex;
declare const common_Mutex: typeof Mutex;
declare const common_createSelfCorrectingClock: typeof createSelfCorrectingClock;
declare const common_createSelfCorrectingCountdown: typeof createSelfCorrectingCountdown;
declare const common_desensitize: typeof desensitize;
declare const common_safeJsonParse: typeof safeJsonParse;
declare namespace common {
  export { common_Mutex as Mutex, common_createSelfCorrectingClock as createSelfCorrectingClock, common_createSelfCorrectingCountdown as createSelfCorrectingCountdown, common_desensitize as desensitize, common_safeJsonParse as safeJsonParse };
}

type ExtractValue<T> = T[keyof T];
declare const CheckStatus: {
    readonly Unchecked: "0";
    readonly HalfChecked: "1";
    readonly Checked: "2";
};
type CheckStatusType = ExtractValue<typeof CheckStatus>;
interface TreeNode {
    id: string | number;
    pid: string | number | null;
    check: CheckStatusType;
    children?: TreeNode[];
    [key: string]: any;
}

/**
 * ========================
 * ==树级数据操作的工具类函数==
 * ========================
 */
/**
 * 构建树形结构
 * @param {Array} nodes - 树节点数组，每个节点包含 `id` 和 `pid` 等属性
 * @returns {Array} - 树形结构数组
 */
declare function buildTree(nodes: TreeNode[]): TreeNode[];
/**
 * 将树形结构转换为扁平化数组
 * @param {TreeNode[]} data - 树形数据，包含 `id`, `name` 和可选的 `children` 属性
 * @returns {Array} - 扁平化的数组，包含节点的 `id`, `name`, 和 `pid`
 */
declare function treeToArr(data: TreeNode[]): TreeNode[];
/**
 * 更新树结构的节点选中状态。
 * 该函数处理具有多个根节点的树结构，当选中或取消选中某些节点时，更新整个树的状态。
 * 父节点的状态会根据其子节点的状态自动变为选中、半选或未选中。
 *
 * @param {TreeNode[]} tree - 树结构的数组，每个节点包含 id, name, pid, children, check 属性。
 * @param {TreeNode[]} selectedNodes - 选中的节点数组，每个节点同样包含 id, name, pid, children, check 属性。
 * @returns {TreeNode[]} 返回更新后的树结构数组。
 */
declare function updateTreeCheckStatus(tree: TreeNode[], selectedNodes: TreeNode[]): TreeNode[];
/**
 * 更新扁平数组格式的树结构的节点选中状态。
 * 该函数处理扁平数组形式的树结构，当选中或取消选中某些节点时，更新整个树的状态。
 * 父节点的状态会根据其子节点的状态自动变为选中、半选或未选中。
 *
 * @param {TreeNode[]} tree - 扁平数组格式的树结构，每个节点包含 id, name, pid, check 属性，children 属性可以为空。
 * @param {TreeNode[]} selectedNodes - 选中的节点数组，每个节点同样包含 id, name, pid, check 属性。
 * @returns {TreeNode[]} 返回更新后的扁平数组格式的树结构。
 */
declare function updateTreeCheckStatusFlat(tree: TreeNode[], selectedNodes: TreeNode[]): TreeNode[];
/**
 * 在树形结构中根据关键词查找相关节点，并返回包含匹配节点、父节点和子节点的结果。
 *
 * @param {Array} treeArr - 树形数据数组，每个元素应为一个节点对象，节点对象至少包含 `id`, `pid`, `name` 属性。
 * @param {string} keywords - 用于查找的关键词，匹配节点的 `name` 属性。
 * @param {boolean} mark - 是否在结果中标记 `isMatched` 属性。
 * @returns {Array} - 返回匹配的节点数组，包含匹配的节点及其父节点和子节点，顺序为父节点在前、子节点在后。
 */
declare function searchTreeWithRelations(treeArr?: TreeNode[], keywords?: string, mark?: boolean): TreeNode[];
/**
 * 从树形结构中移除指定的节点
 * @param {Array} treeArr - 当前的扁平树形结构数组，每个节点对象包含 `id` 和 `pid` 属性
 * @param {Array} selectedNodes - 要移除的节点数组，每个节点包含 `id` 和 `pid` 属性
 * @returns {Array} - 过滤后的扁平树形结构数组，其中移除了指定的节点及其子节点（如果父节点被移除）
 */
declare function removeNodesFromTree(treeArr?: TreeNode[], selectedNodes?: TreeNode[]): TreeNode[];
/**
 * 合并节点数组到已有的树形结构中
 * @param {Array} treeArr - 现有的树形结构数组，每个元素包含一个 `id` 和 `pid` 属性
 * @param {Array} nodes - 要合并的节点数组，每个节点包含一个 `id` 和 `pid` 属性
 * @returns {Array} - 合并后的树形结构数组
 */
declare function mergeTrees(treeArr?: TreeNode[], nodes?: TreeNode[]): TreeNode[];
/**
 * 从树形结构中选择与给定选中节点相关的所有父节点和子节点
 * @param {Array} treeData - 树形结构数组，每个节点对象包含 `id` 和 `pid` 属性
 * @param {Array} selectedNodes - 选中的节点数组，每个节点对象包含 `id` 和 `pid` 属性
 * @returns {Array} - 包含选中节点、其父节点和子节点的数组
 */
declare function selectRelatedNodes(treeData: TreeNode[], selectedNodes?: TreeNode[]): TreeNode[];

declare const tree_buildTree: typeof buildTree;
declare const tree_mergeTrees: typeof mergeTrees;
declare const tree_removeNodesFromTree: typeof removeNodesFromTree;
declare const tree_searchTreeWithRelations: typeof searchTreeWithRelations;
declare const tree_selectRelatedNodes: typeof selectRelatedNodes;
declare const tree_treeToArr: typeof treeToArr;
declare const tree_updateTreeCheckStatus: typeof updateTreeCheckStatus;
declare const tree_updateTreeCheckStatusFlat: typeof updateTreeCheckStatusFlat;
declare namespace tree {
  export { tree_buildTree as buildTree, tree_mergeTrees as mergeTrees, tree_removeNodesFromTree as removeNodesFromTree, tree_searchTreeWithRelations as searchTreeWithRelations, tree_selectRelatedNodes as selectRelatedNodes, tree_treeToArr as treeToArr, tree_updateTreeCheckStatus as updateTreeCheckStatus, tree_updateTreeCheckStatusFlat as updateTreeCheckStatusFlat };
}

declare const _default: {
    tree: typeof tree;
    business: typeof business;
    common: typeof common;
};

// @ts-ignore
export = _default;
export { Mutex, buildTree, captureElementAsImage, createSelfCorrectingClock, createSelfCorrectingCountdown, desensitize, mergeTrees, removeNodesFromTree, safeJsonParse, searchTreeWithRelations, selectRelatedNodes, treeToArr, updateTreeCheckStatus, updateTreeCheckStatusFlat };