a2bei4-utils 1.0.0

package/dist/a2bei4.utils.esm.js

@@ -0,0 +1,1070 @@
+/**
+ * 使用 Fisher-Yates 算法对数组 **原地** 随机乱序。
+ * @template T
+ * @param {T[]} arr - 要乱序的数组
+ * @returns {T[]} 返回传入的同一数组实例（已乱序）
+ */
+function shuffle(arr) {
+    //  方式一：
+    // arr.sort(() => Math.random() - 0.5);
+    //  方式二：
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+}
+
+/**
+ * 将数组中的元素从 `fromIndex` 移动到 `toIndex`，**原地** 修改并返回该数组。
+ * @template T
+ * @param {T[]} arr - 要操作的数组
+ * @param {number} fromIndex - 原始下标
+ * @param {number} toIndex - 目标下标
+ * @returns {T[]} 返回传入的同一数组实例
+ */
+function moveItem(arr, fromIndex, toIndex) {
+    arr.splice(toIndex, 0, arr.splice(fromIndex, 1)[0]);
+}
+
+/**
+ * 视口尺寸对象。
+ * @typedef {Object} ViewportDimensions
+ * @property {number} w 视口宽度，单位像素。
+ * @property {number} h 视口高度，单位像素。
+ */
+
+/**
+ * 获取当前视口（viewport）的宽高。
+ *
+ * 兼容策略：
+ * 1. 优先使用 `window.innerWidth/innerHeight`（现代浏览器）。
+ * 2. 降级到 `document.documentElement.clientWidth/clientHeight`（IE9+ 及怪异模式）。
+ * 3. 最后降级到 `document.body.clientWidth/clientHeight`（IE6-8 怪异模式）。
+ *
+ * @returns {ViewportDimensions} 包含 `w`（宽度）和 `h`（高度）的对象，单位为像素。
+ *
+ * @example
+ * const { w, h } = getViewportSize();
+ * console.log(`视口尺寸：${w} × ${h}`);
+ */
+function getViewportSize() {
+    const d = document,
+        root = d.documentElement,
+        body = d.body;
+
+    return {
+        w: window.innerWidth || root.clientWidth || body.clientWidth,
+        h: window.innerHeight || root.clientHeight || body.clientHeight
+    };
+}
+
+/**
+ * 将当前页面 URL 的 query 部分解析成键值对对象。
+ *
+ * @returns {Record<string, string>} 所有查询参数组成的平凡对象
+ *                                   （同名 key 仅保留最后一项）
+ */
+function getAllSearchParams() {
+    const urlSearchParams = new URLSearchParams(location.search);
+    return Object.fromEntries(urlSearchParams.entries());
+}
+
+/**
+ * 根据 key 获取当前页面 URL 中的单个查询参数。
+ *
+ * @param {string} key - 要提取的参数名
+ * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`
+ */
+function getSearchParam(key) {
+    const params = getAllSearchParams();
+    return params[key];
+}
+
+//#region 数据类型判断
+
+/**
+ * 返回任意值的运行时类型字符串（小写形式）。
+ * 
+ * @param {*} obj 待检测的值
+ * @returns {keyof globalThis|"blob"|"file"|"formdata"|string} 小写类型名
+ */
+function getDataType(obj) {
+    return Object.prototype.toString
+        .call(obj)
+        .replace(/^\[object\s(\w+)\]$/, "$1")
+        .toLowerCase();
+}
+
+/**
+ * 判断值是否为原生 Blob（含 File）。
+ * 
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Blob}
+ */
+function isBlob(obj) {
+    return getDataType(obj) === "blob";
+}
+
+/**
+ * 判断值是否为**纯粹**的 Object（即 `{}` 或 `new Object()`，不含数组、null、自定义类等）。
+ * 
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Record<PropertyKey, any>}
+ */
+function isPlainObject(obj) {
+    return getDataType(obj) === "object";
+}
+
+/**
+ * 判断值是否为 Promise（含 Promise 子类）。
+ * 
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Promise<any>}
+ */
+function isPromise(obj) {
+    return getDataType(obj) === "promise";
+}
+
+/**
+ * 判断值是否为合法 Date 对象（含 Invalid Date 返回 false）。
+ *
+ * @param {*} t - 待检测值
+ * @returns {t is Date}
+ */
+function isDate(t) {
+    return getDataType(t) === "date";
+}
+
+/**
+ * 判断值是否为函数（含异步函数、生成器函数、类）。
+ * 
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Function}
+ */
+function isFunction(obj) {
+    return typeof obj === "function";
+}
+
+/**
+ * 判断值是否为**非空**字符串。
+ * 
+ * @param {*} obj - 待检测的值
+ * @returns {obj is string}
+ */
+function isNonEmptyString(obj) {
+    return getDataType(obj) === "string" && obj.length > 0;
+}
+
+//#endregion
+
+//#region 随机数据
+
+/**
+ * 在闭区间 [min, max] 内生成一个均匀分布的随机整数。
+ * 若 min > max 则自动交换。
+ *
+ * @param {number} min - 整数下界（包含）
+ * @param {number} max - 整数上界（包含）
+ * @returns {number}
+ * @throws {TypeError} 当 min 或 max 不是整数时抛出
+ */
+function randomIntInRange(min, max) {
+    if (!Number.isInteger(min) || !Number.isInteger(max)) {
+        throw new TypeError("Arguments must be integers");
+    }
+    if (min > max) [min, max] = [max, min];
+    // 注意加 1，否则 max 永远取不到；Math.floor 保证均匀
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * 随机生成一个汉字（可控制范围）。
+ *
+ * @param {boolean} [base=true]  - 是否启用基本区（0x4E00-0x9FA5）
+ * @param {boolean} [extA=false] - 是否启用扩展 A 区（0x3400-0x4DBF）
+ * @param {boolean} [extBH=false] - 是否启用扩展 B~H 区（0x20000-0x2EBEF，代理对）
+ * @returns {string} 单个汉字字符
+ * @throws {RangeError} 未启用任何区段时抛出
+ */
+function randomHan(base = true, extA = false, extBH = false) {
+    // 1. 收集已启用的“区段”
+    const ranges = [];
+    if (base) ranges.push({ min: 0x4e00, max: 0x9fa5, surrogate: false });
+    if (extA) ranges.push({ min: 0x3400, max: 0x4dbf, surrogate: false });
+    if (extBH) ranges.push({ min: 0x20000, max: 0x2ebef, surrogate: true });
+
+    if (ranges.length === 0) {
+        throw new RangeError("At least one range must be enabled");
+    }
+
+    // 2. 按总码位数抽号
+    const total = ranges.reduce((sum, r) => sum + (r.max - r.min + 1), 0);
+    let n = randomIntInRange(0, total - 1);
+
+    // 3. 定位落在哪个区段
+    for (const { min, max, surrogate } of ranges) {
+        const size = max - min + 1;
+        if (n < size) {
+            const code = min + n;
+            if (!surrogate) return String.fromCharCode(code);
+            // 代理对
+            const offset = code - 0x10000;
+            const hi = (offset >> 10) + 0xd800;
+            const lo = (offset & 0x3ff) + 0xdc00;
+            return String.fromCharCode(hi, lo);
+        }
+        n -= size;
+    }
+}
+
+/**
+ * 随机生成一个英文字母。
+ *
+ * @param {'lower'|'upper'} [type] - 指定大小写；留空则随机
+ * @returns {string} 单个字母
+ */
+function randomEnLetter(type) {
+    const lower = "abcdefghijklmnopqrstuvwxyz";
+    const upper = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+    const randomNum = randomIntInRange(0, 25);
+
+    switch (type) {
+        case "lower":
+            return lower[randomNum];
+        case "upper":
+            return upper[randomNum];
+        default:
+            return (Math.random() < 0.5 ? lower : upper)[randomNum];
+    }
+}
+
+/**
+ * 生成指定长度的随机“中英混合”字符串。
+ *
+ * @param {number} [len=1] - 目标长度（≥1，自动取整）
+ * @param {number} [zhProb=0.5] - 每个位置选择汉字的概率，默认 0.5
+ * @returns {string}
+ */
+function randomHanOrEn(len, zhProb = 0.5) {
+    len = Math.max(1, Math.floor(len));
+    const buf = [];
+    for (let i = 0; i < len; i++) {
+        buf.push(Math.random() < zhProb ? randomHan() : randomEnLetter());
+    }
+    return buf.join("");
+}
+
+//#endregion
+
+//#region 防抖节流
+
+/**
+ * 创建 debounced（防抖）函数。
+ * - 默认 trailing 触发；当 `leading=true` 时，首次调用或超过等待间隔会立即执行。
+ * - 支持手动取消。
+ *
+ * @template {(...args: any[]) => any} T
+ * @param {T} fn - 要防抖的原始函数
+ * @param {number} wait - 防抖等待时间（毫秒）
+ * @param {boolean} [leading=false] - 是否启用立即执行（leading edge）
+ * @returns {T & { cancel(): void }} 返回经过防抖包装的函数，并附带 `cancel` 方法
+ * @throws {TypeError} 当 `fn` 不是函数时抛出
+ */
+function debounce(fn, wait, leading = false) {
+    if (typeof fn !== "function") throw new TypeError("fn must be function");
+    wait = Math.max(0, Number(wait) || 0);
+    let timeoutId;
+    let lastCall = 0; // 0 表示从未调用过
+
+    function debounced(...args) {
+        const isFirst = lastCall === 0;
+        const isOverWait = Date.now() - lastCall >= wait;
+
+        clearTimeout(timeoutId);
+
+        // 首次调用 || 已达到等待间隔
+        if (leading && (isFirst || isOverWait)) {
+            lastCall = Date.now();
+            return fn.apply(this, args);
+        }
+
+        timeoutId = setTimeout(() => {
+            lastCall = Date.now();
+            fn.apply(this, args);
+        }, wait);
+    }
+
+    debounced.cancel = () => {
+        clearTimeout(timeoutId);
+        lastCall = 0; // 恢复初始状态
+    };
+
+    return debounced;
+}
+
+/**
+ * 创建 throttled（节流）函数。
+ * 支持 leading/trailing 边缘触发，可手动取消。
+ *
+ * @template {(...args: any[]) => any} T
+ * @param {T} fn - 要节流的原始函数
+ * @param {number} wait - 节流间隔（毫秒）
+ * @param {object} [options] - 配置项
+ * @param {boolean} [options.leading=true] - 是否在 leading 边缘执行
+ * @param {boolean} [options.trailing=true] - 是否在 trailing 边缘执行
+ * @returns {T & { cancel(): void }} 返回经过节流包装的函数，并附带 `cancel` 方法
+ * @throws {TypeError} 当 `fn` 不是函数时抛出
+ */
+function throttle(fn, wait, { leading = true, trailing = true } = {}) {
+    if (typeof fn !== "function") throw new TypeError("fn must be function");
+    wait = Math.max(0, Number(wait) || 0);
+
+    let timeoutId = null,
+        lastCall = 0;
+
+    function throttled(...args) {
+        const remaining = wait - (Date.now() - lastCall);
+
+        if (leading && (lastCall === 0 || remaining <= 0)) {
+            lastCall = Date.now();
+            fn.apply(this, args);
+        } else if (trailing && !timeoutId) {
+            timeoutId = setTimeout(
+                () => {
+                    timeoutId = null;
+                    lastCall = Date.now();
+                    fn.apply(this, args);
+                },
+                remaining > 0 ? remaining : wait
+            );
+        }
+    }
+
+    throttled.cancel = () => {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+        lastCall = 0;
+    };
+
+    return throttled;
+}
+
+//#endregion
+
+/**
+ * 利用 JSON 序列化/反序列化实现**深拷贝**。
+ * 注意：会丢失 `undefined`、函数、循环引用、特殊包装对象等。
+ *
+ * @template T
+ * @param {T} obj - 待拷贝的 JSON 兼容值
+ * @returns {T} 深拷贝后的值
+ */
+function deepCloneByJSON(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+
+/**
+ * **安全**地将源对象中**已存在**的属性赋值到目标对象。
+ * 不会新增键，也不会复制原型链上的属性。
+ *
+ * @template {Record<PropertyKey, any>} T
+ * @param {T} target - 目标对象（将被就地修改）
+ * @param {...Partial<T>} sources - 一个或多个源对象
+ * @returns {T} 修改后的目标对象（即第一个参数本身）
+ *
+ * @example
+ * const defaults = { a: 1, b: 2 };
+ * assignExisting(defaults, { a: 9, c: 99 }); // defaults 变为 { a: 9, b: 2 }
+ */
+function assignExisting(target, ...sources) {
+    sources.forEach((source) => {
+        Object.keys(source).forEach((key) => {
+            if (target.hasOwnProperty(key)) {
+                target[key] = source[key];
+            }
+        });
+    });
+    return target;
+}
+
+/**
+ * 提取任意函数（含箭头函数、普通函数、async、class 构造器）的形参名称列表。
+ * 通过源码正则解析，不支持解构参数、默认参数、剩余参数等复杂语法；
+ * 若出现上述场景将返回空数组或部分名称。
+ *
+ * @param {Function} fn - 目标函数
+ * @returns {string[]} 按声明顺序排列的参数名数组；解析失败时返回空数组
+ *
+ * @example
+ * getFunctionArgNames(function (a, b) {})        // ["a", "b"]
+ * getFunctionArgNames((foo, bar) => {})          // ["foo", "bar"]
+ * getFunctionArgNames(async function x({a} = {}) {}) // [] （解构无法识别）
+ */
+function getFunctionArgNames(fn) {
+    const FN_ARG_SPLIT = /,/,
+        FN_ARG = /^\s*(_?)(\S+?)\1\s*$/,
+        FN_ARGS = /^[^(]*\(\s*([^)]*)\)/m,
+        ARROW_ARG = /^([^(]+?)=>/,
+        STRIP_COMMENTS = /((\/\/.*$)|(\/\*[\s\S]*?\*\/))/gm;
+
+    const fnText = Function.prototype.toString.call(fn).replace(STRIP_COMMENTS, "");
+    const argDecl = fnText.match(ARROW_ARG) || fnText.match(FN_ARGS);
+    const retArgNames = [];
+    [].forEach.call(argDecl[1].split(FN_ARG_SPLIT), function (arg) {
+        arg.replace(FN_ARG, function (all, underscore, name) {
+            retArgNames.push(name);
+        });
+    });
+    return retArgNames;
+}
+
+/**
+ * 将 Blob（或 File）读取为文本，并可选择自动执行 `JSON.parse`。
+ * 当 `isParse=true` 且内容非法 JSON 时，会回退为返回原始文本。
+ *
+ * @param {Blob} blob - 待读取的 Blob/File 对象
+ * @param {boolean} [isParse=true] - 是否尝试将结果按 JSON 解析
+ * @returns {Promise<string | any>} 解析后的 JSON 对象或原始文本
+ *
+ * @example
+ * const json = await readBlobAsText(blob);        // 自动 JSON.parse
+ * const text = await readBlobAsText(blob, false); // 仅返回文本
+ */
+function readBlobAsText(blob, isParse = true) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = (evt) => {
+            const result = evt.target.result;
+            if (isParse) {
+                try {
+                    resolve(JSON.parse(result));
+                } catch (error) {
+                    console.error(error);
+                    resolve(result);
+                }
+            } else {
+                resolve(result);
+            }
+        };
+        reader.onerror = reject;
+        reader.readAsText(blob);
+    });
+}
+
+/**
+ * 将任意值安全转换为 Date 对象。
+ * - 数字／数字字符串：视为时间戳
+ * - 字符串：尝试按 ISO/RFC 格式解析
+ * - 对象：优先 valueOf()，再 toString()
+ * - null / undefined / 无效值：返回 null
+ *
+ * @param {*} val - 待转换值
+ * @returns {Date | null} 有效 Date 或 null
+ */
+function toDate(val) {
+    if (val == null) return null; // null / undefined
+    if (val instanceof Date) return isNaN(val) ? null : val; // 已是 Date，但需排除 Invalid Date
+
+    // 1. 数字或数字字符串 → 时间戳
+    if (typeof val === "number" || (typeof val === "string" && /^-?\d+(\.\d+)?$/.test(val.trim()))) {
+        const d = new Date(+val);
+        return isNaN(d) ? null : d;
+    }
+
+    // 2. 标准 ISO 8601 / RFC 2825 等合法字符串
+    if (typeof val === "string") {
+        const d = new Date(val);
+        return isNaN(d) ? null : d; // 非法格式返回 null
+    }
+
+    // 3. 对象带 valueOf / toString
+    if (typeof val === "object") {
+        // 优先调用 valueOf（期望返回数字时间戳）
+        const prim = val.valueOf ? val.valueOf() : Object.prototype.valueOf.call(val);
+        if (typeof prim === "number" && !isNaN(prim)) {
+            const d = new Date(prim);
+            return isNaN(d) ? null : d;
+        }
+        // 兜底用字符串
+        const str = val.toString ? val.toString() : String(val);
+        const d = new Date(str);
+        return isNaN(d) ? null : d;
+    }
+
+    // 4. 其余情况
+    return null;
+}
+
+/**
+ * 在闭区间 [date1, date2] 内随机生成一个日期（含首尾）。
+ * 若顺序相反则自动交换。
+ *
+ * @param {Date} date1 - 起始日期
+ * @param {Date} date2 - 结束日期
+ * @returns {Date} 随机日期
+ */
+function randomDateInRange(date1, date2) {
+    let v1 = date1.getTime(),
+        v2 = date2.getTime();
+    if (v1 > v2) [v1, v2] = [v2, v1];
+    return new Date(v1 + Math.floor(Math.random() * (v2 - v1 + 1)));
+}
+
+/**
+ * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
+ *
+ * @param {string|number|Date} originalTime - 原始时间（可转 Date 的任意值）
+ * @param {Date} [currentTime=new Date()] - 基准时间，默认当前
+ * @returns {{days:number,hours:string,minutes:string,seconds:string}}
+ */
+function calcTimeDifference(originalTime, currentTime = new Date()) {
+    // 计算时间差（毫秒）
+    const diffMs = currentTime - new Date(originalTime);
+
+    // 转换为天、小时、分钟、秒
+    const diffSeconds = Math.floor(diffMs / 1000);
+    const days = Math.floor(diffSeconds / (3600 * 24));
+    const hours = Math.floor((diffSeconds % (3600 * 24)) / 3600);
+    const minutes = Math.floor((diffSeconds % 3600) / 60);
+    const seconds = diffSeconds % 60;
+
+    const padZero = (num) => String(num).padStart(2, "0");
+
+    return {
+        days,
+        hours: padZero(hours),
+        minutes: padZero(minutes),
+        seconds: padZero(seconds)
+    };
+}
+
+/**
+ * 将总秒数格式化成人类可读的时间段文本。
+ * 固定进制：1 年=365 天，1 月=30 天。
+ *
+ * @param {number} totalSeconds - 非负总秒数
+ * @param {object} [options] - 格式化选项
+ * @param {Partial<{year:string,month:string,day:string,hour:string,minute:string,second:string}>} [options.labels] - 各单位的自定义文本
+ * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.maxUnit] - 最大输出单位
+ * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.minUnit] - 最小输出单位
+ * @param {boolean} [options.showZero] - 是否强制显示 0 秒
+ * @returns {string} 拼接后的时长文本，如“1天 02小时 30分钟”
+ * @throws {TypeError} 当 totalSeconds 为非数字或负数时抛出
+ */
+function formatDuration(totalSeconds, options = {}) {
+    if (typeof totalSeconds !== "number" || totalSeconds < 0 || !isFinite(totalSeconds)) {
+        throw new TypeError("totalSeconds 必须是非负数字");
+    }
+
+    // 1. 默认中文单位
+    const DEFAULT_LABELS = {
+        year: "年",
+        month: "月",
+        day: "天",
+        hour: "小时",
+        minute: "分钟",
+        second: "秒"
+    };
+
+    // 2. 固定进制表（秒）
+    const UNIT_TABLE = [
+        { key: "year", seconds: 365 * 24 * 3600 },
+        { key: "month", seconds: 30 * 24 * 3600 },
+        { key: "day", seconds: 24 * 3600 },
+        { key: "hour", seconds: 3600 },
+        { key: "minute", seconds: 60 },
+        { key: "second", seconds: 1 }
+    ];
+
+    // 3. 合并用户自定义文本
+    const labels = Object.assign({}, DEFAULT_LABELS, options.labels);
+
+    // 4. 根据 maxUnit / minUnit 截取
+    let start = 0,
+        end = UNIT_TABLE.length;
+    if (options.maxUnit) {
+        const idx = UNIT_TABLE.findIndex((u) => u.key === options.maxUnit);
+        if (idx !== -1) start = idx;
+    }
+    if (options.minUnit) {
+        const idx = UNIT_TABLE.findIndex((u) => u.key === options.minUnit);
+        if (idx !== -1) end = idx + 1;
+    }
+    const units = UNIT_TABLE.slice(start, end);
+    if (!units.length) units.push(UNIT_TABLE[UNIT_TABLE.length - 1]); // 保底秒
+
+    // 5. 逐级计算
+    let rest = Math.floor(totalSeconds);
+    const parts = [];
+
+    for (const { key, seconds } of units) {
+        const val = Math.floor(rest / seconds);
+        rest %= seconds;
+
+        const shouldShow = val > 0 || (options.showZero && key === "second");
+        if (shouldShow || (parts.length === 0 && rest === 0)) {
+            parts.push(`${val}${labels[key]}`);
+        }
+    }
+
+    // 6. 兜底
+    if (parts.length === 0) {
+        parts.push(`0${labels[units[units.length - 1].key]}`);
+    }
+
+    return parts.join("");
+}
+
+/**
+ * 快捷调用 {@link formatDuration}，最大单位到“天”。
+ *
+ * @param {number} totalSeconds
+ * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
+ * @returns {string}
+ */
+function formatDurationMaxDay(totalSeconds, options = {}) {
+    return formatDuration(totalSeconds, { ...options, maxUnit: "day" });
+}
+
+/**
+ * 快捷调用 {@link formatDuration}，最大单位到“小时”。
+ *
+ * @param {number} totalSeconds
+ * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
+ * @returns {string}
+ */
+function formatDurationMaxHour(totalSeconds, options = {}) {
+    return formatDuration(totalSeconds, { ...options, maxUnit: "hour" });
+}
+
+/**
+ * 通过动态创建 `<a>` 标签触发浏览器下载。
+ *
+ * @param {string} url - 任意可下载地址（同源或允许跨域）
+ * @param {string} [fileName] - 保存到本地的文件名；不传时使用时间戳
+ */
+function downloadByUrl(url, fileName) {
+    const a = document.createElement("a");
+    a.style.display = "none";
+    a.rel = "noopener";
+    a.href = url;
+    a.download = fileName || Date.now();
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+}
+
+/**
+ * 把 Blob 转成临时 URL 并触发下载，下载完成后立即释放内存。
+ *
+ * @param {Blob} blob - 待下载的 Blob（含 File）
+ * @param {string} [fileName] - 保存到本地的文件名
+ */
+function downloadByBlob(blob, fileName) {
+    const url = URL.createObjectURL(blob);
+    downloadByUrl(url, fileName);
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+/**
+ * 将任意数据包装成 Blob 并下载。
+ *
+ * @param {string | ArrayBufferView | ArrayBuffer | Blob} data - 要写入文件的数据
+ * @param {string} [fileName] - 保存到本地的文件名
+ * @param {string} [mimeType] - MIME 类型；默认 `application/octet-stream`
+ */
+function downloadByData(data, fileName, mimeType = "application/octet-stream") {
+    downloadByBlob(new Blob([data], { type: mimeType }), fileName);
+}
+
+/**
+ * 快捷下载 Excel 文件（MIME 已固定）。
+ *
+ * @param {string | ArrayBufferView | ArrayBuffer | Blob} data - Excel 二进制或字符串内容
+ * @param {string} [fileName] - 保存到本地的文件名
+ */
+function downloadExcel(data, fileName) {
+    downloadByData(data, fileName, "application/vnd.ms-excel");
+}
+
+/**
+ * 快捷下载 JSON 文件（MIME 已固定）。
+ * 若传入非字符串数据，会自行 `JSON.stringify`。
+ *
+ * @param {any} data - 要序列化的 JSON 数据
+ * @param {string} [fileName] - 保存到本地的文件名
+ */
+function downloadJSON(data, fileName) {
+    // downloadByData(typeof data === "string" ? data : JSON.stringify(data, null, 4), fileName, "application/json");
+    downloadByData(data, fileName, "application/json");
+}
+
+/**
+ * 简单、高性能的通用事件总线。
+ * - 支持命名空间事件
+ * - 支持一次性监听器
+ * - 返回唯一 flag，用于精确卸载
+ * - emit 时可选自定义 this 指向
+ */
+class MyEvent {
+    constructor() {
+        this.evtPool = new Map();
+    }
+
+    /**
+     * 注册事件监听器。
+     * @param {string} name - 事件名
+     * @param {Function} fn - 回调函数
+     * @returns {string} flag - 唯一标识，用于 off
+     */
+    on(name, fn) {
+        let flag = Date.now() + "_" + parseInt(Math.random() * 1e8);
+        const evtItem = {
+            flag,
+            fn
+        };
+        if (this.evtPool.has(name)) {
+            this.evtPool.get(name).push(evtItem);
+        } else {
+            this.evtPool.set(name, [evtItem]);
+        }
+        return flag;
+    }
+
+    /**
+     * 注册一次性监听器，触发后自动移除。
+     * @param {string} name - 事件名
+     * @param {Function} fn - 回调函数
+     * @returns {string} flag - 唯一标识
+     */
+    once(name, fn) {
+        const _this = this;
+        let wrapper;
+        wrapper = function (data) {
+            _this.off(name, wrapper);
+            fn.call(this, data);
+        };
+        return this.on(name, wrapper);
+    }
+
+    /**
+     * 移除指定事件监听器。
+     * @param {string} name - 事件名
+     * @param {Function|string} fnOrFlag - 回调函数或 flag
+     */
+    off(name, fnOrFlag) {
+        if (!this.evtPool.has(name)) return;
+        const evtItems = this.evtPool.get(name);
+        const filtered = evtItems.filter((item) => item.fn !== fnOrFlag && item.flag !== fnOrFlag);
+        if (filtered.length === 0) {
+            this.evtPool.delete(name);
+        } else {
+            this.evtPool.set(name, filtered);
+        }
+    }
+
+    /**
+     * 触发事件（同步执行）。
+     * @param {string} name - 事件名
+     * @param {*} [data] - 任意载荷
+     * @param {*} [fnThis] - 回调内部 this 指向，默认 undefined
+     */
+    emit(name, data, fnThis) {
+        if (!this.evtPool.has(name)) return;
+        const evtItems = this.evtPool.get(name);
+        evtItems.forEach((item) => {
+            try {
+                item.fn.call(fnThis, data);
+            } catch (err) {
+                console.error(`Error in event listener for "${name}":`, err);
+            }
+        });
+    }
+}
+
+/**
+ * 跨页通信插件：通过 localStorage + storage 事件将当前实例的 emit 广播到其他同源页面。
+ * 支持节流、命名空间隔离。
+ */
+const MyEvent_CrossPagePlugin = (() => {
+    const INSTALLED = new WeakSet(); // 防止重复安装
+
+    return {
+        /**
+         * 为指定 MyEvent 实例安装跨页插件。
+         * @param {MyEvent} bus - 事件总线实例
+         * @param {Options} [opts] - 配置项
+         */
+        install(bus, opts = {}) {
+            if (INSTALLED.has(bus)) return;
+            INSTALLED.add(bus);
+
+            const ns = `___my-event-cross-page-${opts.namespace || "default"}___`;
+            const delay = opts.throttle || 16;
+            let last = 0;
+
+            //  1、重写 emit
+            const rawEmit = bus.emit;
+            bus.emit = function (name, data, fnThis) {
+                rawEmit.call(bus, name, data, fnThis); // 本地先执行
+                const now = Date.now();
+                if (now - last < delay) return;
+                last = now;
+                const key = ns + name;
+                try {
+                    localStorage.setItem(key, JSON.stringify({ name, data, ts: now }));
+                    localStorage.removeItem(key); // 触发 storage 事件
+                } catch (e) {}
+            };
+
+            //  2、监听其他页广播
+            function onStorageHandler(e) {
+                if (!e.key || !e.key.startsWith(ns)) return;
+                let payload;
+                try {
+                    payload = JSON.parse(e.newValue || "{}");
+                } catch {
+                    return;
+                }
+                if (!payload.ts || payload.ts <= last) return;
+                rawEmit.call(bus, e.key.slice(ns.length), payload.data); // 仅本地
+            }
+            addEventListener("storage", onStorageHandler);
+
+            //  3、保存卸载器
+            bus._uninstallCrossPage = () => {
+                removeEventListener("storage", onStorageHandler);
+                bus.emit = rawEmit;
+                INSTALLED.delete(bus);
+            };
+        },
+
+        /**
+         * 卸载插件，恢复原始 emit 并停止监听。
+         * @param {MyEvent} bus - 事件总线实例
+         */
+        uninstall(bus) {
+            if (typeof bus._uninstallCrossPage === "function") bus._uninstallCrossPage();
+        }
+    };
+})();
+
+/**
+ * 生成 RFC4122 版本 4 的 GUID/UUID。
+ * 收集来源：《基于mvc的javascript web富应用开发》 书中介绍是Robert Kieffer写的，还留了网址 http://goo.gl/0b0hu ，但实际访问不了。
+ * 格式：`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
+ *
+ * @returns {string} 36 位大写 GUID
+ *
+ * @example
+ * // A2E0F340-6C3B-4D7F-B8C1-1E4F6A8B9C0D
+ * console.log(getGUID())
+ */
+function getGUID() {
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        let r = (Math.random() * 16) | 0,
+            v = c == "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16).toUpperCase();
+    });
+}
+
+/**
+ * 分布式短 ID 生成器。
+ * 格式：`${timestamp}${flag}${serial}`，其中：
+ * - timestamp：毫秒级时间戳
+ * - flag：客户端标识串（自定义）
+ * - serial：同一毫秒内的序号，左补零到固定长度
+ */
+class MyId {
+    #ts = Date.now(); //	时间戳
+    #sn = 0; //	序号（保证同一客户端之间的唯一项）
+    #flag = ""; //	客户端标识（保证不同客户端之间的唯一项）
+    #len = 5; //	序号位长度（我的电脑测试，同一时间戳内可以for循环执行了1000次左右，没有一次超过3k，所以5位应该够用了）
+    //  测试代码
+    //  let obj = {[Date.now()]:[]}; try { for (let i = 0; i < 100000; i++) { obj[Date.now()].push(i); } } catch { console.log(obj[Object.getOwnPropertyNames(obj)[0]].length); }
+
+    /**
+     * @param {object} [option]
+     * @param {string} [option.flag] - 客户端标识，默认空串
+     * @param {number} [option.len=5] - 序号位长度（位数），安全范围 ≥0
+     */
+    constructor(option = {}) {
+        if (option) {
+            if (typeof option.flag === "string") {
+                this.#flag = option.flag;
+            }
+            if (Number.isSafeInteger(option.len) && len >= 0) {
+                this.#len = option.len;
+            }
+        }
+    }
+
+    /**
+     * 生成下一个全局唯一字符串 ID。
+     * 同一毫秒序号自动递增；序号溢出时会在控制台警告。
+     * @returns {string}
+     */
+    nextId() {
+        let ts = Date.now();
+        if (ts === this.#ts) {
+            this.#sn++;
+            if (this.#sn >= 10 ** this.#len) {
+                console.log("长度不够用了！！！");
+            }
+        } else {
+            this.#sn = 0;
+            this.#ts = ts;
+        }
+        return ts.toString() + this.#flag + this.#sn.toString().padStart(this.#len, "0");
+    }
+}
+
+/**
+ * 基于 `setTimeout` 的“间隔循环”定时器。
+ * 每次任务执行完成后才计算下一次间隔，避免任务堆积。
+ */
+class IntervalTimer {
+    
+    /**
+     * 创建定时器实例。
+     * @param {() => void} fn - 每次间隔要执行的业务函数
+     * @param {number} [ms=1000] - 间隔时间（毫秒）
+     * @throws {TypeError} 当 `fn` 不是函数时抛出
+     */
+    constructor(fn, ms = 1000) {
+        if (typeof fn !== "function") {
+            throw new TypeError("IntervalTimer: 必须传入一个函数");
+        }
+        this._fn = fn;
+        this._ms = ms;
+        this._timerId = null;
+    }
+
+    /**
+     * 启动定时器；若已启动则先停止再重新启动。
+     * 首次执行会立即触发。
+     */
+    start() {
+        this.stop();
+        const loop = () => {
+            this._fn(); // 执行业务
+            this._timerId = setTimeout(loop, this._ms);
+        };
+        loop(); // 立即执行第一次
+    }
+
+    /**
+     * 停止定时器。
+     */
+    stop() {
+        if (this._timerId !== null) {
+            clearTimeout(this._timerId);
+            this._timerId = null;
+        }
+    }
+
+    /**
+     * 查询定时器是否正在运行。
+     * @returns {boolean}
+     */
+    isRunning() {
+        return this._timerId !== null;
+    }
+}
+
+/**
+ * 把嵌套树拍平成 `{ [id]: node }` 映射，同时把原 `children` 置为 `null`。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {T[]} data - 嵌套树森林
+ * @param {string} [idKey='id'] - 主键字段
+ * @param {string} [childrenKey='children'] - 子节点字段
+ * @returns {Record<string, T & { [k in typeof childrenKey]: null }>} id→节点的映射表
+ */
+function nestedTree2IdMap(data, idKey = "id", childrenKey = "children") {
+    const retObj = {};
+    function fn(nodes) {
+        if (Array.isArray(nodes) && nodes.length > 0) {
+            nodes.forEach((node) => {
+                retObj[node[idKey]] = { ...node };
+                retObj[node[idKey]][childrenKey] = null;
+
+                fn(node[childrenKey]);
+            });
+        }
+    }
+    fn(data);
+    return retObj;
+}
+
+/**
+ * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {T[]} nodes - 扁平节点列表（必须包含 id / parentId）
+ * @param {number | string} [parentId=0] - 根节点标识值
+ * @param {Object} [opts] - 字段映射配置
+ * @param {string} [opts.idKey='id'] - 节点主键
+ * @param {string} [opts.parentKey='parentId'] - 父节点外键
+ * @param {string} [opts.childrenKey='children'] - 存放子节点的字段
+ * @returns {(T & { [k in typeof childrenKey]: T[] })[]} 嵌套树森林
+ */
+function flatCompleteTree2NestedTree(nodes, parentId = 0, { idKey = "id", parentKey = "parentId", childrenKey = "children" } = {}) {
+    const map = new Map(); // id -> node
+    const items = []; // 多根森林
+
+    // 1. 初始化：保证每个节点都有 children，并存入 map
+    for (const item of nodes) {
+        const node = { ...item, [childrenKey]: [] };
+        map.set(item[idKey], node);
+    }
+
+    // 2. 建立父子关系
+    for (const item of nodes) {
+        const node = map.get(item[idKey]);
+        const parentIdVal = item[parentKey];
+
+        if (parentIdVal === parentId) {
+            // 根层
+            items.push(node);
+        } else {
+            // 非根层：找到父节点，把自己挂上去
+            const parent = map.get(parentIdVal);
+            if (parent) parent[childrenKey].push(node);
+            // 如果 parent 不存在，说明数据不完整，可自定义处理
+        }
+    }
+
+    return items;
+}
+
+/**
+ * 在嵌套树中按 `id` 递归查找节点，并返回其指定属性值。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {string | number} id - 要查找的 id
+ * @param {T[]} arr - 嵌套树森林
+ * @param {string} [resultKey='name'] - 需要返回的字段
+ * @param {string} [idKey='id'] - 主键字段
+ * @param {string} [childrenKey='children'] - 子节点字段
+ * @returns {any} 找到的值；未找到返回 `undefined`
+ */
+const findObjAttrValueById = function findObjAttrValueByIdFn(id, arr, resultKey = "name", idKey = "id", childrenKey = "children") {
+    if (Array.isArray(arr) && arr.length > 0) {
+        for (let i = 0; i < arr.length; i++) {
+            const item = arr[i];
+            if (item[idKey]?.toString() === id?.toString()) {
+                return item[resultKey];
+            } else if (Array.isArray(item[childrenKey]) && item[childrenKey].length > 0) {
+                const result = findObjAttrValueByIdFn(id, item[childrenKey], resultKey, idKey, childrenKey);
+                if (result) {
+                    return result;
+                }
+            }
+        }
+    }
+};
+
+export { IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };
+//# sourceMappingURL=a2bei4.utils.esm.js.map