a2bei4-utils 1.0.2 → 1.0.4

package/dist/a2bei4.utils.umd.js

@@ -4,1868 +4,2098 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.a2bei4Utils = {}));
 })(this, (function (exports) { 'use strict';
 
-    /**
-     * 使用 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;
+    /**
+     * 使用 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]);
     }
 
-    /**
-     * 将数组中的元素从 `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]);
+    const AudioStreamResamplerProcessorCode = `
+class AudioStreamResamplerProcessor extends AudioWorkletProcessor {
+    constructor(options) {
+        super();
+        const config = options.processorOptions || {};
+        this.targetSampleRate = config.targetSampleRate || 16000;
+        this.sourceSampleRate = sampleRate;
+        this.downsampleRatio = this.sourceSampleRate / this.targetSampleRate;
+
+        // 16000Hz 用 60ms chunk (960 samples)，其他用 1024
+        this.chunkSize = this.targetSampleRate === 16000 ? 960 : 1024;
+
+        const sourceBufferSize = config.sourceBufferSize || 16384; // ~340ms @48kHz
+        const pcmBufferSize = config.pcmBufferSize || (this.chunkSize * 10); // 更大缓冲，减少溢出概率
+
+        this.sourceBuffer = new Float32Array(sourceBufferSize);
+        this.sourceBufferLength = 0;
+
+        this.pcmBuffer = new Int16Array(pcmBufferSize);
+        this.pcmBufferIndex = 0;
+    }
+
+    process(inputs, outputs, parameters) {
+        const input = inputs[0];
+        if (!input || input.length === 0 || input[0].length === 0) return true;
+        const inputChannel = input[0];
+
+        // 1. 写入源缓冲区（溢出时覆盖最旧数据）
+        const newLength = this.sourceBufferLength + inputChannel.length;
+        if (newLength > this.sourceBuffer.length) {
+            const overflow = newLength - this.sourceBuffer.length;
+            this.sourceBuffer.copyWithin(0, overflow);
+            this.sourceBufferLength = this.sourceBuffer.length - inputChannel.length;
+        }
+        this.sourceBuffer.set(inputChannel, this.sourceBufferLength);
+        this.sourceBufferLength += inputChannel.length;
+
+        // 2. 计算可降采样样本数
+        const availableOutputSamples = Math.floor(this.sourceBufferLength / this.downsampleRatio);
+        if (availableOutputSamples === 0) return true;
+
+        // 3. 线性插值降采样
+        const downsampled = new Float32Array(availableOutputSamples);
+        for (let i = 0; i < availableOutputSamples; i++) {
+            const srcIndex = i * this.downsampleRatio;
+            const srcIndexInt = Math.floor(srcIndex);
+            const fraction = srcIndex - srcIndexInt;
+            const val0 = this.sourceBuffer[srcIndexInt];
+            const val1 = srcIndexInt + 1 < this.sourceBufferLength ? this.sourceBuffer[srcIndexInt + 1] : val0;
+            downsampled[i] = val0 + (val1 - val0) * fraction;
+        }
+
+        // 4. Float32 → Int16 PCM
+        const pcmData = this.floatTo16BitPCM(downsampled);
+
+        // 5. 写入 PCM 缓冲区（空间不足时直接覆盖最旧，缓冲区足够大基本不会触发）
+        if (this.pcmBufferIndex + pcmData.length > this.pcmBuffer.length) {
+            // 简单策略：从头覆盖（丢弃最旧数据）
+            this.pcmBufferIndex = 0;
+        }
+        this.pcmBuffer.set(pcmData, this.pcmBufferIndex);
+        this.pcmBufferIndex += pcmData.length;
+
+        // 6. 发送所有完整的 chunk（关键：复制到新数组再转移）
+        while (this.pcmBufferIndex >= this.chunkSize) {
+            // 方法1：推荐，使用 slice（隐式复制到新 ArrayBuffer）
+            const chunk = this.pcmBuffer.slice(0, this.chunkSize);
+
+            // 方法2：等价写法
+            // const chunk = new Int16Array(this.pcmBuffer.subarray(0, this.chunkSize));
+
+            this.port.postMessage(chunk, [chunk.buffer]); // 转移新缓冲区，安全！
+
+            // 移动剩余数据到开头
+            this.pcmBuffer.copyWithin(0, this.chunkSize, this.pcmBufferIndex);
+            this.pcmBufferIndex -= this.chunkSize;
+        }
+
+        // 7. 清理已消费的源数据
+        const consumedSrc = Math.floor(availableOutputSamples * this.downsampleRatio + 0.5); // 四舍五入更准
+        if (consumedSrc > 0) {
+            this.sourceBuffer.copyWithin(0, consumedSrc, this.sourceBufferLength);
+            this.sourceBufferLength -= consumedSrc;
+        }
+
+        return true;
+    }
+
+    floatTo16BitPCM(input) {
+        const output = new Int16Array(input.length);
+        for (let i = 0; i < input.length; i++) {
+            const s = Math.max(-1, Math.min(1, input[i]));
+            output[i] = s < 0 ? s * 0x8000 : s * 0x7FFF;
+        }
+        return output;
+    }
+}
+
+registerProcessor('audio-stream-resampler-processor', AudioStreamResamplerProcessor);
+`;
+
+    /**
+     * 浏览器端实时音频流重采样器。
+     * 基于 AudioWorklet 将麦克风/媒体流转换为 16 kHz、16-bit、单声道 PCM，
+     * 并通过回调逐块输出，可选保存完整 PCM 用于后续合并。
+     */
+    class AudioStreamResampler {
+        /**
+         * @param {object} config
+         * @param {function(Int16Array)} config.onData - 收到一个 chunk PCM 数据的回调
+         * @param {function(string, string)} [config.onStateChange] - 状态变化回调
+         * @param {object} [config.processorOptions] - 传递给 AudioWorklet 的选项
+         * @param {boolean} [config.saveFullPcm=false] - 是否在内部保存所有 PCM 用于 stop 时合并（长时间录音建议关闭）
+         */
+        constructor(config) {
+            this.onData = config.onData || (() => {});
+            this.onStateChange = config.onStateChange || (() => {});
+            this.processorOptions = config.processorOptions || {};
+            this.saveFullPcm = config.saveFullPcm ?? false;
+
+            this.audioContext = null;
+            this.workletNode = null;
+            this.source = null;
+            this.workletUrl = null;
+            this.fullPcmData = this.saveFullPcm ? [] : null;
+
+            this.isInitialized = false;
+            this.isProcessing = false;
+        }
+
+        /**
+         * 初始化 AudioContext 并加载 AudioWorklet。
+         * 完成后状态变为 `"ready"`。
+         */
+        async init() {
+            this.onStateChange("initializing", "正在初始化音频环境...");
+            try {
+                this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
+
+                const blob = new Blob([AudioStreamResamplerProcessorCode], { type: "application/javascript" });
+                this.workletUrl = URL.createObjectURL(blob);
+                await this.audioContext.audioWorklet.addModule(this.workletUrl);
+
+                this.workletNode = new AudioWorkletNode(this.audioContext, "audio-stream-resampler-processor", {
+                    processorOptions: this.processorOptions
+                });
+
+                this.workletNode.port.onmessage = (event) => {
+                    const chunk = event.data; // Int16Array
+                    this.onData(chunk);
+                    if (this.saveFullPcm) {
+                        this.fullPcmData.push(chunk);
+                    }
+                };
+
+                this.isInitialized = true;
+                this.onStateChange("ready", "音频环境已就绪");
+            } catch (err) {
+                console.error("AudioStreamResampler init error:", err);
+                this.onStateChange("error", `初始化失败: ${err.message}`);
+            }
+        }
+
+        /**
+         * 绑定媒体流，开始实时处理。
+         * @param {MediaStream} stream - 通过 getUserMedia 或其他方式获得的流
+         */
+        setMediaStream(stream) {
+            if (!this.isInitialized) {
+                console.error("请先调用 init()");
+                return;
+            }
+
+            if (this.source) {
+                this.source.disconnect();
+            }
+
+            this.source = this.audioContext.createMediaStreamSource(stream);
+            this.source.connect(this.workletNode);
+            // workletNode 默认连接到 destination，可选断开以静音
+            // this.workletNode.connect(this.audioContext.destination);
+
+            this.isProcessing = true;
+            this.onStateChange("processing", "正在处理音频流...");
+        }
+
+        /**
+         * 停止处理并释放资源。
+         * @param {(fullPcm: Int16Array) => void} [callback] - 若构造时 `saveFullPcm=true`，会把合并后的完整 PCM 通过此回调传出
+         */
+        stop(callback) {
+            if (!this.isProcessing) return;
+
+            this.onStateChange("stopping", "正在停止...");
+
+            if (this.source) {
+                this.source.disconnect();
+                this.source = null;
+            }
+
+            this._cleanup();
+
+            this.onStateChange("stopped", "已停止");
+
+            if (this.saveFullPcm && callback && typeof callback === "function") {
+                const totalLength = this.fullPcmData.reduce((sum, chunk) => sum + chunk.length, 0);
+                const combined = new Int16Array(totalLength);
+                let offset = 0;
+                for (const chunk of this.fullPcmData) {
+                    combined.set(chunk, offset);
+                    offset += chunk.length;
+                }
+                callback(combined);
+            }
+        }
+
+        _cleanup() {
+            if (this.workletNode) {
+                this.workletNode.disconnect();
+                this.workletNode.port.close();
+                this.workletNode = null;
+            }
+            if (this.audioContext && this.audioContext.state !== "closed") {
+                this.audioContext.close();
+                this.audioContext = null;
+            }
+            if (this.workletUrl) {
+                URL.revokeObjectURL(this.workletUrl);
+                this.workletUrl = null;
+            }
+
+            this.isProcessing = false;
+            this.isInitialized = false;
+            if (this.fullPcmData) {
+                this.fullPcmData.length = 0;
+            }
+        }
+    }
+
+    /**
+     * 将 16-bit 单声道 PCM 数据封装成标准 WAV Blob。
+     *
+     * @param {Int16Array} pcmData - PCM 采样数据
+     * @param {number} [sampleRate=16000] - 采样率，默认 16 kHz
+     * @returns {Blob} audio/wav Blob
+     */
+    function pcmToWavBlob(pcmData, sampleRate = 16000) {
+        const length = pcmData.length;
+        const buffer = new ArrayBuffer(44 + length * 2);
+        const view = new DataView(buffer);
+        const writeString = (offset, string) => {
+            for (let i = 0; i < string.length; i++) {
+                view.setUint8(offset + i, string.charCodeAt(i));
+            }
+        };
+        writeString(0, "RIFF");
+        view.setUint32(4, 36 + length * 2, true);
+        writeString(8, "WAVE");
+        writeString(12, "fmt ");
+        view.setUint32(16, 16, true);
+        view.setUint16(20, 1, true);
+        view.setUint16(22, 1, true);
+        view.setUint32(24, sampleRate, true);
+        view.setUint32(28, sampleRate * 2, true);
+        view.setUint16(32, 2, true);
+        view.setUint16(34, 16, true);
+        writeString(36, "data");
+        view.setUint32(40, length * 2, true);
+        let offset = 44;
+        for (let i = 0; i < length; i++) {
+            view.setInt16(offset, pcmData[i], true);
+            offset += 2;
+        }
+        return new Blob([buffer], { type: "audio/wav" });
     }
 
-    const AudioStreamResamplerProcessorCode = `
-class AudioStreamResamplerProcessor extends AudioWorkletProcessor {
-    constructor(options) {
-        super();
-        const config = options.processorOptions || {};
-        this.targetSampleRate = config.targetSampleRate || 16000;
-        this.sourceSampleRate = sampleRate;
-        this.downsampleRatio = this.sourceSampleRate / this.targetSampleRate;
-
-        // 16000Hz 用 60ms chunk (960 samples)，其他用 1024
-        this.chunkSize = this.targetSampleRate === 16000 ? 960 : 1024;
-
-        const sourceBufferSize = config.sourceBufferSize || 16384; // ~340ms @48kHz
-        const pcmBufferSize = config.pcmBufferSize || (this.chunkSize * 10); // 更大缓冲，减少溢出概率
-
-        this.sourceBuffer = new Float32Array(sourceBufferSize);
-        this.sourceBufferLength = 0;
-
-        this.pcmBuffer = new Int16Array(pcmBufferSize);
-        this.pcmBufferIndex = 0;
-    }
-
-    process(inputs, outputs, parameters) {
-        const input = inputs[0];
-        if (!input || input.length === 0 || input[0].length === 0) return true;
-        const inputChannel = input[0];
-
-        // 1. 写入源缓冲区（溢出时覆盖最旧数据）
-        const newLength = this.sourceBufferLength + inputChannel.length;
-        if (newLength > this.sourceBuffer.length) {
-            const overflow = newLength - this.sourceBuffer.length;
-            this.sourceBuffer.copyWithin(0, overflow);
-            this.sourceBufferLength = this.sourceBuffer.length - inputChannel.length;
-        }
-        this.sourceBuffer.set(inputChannel, this.sourceBufferLength);
-        this.sourceBufferLength += inputChannel.length;
-
-        // 2. 计算可降采样样本数
-        const availableOutputSamples = Math.floor(this.sourceBufferLength / this.downsampleRatio);
-        if (availableOutputSamples === 0) return true;
-
-        // 3. 线性插值降采样
-        const downsampled = new Float32Array(availableOutputSamples);
-        for (let i = 0; i < availableOutputSamples; i++) {
-            const srcIndex = i * this.downsampleRatio;
-            const srcIndexInt = Math.floor(srcIndex);
-            const fraction = srcIndex - srcIndexInt;
-            const val0 = this.sourceBuffer[srcIndexInt];
-            const val1 = srcIndexInt + 1 < this.sourceBufferLength ? this.sourceBuffer[srcIndexInt + 1] : val0;
-            downsampled[i] = val0 + (val1 - val0) * fraction;
-        }
-
-        // 4. Float32 → Int16 PCM
-        const pcmData = this.floatTo16BitPCM(downsampled);
-
-        // 5. 写入 PCM 缓冲区（空间不足时直接覆盖最旧，缓冲区足够大基本不会触发）
-        if (this.pcmBufferIndex + pcmData.length > this.pcmBuffer.length) {
-            // 简单策略：从头覆盖（丢弃最旧数据）
-            this.pcmBufferIndex = 0;
-        }
-        this.pcmBuffer.set(pcmData, this.pcmBufferIndex);
-        this.pcmBufferIndex += pcmData.length;
-
-        // 6. 发送所有完整的 chunk（关键：复制到新数组再转移）
-        while (this.pcmBufferIndex >= this.chunkSize) {
-            // 方法1：推荐，使用 slice（隐式复制到新 ArrayBuffer）
-            const chunk = this.pcmBuffer.slice(0, this.chunkSize);
-
-            // 方法2：等价写法
-            // const chunk = new Int16Array(this.pcmBuffer.subarray(0, this.chunkSize));
-
-            this.port.postMessage(chunk, [chunk.buffer]); // 转移新缓冲区，安全！
-
-            // 移动剩余数据到开头
-            this.pcmBuffer.copyWithin(0, this.chunkSize, this.pcmBufferIndex);
-            this.pcmBufferIndex -= this.chunkSize;
-        }
-
-        // 7. 清理已消费的源数据
-        const consumedSrc = Math.floor(availableOutputSamples * this.downsampleRatio + 0.5); // 四舍五入更准
-        if (consumedSrc > 0) {
-            this.sourceBuffer.copyWithin(0, consumedSrc, this.sourceBufferLength);
-            this.sourceBufferLength -= consumedSrc;
-        }
-
-        return true;
-    }
-
-    floatTo16BitPCM(input) {
-        const output = new Int16Array(input.length);
-        for (let i = 0; i < input.length; i++) {
-            const s = Math.max(-1, Math.min(1, input[i]));
-            output[i] = s < 0 ? s * 0x8000 : s * 0x7FFF;
-        }
-        return output;
-    }
-}
-
-registerProcessor('audio-stream-resampler-processor', AudioStreamResamplerProcessor);
-`;
-
-    /**
-     * 浏览器端实时音频流重采样器。
-     * 基于 AudioWorklet 将麦克风/媒体流转换为 16 kHz、16-bit、单声道 PCM，
-     * 并通过回调逐块输出，可选保存完整 PCM 用于后续合并。
-     */
-    class AudioStreamResampler {
-        /**
-         * @param {object} config
-         * @param {function(Int16Array)} config.onData - 收到一个 chunk PCM 数据的回调
-         * @param {function(string, string)} [config.onStateChange] - 状态变化回调
-         * @param {object} [config.processorOptions] - 传递给 AudioWorklet 的选项
-         * @param {boolean} [config.saveFullPcm=false] - 是否在内部保存所有 PCM 用于 stop 时合并（长时间录音建议关闭）
-         */
-        constructor(config) {
-            this.onData = config.onData || (() => {});
-            this.onStateChange = config.onStateChange || (() => {});
-            this.processorOptions = config.processorOptions || {};
-            this.saveFullPcm = config.saveFullPcm ?? false;
-
-            this.audioContext = null;
-            this.workletNode = null;
-            this.source = null;
-            this.workletUrl = null;
-            this.fullPcmData = this.saveFullPcm ? [] : null;
-
-            this.isInitialized = false;
-            this.isProcessing = false;
-        }
-
-        /**
-         * 初始化 AudioContext 并加载 AudioWorklet。
-         * 完成后状态变为 `"ready"`。
-         */
-        async init() {
-            this.onStateChange("initializing", "正在初始化音频环境...");
-            try {
-                this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
-
-                const blob = new Blob([AudioStreamResamplerProcessorCode], { type: "application/javascript" });
-                this.workletUrl = URL.createObjectURL(blob);
-                await this.audioContext.audioWorklet.addModule(this.workletUrl);
-
-                this.workletNode = new AudioWorkletNode(this.audioContext, "audio-stream-resampler-processor", {
-                    processorOptions: this.processorOptions
-                });
-
-                this.workletNode.port.onmessage = (event) => {
-                    const chunk = event.data; // Int16Array
-                    this.onData(chunk);
-                    if (this.saveFullPcm) {
-                        this.fullPcmData.push(chunk);
-                    }
-                };
-
-                this.isInitialized = true;
-                this.onStateChange("ready", "音频环境已就绪");
-            } catch (err) {
-                console.error("AudioStreamResampler init error:", err);
-                this.onStateChange("error", `初始化失败: ${err.message}`);
-            }
-        }
-
-        /**
-         * 绑定媒体流，开始实时处理。
-         * @param {MediaStream} stream - 通过 getUserMedia 或其他方式获得的流
-         */
-        setMediaStream(stream) {
-            if (!this.isInitialized) {
-                console.error("请先调用 init()");
-                return;
-            }
-
-            if (this.source) {
-                this.source.disconnect();
-            }
-
-            this.source = this.audioContext.createMediaStreamSource(stream);
-            this.source.connect(this.workletNode);
-            // workletNode 默认连接到 destination，可选断开以静音
-            // this.workletNode.connect(this.audioContext.destination);
-
-            this.isProcessing = true;
-            this.onStateChange("processing", "正在处理音频流...");
-        }
-
-        /**
-         * 停止处理并释放资源。
-         * @param {(fullPcm: Int16Array) => void} [callback] - 若构造时 `saveFullPcm=true`，会把合并后的完整 PCM 通过此回调传出
-         */
-        stop(callback) {
-            if (!this.isProcessing) return;
-
-            this.onStateChange("stopping", "正在停止...");
-
-            if (this.source) {
-                this.source.disconnect();
-                this.source = null;
-            }
-
-            this._cleanup();
-
-            this.onStateChange("stopped", "已停止");
-
-            if (this.saveFullPcm && callback && typeof callback === "function") {
-                const totalLength = this.fullPcmData.reduce((sum, chunk) => sum + chunk.length, 0);
-                const combined = new Int16Array(totalLength);
-                let offset = 0;
-                for (const chunk of this.fullPcmData) {
-                    combined.set(chunk, offset);
-                    offset += chunk.length;
-                }
-                callback(combined);
-            }
-        }
-
-        _cleanup() {
-            if (this.workletNode) {
-                this.workletNode.disconnect();
-                this.workletNode.port.close();
-                this.workletNode = null;
-            }
-            if (this.audioContext && this.audioContext.state !== "closed") {
-                this.audioContext.close();
-                this.audioContext = null;
-            }
-            if (this.workletUrl) {
-                URL.revokeObjectURL(this.workletUrl);
-                this.workletUrl = null;
-            }
-
-            this.isProcessing = false;
-            this.isInitialized = false;
-            if (this.fullPcmData) {
-                this.fullPcmData.length = 0;
-            }
-        }
-    }
-
-    /**
-     * 将 16-bit 单声道 PCM 数据封装成标准 WAV Blob。
-     *
-     * @param {Int16Array} pcmData - PCM 采样数据
-     * @param {number} [sampleRate=16000] - 采样率，默认 16 kHz
-     * @returns {Blob} audio/wav Blob
-     */
-    function pcmToWavBlob(pcmData, sampleRate = 16000) {
-        const length = pcmData.length;
-        const buffer = new ArrayBuffer(44 + length * 2);
-        const view = new DataView(buffer);
-        const writeString = (offset, string) => {
-            for (let i = 0; i < string.length; i++) {
-                view.setUint8(offset + i, string.charCodeAt(i));
-            }
-        };
-        writeString(0, "RIFF");
-        view.setUint32(4, 36 + length * 2, true);
-        writeString(8, "WAVE");
-        writeString(12, "fmt ");
-        view.setUint32(16, 16, true);
-        view.setUint16(20, 1, true);
-        view.setUint16(22, 1, true);
-        view.setUint32(24, sampleRate, true);
-        view.setUint32(28, sampleRate * 2, true);
-        view.setUint16(32, 2, true);
-        view.setUint16(34, 16, true);
-        writeString(36, "data");
-        view.setUint32(40, length * 2, true);
-        let offset = 44;
-        for (let i = 0; i < length; i++) {
-            view.setInt16(offset, pcmData[i], true);
-            offset += 2;
-        }
-        return new Blob([buffer], { type: "audio/wav" });
-    }
-
-    /**
-     * 视口尺寸对象。
-     * @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)
-        };
+    /**
+     * 视口尺寸对象。
+     * @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];
     }
 
-    /**
-     * 将总秒数格式化成人类可读的时间段文本。
-     * 固定进制：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("");
+    //#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);
+        });
     }
 
-    /**
-     * 快捷调用 {@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" });
+    function getLocales_TimePeriod() {
+        return {
+            earlyMorning: "凌晨",
+            morning: "上午",
+            noon: "中午",
+            afternoon: "下午",
+            evening: "晚上"
+        };
+    }
+
+    /**
+     * 将任意值安全转换为 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)));
+    }
+
+    //#region   持续时间相关
+
+    /**
+     * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+     * @typedef {Object} DurationObject
+     * @property {number} years - 年数
+     * @property {number} months - 月数（0-11）
+     * @property {number} days - 天数（0-29，取决于 monthDays）
+     * @property {number} hours - 小时数（0-23）
+     * @property {number} minutes - 分钟数（0-59）
+     * @property {number} seconds - 秒数（0-59）
+     * @property {number} milliseconds - 毫秒数（0-999）
+     */
+
+    /**
+     * 时间持续对象（最大单位为天）
+     * @typedef {Object} DurationMaxDayObject
+     * @property {number} days - 天数
+     * @property {number} hours - 小时数（0-23）
+     * @property {number} minutes - 分钟数（0-59）
+     * @property {number} seconds - 秒数（0-59）
+     * @property {number} milliseconds - 毫秒数（0-999）
+     */
+
+    /**
+     * 时间持续对象（最大单位为小时）
+     * @typedef {Object} DurationMaxHourObject
+     * @property {number} hours - 小时数
+     * @property {number} minutes - 分钟数（0-59）
+     * @property {number} seconds - 秒数（0-59）
+     * @property {number} milliseconds - 毫秒数（0-999）
+     */
+
+    /**
+     * 将毫秒转换为时间持续对象。
+     *
+     * @param {number} milliseconds - 毫秒数（非负整数）
+     * @param {Object} [options] - 选项对象。
+     * @param {number} [options.yearDays=365] - 一年的天数。
+     * @param {number} [options.monthDays=30] - 一月的天数。
+     * @returns {DurationObject} 时间持续对象
+     * @throws {TypeError} 当 milliseconds 不是有效数字
+     * @throws {RangeError} 当 milliseconds 为负数
+     * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
+     *
+     * @example
+     * // 基本用法
+     * millisecond2Duration(42070000500);
+     * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+     */
+    function millisecond2Duration(milliseconds, options = { yearDays: 365, monthDays: 30 }) {
+        // 参数验证
+        if (typeof milliseconds !== "number" || isNaN(milliseconds)) {
+            throw new TypeError("milliseconds must be a valid number");
+        }
+        if (milliseconds < 0) {
+            throw new RangeError("milliseconds must be a non-negative number");
+        }
+
+        // 默认选项
+        const { yearDays = 365, monthDays = 30 } = options;
+
+        // 选项验证
+        if (!Number.isInteger(yearDays) || yearDays <= 0) {
+            throw new RangeError("yearDays must be a positive integer");
+        }
+        if (!Number.isInteger(monthDays) || monthDays <= 0) {
+            throw new RangeError("monthDays must be a positive integer");
+        }
+
+        const totalMilliseconds = Math.floor(milliseconds);
+        const ms = totalMilliseconds % 1000;
+        const diffSeconds = Math.floor(totalMilliseconds / 1000);
+
+        const seconds = diffSeconds % 60;
+        const minutes = Math.floor(diffSeconds / 60) % 60;
+        const hours = Math.floor(diffSeconds / 3600) % 24;
+
+        // 计算年、月、日
+        const totalDays = Math.floor(diffSeconds / 3600 / 24);
+        const years = Math.floor(totalDays / yearDays);
+        const remainingDays = totalDays % yearDays;
+        const months = Math.floor(remainingDays / monthDays);
+        const days = remainingDays % monthDays;
+
+        return { years, months, days, hours, minutes, seconds, milliseconds: ms };
+    }
+
+    /**
+     * 将毫秒转换为时间持续对象（最大单位为天）。
+     * @param {number} milliseconds - 毫秒数（非负整数）
+     * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+     * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+     * @throws {RangeError} 当 milliseconds 为负数时抛出
+     * @example
+     * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+     * millisecond2DurationMaxDay(42070000500);
+     */
+    function millisecond2DurationMaxDay(milliseconds) {
+        if (typeof milliseconds !== "number" || isNaN(milliseconds)) {
+            throw new TypeError("milliseconds must be a valid number");
+        }
+        if (milliseconds < 0) {
+            throw new RangeError("milliseconds must be a non-negative number");
+        }
+
+        const totalMilliseconds = Math.floor(milliseconds);
+        const ms = totalMilliseconds % 1000;
+        const diffSeconds = Math.floor(totalMilliseconds / 1000);
+
+        const seconds = diffSeconds % 60;
+        const minutes = Math.floor(diffSeconds / 60) % 60;
+        const hours = Math.floor(diffSeconds / 3600) % 24;
+        const days = Math.floor(diffSeconds / 3600 / 24);
+
+        return { days, hours, minutes, seconds, milliseconds: ms };
+    }
+
+    /**
+     * 将毫秒转换为时间持续对象（最大单位为小时）。
+     * @param {number} milliseconds - 毫秒数（非负整数）
+     * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+     * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+     * @throws {RangeError} 当 milliseconds 为负数时抛出
+     * @example
+     * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+     * millisecond2DurationMaxHour(42070000500);
+     */
+    function millisecond2DurationMaxHour(milliseconds) {
+        if (typeof milliseconds !== "number" || isNaN(milliseconds)) {
+            throw new TypeError("milliseconds must be a valid number");
+        }
+        if (milliseconds < 0) {
+            throw new RangeError("milliseconds must be a non-negative number");
+        }
+
+        const totalMilliseconds = Math.floor(milliseconds);
+        const ms = totalMilliseconds % 1000;
+        const diffSeconds = Math.floor(totalMilliseconds / 1000);
+
+        const seconds = diffSeconds % 60;
+        const minutes = Math.floor(diffSeconds / 60) % 60;
+        const hours = Math.floor(diffSeconds / 3600);
+
+        return { hours, minutes, seconds, milliseconds: ms };
+    }
+
+    /**
+     * 将秒转换为时间持续对象。
+     *
+     * @param {number} seconds - 秒数（非负整数）
+     * @param {Object} [options] - 选项对象。
+     * @param {number} [options.yearDays=365] - 一年的天数。
+     * @param {number} [options.monthDays=30] - 一月的天数。
+     * @returns {DurationObject} 时间持续对象
+     * @throws {TypeError} 当 seconds 不是有效数字
+     * @throws {RangeError} 当 seconds 为负数
+     * @throws {RangeError} 当 yearDays 或 monthDays 不是正整数
+     *
+     * @example
+     * // 基本用法
+     * second2Duration(42070000.5);
+     * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+     */
+    function second2Duration(seconds, options = { yearDays: 365, monthDays: 30 }) {
+        if (typeof seconds !== "number" || isNaN(seconds)) {
+            throw new TypeError("seconds must be a valid number");
+        }
+        if (seconds < 0) {
+            throw new RangeError("seconds must be a non-negative number");
+        }
+        return millisecond2Duration(seconds * 1000, options);
+    }
+
+    /**
+     * 将秒转换为时间持续对象（最大单位为天）。
+     * @param {number} seconds - 秒数（非负整数）
+     * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+     * @throws {TypeError} 当 seconds 不是有效数字时抛出
+     * @throws {RangeError} 当 seconds 为负数时抛出
+     * @example
+     * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+     * second2DurationMaxDay(42070000.5);
+     */
+    function second2DurationMaxDay(seconds) {
+        if (typeof seconds !== "number" || isNaN(seconds)) {
+            throw new TypeError("seconds must be a valid number");
+        }
+        if (seconds < 0) {
+            throw new RangeError("seconds must be a non-negative number");
+        }
+        return millisecond2DurationMaxDay(seconds * 1000);
+    }
+
+    /**
+     * 将秒转换为时间持续对象（最大单位为小时）。
+     * @param {number} seconds - 秒数（非负整数）
+     * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+     * @throws {TypeError} 当 seconds 不是有效数字时抛出
+     * @throws {RangeError} 当 seconds 为负数时抛出
+     * @example
+     * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+     * second2DurationMaxHour(42070000.5);
+     */
+    function second2DurationMaxHour(seconds) {
+        if (typeof seconds !== "number" || isNaN(seconds)) {
+            throw new TypeError("seconds must be a valid number");
+        }
+        if (seconds < 0) {
+            throw new RangeError("seconds must be a non-negative number");
+        }
+        return millisecond2DurationMaxHour(seconds * 1000);
+    }
+
+    //#endregion
+
+    /**
+     * 根据小时数返回对应的时间段名称。
+     *
+     * @param {number} hour - 24 小时制的小时（0-23）
+     * @param {object} [locales] - 自定义时段文案
+     * @param {string} [locales.earlyMorning="凌晨"] - 00-05
+     * @param {string} [locales.morning="上午"] - 06-11
+     * @param {string} [locales.noon="中午"] - 12-13
+     * @param {string} [locales.afternoon="下午"] - 14-17
+     * @param {string} [locales.evening="晚上"] - 18-23
+     * @returns {string} 时段名称
+     * @throws {RangeError} 当 hour 不在 0-23 范围时抛出
+     */
+    function getTimePeriodName(hour, locales = getLocales_TimePeriod()) {
+        if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+            throw new RangeError("hour 必须是 0-23 的整数");
+        }
+        if (hour >= 0 && hour < 6) return locales.earlyMorning;
+        if (hour < 12) return locales.morning;
+        if (hour < 14) return locales.noon;
+        if (hour < 18) return locales.afternoon;
+        return locales.evening;
+    }
+
+    /**
+     * 格式化时间戳为本地化的时间字符串。
+     *
+     * @param {number} timestamp - 要格式化的时间戳（毫秒）。
+     * @param {Object} [locales] - 本地化配置对象，包含时间相关的本地化字符串。
+     * @param {string} [locales.justNow='刚刚'] - 表示刚刚过去的时间。
+     * @param {string} [locales.today='今天'] - 表示今天。
+     * @param {string} [locales.yesterday='昨天'] - 表示昨天。
+     * @param {string} [locales.beforeYesterday='前天'] - 表示前天。
+     * @param {string} [locales.year='年'] - 年的单位。
+     * @param {string} [locales.month='月'] - 月的单位。
+     * @param {string} [locales.day='日'] - 日的单位。
+     * @param {Object} [locales.timePeriod] - 一天中不同时间段的本地化字符串。
+     * @param {string} [locales.timePeriod.earlyMorning='凌晨'] - 凌晨。
+     * @param {string} [locales.timePeriod.morning='上午'] - 上午。
+     * @param {string} [locales.timePeriod.noon='中午'] - 中午。
+     * @param {string} [locales.timePeriod.afternoon='下午'] - 下午。
+     * @param {string} [locales.timePeriod.evening='晚上'] - 晚上。
+     * @param {Array<string>} [locales.weekDays=['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六']] - 星期几的本地化字符串数组。
+     *
+     * @returns {string} - 格式化后的时间字符串。
+     */
+    function formatTimeForLocale(
+        timestamp,
+        locales = {
+            justNow: "刚刚",
+            today: "今天",
+            yesterday: "昨天",
+            beforeYesterday: "前天",
+            year: "年",
+            month: "月",
+            day: "日",
+            timePeriod: getLocales_TimePeriod(),
+            weekDays: ["星期日", "星期一", "星期二", "星期三", "星期四", "星期五", "星期六"]
+        }
+    ) {
+        const now = new Date();
+        const messageDate = new Date(timestamp);
+
+        const nowTime = now.getTime();
+        const msgTime = messageDate.getTime();
+        const diff = nowTime - msgTime;
+        const diffMinutes = Math.floor(diff / (1000 * 60));
+
+        const year = messageDate.getFullYear();
+        const month = messageDate.getMonth() + 1;
+        const day = messageDate.getDate();
+        const hour = messageDate.getHours();
+        const minute = messageDate.getMinutes().toString().padStart(2, "0");
+
+        // 刚刚：1分钟内
+        if (diffMinutes < 1) {
+            return locales.justNow;
+        }
+
+        // 计算自然天数差（按日期而非时间差）
+        const nowDate = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        const msgDate = new Date(year, month - 1, day);
+        const diffDays = Math.floor((nowDate.getTime() - msgDate.getTime()) / (1000 * 60 * 60 * 24));
+
+        const period = getTimePeriodName(hour, locales.timePeriod);
+        const timeStr = `${hour}:${minute}`;
+
+        // 今天
+        if (diffDays === 0) {
+            return `${locales.today} ${period}${timeStr}`;
+        }
+
+        // 昨天
+        if (diffDays === 1) {
+            return `${locales.yesterday} ${period}${timeStr}`;
+        }
+
+        // 前天
+        if (diffDays === 2) {
+            return `${locales.beforeYesterday} ${period}${timeStr}`;
+        }
+
+        // 本周内（周一到周日，且不是今天/昨天/前天）
+        // 获取本周一的日期
+        const nowDay = now.getDay() || 7; // 周日转为7
+        const msgDay = messageDate.getDay() || 7;
+        const mondayOfThisWeek = new Date(nowDate.getTime() - (nowDay - 1) * 24 * 60 * 60 * 1000);
+        const mondayOfThatWeek = new Date(msgDate.getTime() - (msgDay - 1) * 24 * 60 * 60 * 1000);
+
+        if (mondayOfThisWeek.getTime() === mondayOfThatWeek.getTime() && diffDays < 7) {
+            const weekDayName = locales.weekDays[messageDate.getDay()];
+            return `${weekDayName}${period} ${timeStr}`;
+        }
+
+        // 本月内（非本周）
+        const nowYear = now.getFullYear();
+        const nowMonth = now.getMonth();
+        if (year === nowYear && messageDate.getMonth() === nowMonth) {
+            return `${month}${locales.month}${day}${locales.day} ${period}${timeStr}`;
+        }
+
+        // 本年内（非本月）
+        if (year === nowYear) {
+            return `${month}${locales.month}${day}${locales.day} ${period}${timeStr}`;
+        }
+
+        // 其他（非本年）
+        return `${year}${locales.year}${month}${locales.month}${day}${locales.day} ${period}${timeStr}`;
     }
 
-    /**
-     * 快捷调用 {@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>` 标签触发浏览器下载。
+     * 注意：此方法可能无法强制下载浏览器原生支持的文件（如图片、PDF），浏览器可能会选择直接打开。
+     *
+     * @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");
+    }
+
+    /**
+     * 通过 `fetch` 获取资源并强制下载，避免浏览器直接打开文件。
+     * 此方法适用于下载图片、PDF 等浏览器默认会打开的文件类型。
+     * 如果 `fetch` 失败（如 CORS 策略阻止），会回退到 `downloadByUrl` 方法作为备选方案。
+     *
+     * @param {string} url - 文件的 URL 地址
+     * @param {string} [fileName] - 保存到本地的文件名。如果不提供，会尝试从 URL 中自动提取
+     * @returns {Promise<void>} 返回一个 Promise，在下载开始或失败后 resolve
+     */
+    async function fetchOrDownloadByUrl(url, fileName) {
+        // 如果未提供文件名，尝试从 URL 路径中提取
+        if (!fileName) {
+            try {
+                const urlPathname = new URL(url).pathname;
+                // 获取路径的最后一部分作为文件名，并移除可能的查询参数
+                fileName = urlPathname.substring(urlPathname.lastIndexOf("/") + 1).split("?")[0];
+            } catch (e) {}
+            // 如果提取后文件名为空（例如 URL 以 '/' 结尾），也使用时间戳
+            if (!fileName) {
+                fileName = Date.now().toString();
+            }
+        }
+
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                mode: "cors",
+                cache: "no-cache"
+            });
+
+            if (!response.ok) {
+                throw new Error(`HTTP error! ${response.status}: ${response.statusText}`);
+            }
+
+            const blob = await response.blob();
+            downloadByBlob(blob, fileName);
+        } catch (error) {
+            downloadByUrl(url, fileName);
+        }
     }
 
-    /**
-     * 通过动态创建 `<a>` 标签触发浏览器下载。
-     * 注意：此方法可能无法强制下载浏览器原生支持的文件（如图片、PDF），浏览器可能会选择直接打开。
-     *
-     * @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");
-    }
-
-    /**
-     * 通过 `fetch` 获取资源并强制下载，避免浏览器直接打开文件。
-     * 此方法适用于下载图片、PDF 等浏览器默认会打开的文件类型。
-     * 如果 `fetch` 失败（如 CORS 策略阻止），会回退到 `downloadByUrl` 方法作为备选方案。
-     *
-     * @param {string} url - 文件的 URL 地址
-     * @param {string} [fileName] - 保存到本地的文件名。如果不提供，会尝试从 URL 中自动提取
-     * @returns {Promise<void>} 返回一个 Promise，在下载开始或失败后 resolve
-     */
-    async function fetchOrDownloadByUrl(url, fileName) {
-        // 如果未提供文件名，尝试从 URL 路径中提取
-        if (!fileName) {
-            try {
-                const urlPathname = new URL(url).pathname;
-                // 获取路径的最后一部分作为文件名，并移除可能的查询参数
-                fileName = urlPathname.substring(urlPathname.lastIndexOf("/") + 1).split("?")[0];
-            } catch (e) {}
-            // 如果提取后文件名为空（例如 URL 以 '/' 结尾），也使用时间戳
-            if (!fileName) {
-                fileName = Date.now().toString();
-            }
-        }
-
-        try {
-            const response = await fetch(url, {
-                method: "GET",
-                mode: "cors",
-                cache: "no-cache"
-            });
-
-            if (!response.ok) {
-                throw new Error(`HTTP error! ${response.status}: ${response.statusText}`);
-            }
-
-            const blob = await response.blob();
-            downloadByBlob(blob, fileName);
-        } catch (error) {
-            downloadByUrl(url, fileName);
-        }
-    }
-
-    /**
-     * 简单、高性能的通用事件总线。
-     * - 支持命名空间事件
-     * - 支持一次性监听器
-     * - 返回唯一 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();
-            }
-        };
+    /**
+     * 简单、高性能的通用事件总线。
+     * - 支持命名空间事件
+     * - 支持一次性监听器
+     * - 返回唯一 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;
+    /**
+     * 生成 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");
+        }
     }
 
-    /**
-     * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。
-     *
-     * @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;
+    /**
+     * 基于 `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` 递归查找节点，并返回其指定属性值。
-     *
-     * @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;
-                    }
-                }
-            }
-        }
-    };
-
-    /**
-     * 从服务端返回的已选 id 数组里，提取出
-     * 1. 叶子节点
-     * 2. 所有子节点都被选中的父节点
-     * 其余父节点一律丢弃（由前端 Tree 自动算半选）
-     *
-     * @param {Array}  treeData     完整树
-     * @param {Array}  selectedKeys 后端给的选中 id 数组
-     * @param {String} idKey        节点唯一字段
-     * @param {String} childrenKey  子节点字段
-     * @returns {{checked: string[], halfChecked: string[]}}
-     */
-    function extractFullyCheckedKeys(treeData, selectedKeys, idKey = "id", childrenKey = "children") {
-        const selectedSet = new Set(selectedKeys);
-        const checked = new Set();
-        const halfChecked = new Set();
-
-        /* 返回值含义
-            0 - 未选中
-            1 - 半选
-            2 - 全选
-            */
-        function dfs(node) {
-            const nodeId = node[idKey];
-            const children = node[childrenKey] || [];
-
-            // 叶子
-            if (!children.length) {
-                if (selectedSet.has(nodeId)) {
-                    checked.add(nodeId);
-                    return 2;
-                }
-                return 0;
-            }
-
-            // 非叶子
-            let allChecked = true;
-            let someChecked = false;
-
-            children.forEach((child) => {
-                const childState = dfs(child);
-                if (childState !== 2) allChecked = false;
-                if (childState >= 1) someChecked = true;
-            });
-
-            // 当前节点本身在 selectedKeys 里，但子节点未全选 → 只能算半选
-            if (selectedSet.has(nodeId)) {
-                if (allChecked) {
-                    checked.add(nodeId);
-                    return 2;
-                }
-                halfChecked.add(nodeId);
-                return 1;
-            }
-
-            // 当前节点不在 selectedKeys 里，看子节点
-            if (allChecked) {
-                checked.add(nodeId);
-                return 2;
-            }
-            if (someChecked) {
-                halfChecked.add(nodeId);
-                return 1;
-            }
-            return 0;
-        }
-
-        treeData.forEach(dfs);
-        return {
-            checked: [...checked],
-            halfChecked: [...halfChecked]
-        };
+    /**
+     * 把嵌套树拍平成 `{ [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;
+                    }
+                }
+            }
+        }
+    };
+
+    /**
+     * 从服务端返回的已选 id 数组里，提取出
+     * 1. 叶子节点
+     * 2. 所有子节点都被选中的父节点
+     * 其余父节点一律丢弃（由前端 Tree 自动算半选）
+     *
+     * @param {Array}  treeData     完整树
+     * @param {Array}  selectedKeys 后端给的选中 id 数组
+     * @param {String} idKey        节点唯一字段
+     * @param {String} childrenKey  子节点字段
+     * @returns {{checked: string[], halfChecked: string[]}}
+     */
+    function extractFullyCheckedKeys(treeData, selectedKeys, idKey = "id", childrenKey = "children") {
+        const selectedSet = new Set(selectedKeys);
+        const checked = new Set();
+        const halfChecked = new Set();
+
+        /* 返回值含义
+            0 - 未选中
+            1 - 半选
+            2 - 全选
+            */
+        function dfs(node) {
+            const nodeId = node[idKey];
+            const children = node[childrenKey] || [];
+
+            // 叶子
+            if (!children.length) {
+                if (selectedSet.has(nodeId)) {
+                    checked.add(nodeId);
+                    return 2;
+                }
+                return 0;
+            }
+
+            // 非叶子
+            let allChecked = true;
+            let someChecked = false;
+
+            children.forEach((child) => {
+                const childState = dfs(child);
+                if (childState !== 2) allChecked = false;
+                if (childState >= 1) someChecked = true;
+            });
+
+            // 当前节点本身在 selectedKeys 里，但子节点未全选 → 只能算半选
+            if (selectedSet.has(nodeId)) {
+                if (allChecked) {
+                    checked.add(nodeId);
+                    return 2;
+                }
+                halfChecked.add(nodeId);
+                return 1;
+            }
+
+            // 当前节点不在 selectedKeys 里，看子节点
+            if (allChecked) {
+                checked.add(nodeId);
+                return 2;
+            }
+            if (someChecked) {
+                halfChecked.add(nodeId);
+                return 1;
+            }
+            return 0;
+        }
+
+        treeData.forEach(dfs);
+        return {
+            checked: [...checked],
+            halfChecked: [...halfChecked]
+        };
     }
 
-    /**
-     * @class WebSocketManager - 一个纯粹、强大的 WebSocket 连接管理引擎
-     *
-     * @features
-     * - 智能断线重连 (指数退避算法)
-     * - 网络状态监听
-     * - 高度可定制的心跳保活机制 (通过注入函数实现)
-     * - 页面可见性 API 集成
-     * - 消息发送队列
-     * - 清晰的生命周期管理
-     * - 优雅的资源销毁
-     * - 可配置的数据序列化/反序列化
-     * - 纯粹的消息传递，不关心消息内容
-     */
-    class WebSocketManager {
-        /**
-         * @param {string} url - WebSocket 服务器的地址
-         * @param {object} [options={}] - 配置选项
-         * @param {number} [options.heartbeatInterval=30000] - 心跳间隔 (毫秒)
-         * @param {number} [options.heartbeatTimeout=10000] - 心跳超时时间 (毫秒)
-         * @param {number} [options.reconnectBaseInterval=1000] - 重连基础间隔 (毫秒)
-         * @param {number} [options.maxReconnectInterval=30000] - 最大重连间隔 (毫秒)
-         * @param {number} [options.maxReconnectAttempts=Infinity] - 最大重连次数
-         * @param {boolean} [options.autoConnect=true] - 是否在实例化后自动连接
-         * @param {boolean} [options.serializeData=false] - 发送数据时是否自动序列化为JSON字符串
-         * @param {boolean} [options.deserializeData=false] - 接收数据时是否自动反序列化为JSON对象
-         * @param {function|null} [options.getPingMessage=null] - 返回要发送的 ping 消息内容的函数。如果为 null，则不发送心跳。
-         * @param {function|null} [options.isPongMessage=null] - 判断接收到的消息是否为 pong 的函数。接收 MessageEvent 对象作为参数，返回布尔值。
-         * @param {object} [options.protocols] - WebSocket 协议
-         */
-        constructor(url, options = {}) {
-            this.url = url;
-
-            // 默认的心跳实现，用于向后兼容
-            const defaultGetPingMessage = () => JSON.stringify({ type: "ping" });
-            const defaultIsPongMessage = (event) => {
-                try {
-                    const message = JSON.parse(event.data);
-                    return message.type === "pong";
-                } catch (e) {
-                    return false;
-                }
-            };
-
-            this.options = {
-                heartbeatInterval: 30000,
-                heartbeatTimeout: 10000,
-                reconnectBaseInterval: 1000,
-                maxReconnectInterval: 30000,
-                maxReconnectAttempts: Infinity,
-                autoConnect: true,
-                serializeData: false,
-                deserializeData: false,
-                getPingMessage: defaultGetPingMessage, // 默认提供 ping 消息生成器
-                isPongMessage: defaultIsPongMessage, // 默认提供 pong 消息判断器
-                ...options
-            };
-
-            // WebSocket 实例
-            this.ws = null;
-
-            // 状态管理
-            this.readyState = WebSocket.CLOSED;
-            this.reconnectAttempts = 0;
-            this.forcedClose = false;
-            this.isReconnecting = false;
-
-            // 定时器
-            this.heartbeatTimer = null;
-            this.heartbeatTimeoutTimer = null;
-            this.reconnectTimer = null;
-
-            // 消息队列
-            this.messageQueue = [];
-
-            // 事件监听器
-            this.listeners = new Map();
-
-            // 绑定方法上下文
-            this._onOpen = this._onOpen.bind(this);
-            this._onMessage = this._onMessage.bind(this);
-            this._onClose = this._onClose.bind(this);
-            this._onError = this._onError.bind(this);
-            this._handleVisibilityChange = this._handleVisibilityChange.bind(this);
-            this._handleOnline = this._handleOnline.bind(this);
-            this._handleOffline = this._handleOffline.bind(this);
-
-            this._setupEventListeners();
-
-            if (this.options.autoConnect) {
-                this.connect();
-            }
-        }
-
-        // --- 公共 API ---
-
-        /**
-         * 连接到 WebSocket 服务器
-         */
-        connect() {
-            if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
-                return;
-            }
-
-            this.forcedClose = false;
-            this._updateReadyState(WebSocket.CONNECTING);
-            console.log(`[WS] 正在连接到 ${this.url}...`);
-            this._emit("connecting");
-
-            try {
-                this.ws = new WebSocket(this.url, this.options.protocols);
-                this.ws.onopen = this._onOpen;
-                this.ws.onmessage = this._onMessage;
-                this.ws.onclose = this._onClose;
-                this.ws.onerror = this._onError;
-            } catch (error) {
-                console.error("[WS] 连接失败:", error);
-                this._onError(error);
-            }
-        }
-
-        /**
-         * 发送数据
-         * @param {string|object|ArrayBuffer|Blob} data - 要发送的数据
-         */
-        send(data) {
-            if (this.readyState === WebSocket.OPEN) {
-                let message;
-                // 根据配置决定是否序列化数据
-                if (this.options.serializeData) {
-                    message = JSON.stringify(data);
-                } else {
-                    message = data;
-                }
-                this.ws.send(message);
-                console.log("[WS] 消息已发送:", message);
-            } else {
-                console.warn("[WS] 连接未打开，消息已加入队列:", data);
-                this.messageQueue.push(data);
-            }
-        }
-
-        /**
-         * 主动关闭连接
-         * @param {number} [code=1000] - 关闭代码
-         * @param {string} [reason=''] - 关闭原因
-         */
-        close(code = 1000, reason = "Normal closure") {
-            this.forcedClose = true;
-            this._stopHeartbeat();
-            this._clearReconnectTimer();
-            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-                this.ws.close(code, reason);
-            } else {
-                this._updateReadyState(WebSocket.CLOSED);
-                this._emit("close", { code, reason, wasClean: true });
-            }
-        }
-
-        /**
-         * 彻底销毁实例，清理所有资源
-         */
-        destroy() {
-            console.log("[WS] 正在销毁实例...");
-            this.close(1000, "Instance destroyed");
-            this._removeEventListeners();
-            this.messageQueue = [];
-            this.listeners.clear();
-            this.ws = null;
-        }
-
-        /**
-         * 添加事件监听器
-         * @param {string} eventName - 事件名 (e.g., 'open', 'message', 'close', 'error', 'reconnect')
-         * @param {function} callback - 回调函数
-         */
-        on(eventName, callback) {
-            if (!this.listeners.has(eventName)) {
-                this.listeners.set(eventName, []);
-            }
-            this.listeners.get(eventName).push(callback);
-        }
-
-        /**
-         * 移除事件监听器
-         * @param {string} eventName - 事件名
-         * @param {function} callback - 回调函数
-         */
-        off(eventName, callback) {
-            if (this.listeners.has(eventName)) {
-                const callbacks = this.listeners.get(eventName);
-                const index = callbacks.indexOf(callback);
-                if (index > -1) {
-                    callbacks.splice(index, 1);
-                }
-            }
-        }
-
-        // --- 内部方法 ---
-
-        _onOpen(event) {
-            console.log("[WS] 连接已建立");
-            this._updateReadyState(WebSocket.OPEN);
-            this.reconnectAttempts = 0;
-            this.isReconnecting = false;
-
-            // 如果配置了 getPingMessage，则启动心跳
-            if (this.options.getPingMessage) {
-                this._startHeartbeat();
-            }
-
-            this._flushMessageQueue();
-            this._emit("open", event);
-        }
-
-        /**
-         * 纯粹的消息处理方法：处理心跳，然后将数据交给使用者
-         * @param {MessageEvent} event
-         */
-        _onMessage(event) {
-            // --- 步骤 1: 使用注入的函数优先处理内部心跳机制 ---
-            if (this.options.isPongMessage && this.options.isPongMessage(event)) {
-                this._handlePong();
-                return; // 是心跳消息，处理完毕，直接返回
-            }
-
-            // --- 步骤 2: 根据用户配置处理业务消息 ---
-            if (this.options.deserializeData) {
-                try {
-                    const parsedMessage = JSON.parse(event.data);
-                    this._emit("message", parsedMessage, event);
-                } catch (e) {
-                    this._emit("message", event.data, event);
-                }
-            } else {
-                this._emit("message", event.data, event);
-            }
-        }
-
-        _onClose(event) {
-            console.log("[WS] 连接已关闭", event);
-            this._updateReadyState(WebSocket.CLOSED);
-            this._stopHeartbeat();
-            this._emit("close", event);
-
-            if (!this.forcedClose) {
-                this._scheduleReconnect();
-            }
-        }
-
-        _onError(event) {
-            console.error("[WS] 连接发生错误:", event);
-            this._emit("error", event);
-        }
-
-        // --- 心跳机制 ---
-        _startHeartbeat() {
-            // 如果没有配置 getPingMessage，则无法启动心跳
-            if (!this.options.getPingMessage) {
-                return;
-            }
-
-            this._stopHeartbeat();
-            this.heartbeatTimer = setInterval(() => {
-                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-                    try {
-                        // 调用注入的函数获取消息内容并发送
-                        const pingMessage = this.options.getPingMessage();
-                        this.ws.send(pingMessage);
-                        console.log("[WS] 发送 Ping:", pingMessage);
-                        this._setHeartbeatTimeout();
-                    } catch (error) {
-                        console.error("[WS] 发送 Ping 消息失败:", error);
-                    }
-                }
-            }, this.options.heartbeatInterval);
-        }
-
-        _stopHeartbeat() {
-            if (this.heartbeatTimer) {
-                clearInterval(this.heartbeatTimer);
-                this.heartbeatTimer = null;
-            }
-            this._clearHeartbeatTimeout();
-        }
-
-        _setHeartbeatTimeout() {
-            this._clearHeartbeatTimeout();
-            this.heartbeatTimeoutTimer = setTimeout(() => {
-                console.error("[WS] 心跳超时，主动断开连接");
-                this.ws.close(1006, "Heartbeat timeout");
-            }, this.options.heartbeatTimeout);
-        }
-
-        _clearHeartbeatTimeout() {
-            if (this.heartbeatTimeoutTimer) {
-                clearTimeout(this.heartbeatTimeoutTimer);
-                this.heartbeatTimeoutTimer = null;
-            }
-        }
-
-        _handlePong() {
-            console.log("[WS] 收到 Pong");
-            this._clearHeartbeatTimeout();
-        }
-
-        // --- 重连机制 ---
-        _scheduleReconnect() {
-            if (this.forcedClose || this.isReconnecting || this.reconnectAttempts >= this.options.maxReconnectAttempts) {
-                if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
-                    console.error("[WS] 已达到最大重连次数，停止重连");
-                    this._emit("reconnect-failed");
-                }
-                return;
-            }
-
-            this.isReconnecting = true;
-            const interval = Math.min(this.options.reconnectBaseInterval * Math.pow(2, this.reconnectAttempts), this.options.maxReconnectInterval);
-
-            console.log(`[WS] ${interval / 1000}秒后将尝试第 ${this.reconnectAttempts + 1} 次重连...`);
-            this._emit("reconnect-attempt", { attempt: this.reconnectAttempts + 1, interval });
-
-            this.reconnectTimer = setTimeout(() => {
-                this.reconnectAttempts++;
-                this.connect();
-            }, interval);
-        }
-
-        _clearReconnectTimer() {
-            if (this.reconnectTimer) {
-                clearTimeout(this.reconnectTimer);
-                this.reconnectTimer = null;
-            }
-        }
-
-        // --- 消息队列 ---
-        _flushMessageQueue() {
-            if (this.messageQueue.length === 0) return;
-            console.log(`[WS] 发送队列中的 ${this.messageQueue.length} 条消息`);
-            const queue = [...this.messageQueue];
-            this.messageQueue = [];
-            queue.forEach((data) => this.send(data));
-        }
-
-        // --- 事件系统 ---
-        _emit(eventName, ...args) {
-            if (this.listeners.has(eventName)) {
-                this.listeners.get(eventName).forEach((callback) => callback(...args));
-            }
-        }
-
-        // --- 状态与监听器管理 ---
-        _updateReadyState(newState) {
-            this.readyState = newState;
-            this._emit("ready-state-change", newState);
-        }
-
-        _setupEventListeners() {
-            document.addEventListener("visibilitychange", this._handleVisibilityChange);
-            window.addEventListener("online", this._handleOnline);
-            window.addEventListener("offline", this._handleOffline);
-        }
-
-        _removeEventListeners() {
-            document.removeEventListener("visibilitychange", this._handleVisibilityChange);
-            window.removeEventListener("online", this._handleOnline);
-            window.removeEventListener("offline", this._handleOffline);
-        }
-
-        _handleVisibilityChange() {
-            // 如果未启用心跳，不需要处理页面可见性变化
-            if (!this.options.getPingMessage) {
-                return;
-            }
-
-            if (document.hidden) {
-                console.log("[WS] 页面隐藏，停止心跳");
-                this._stopHeartbeat();
-            } else {
-                console.log("[WS] 页面可见，检查连接状态");
-                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
-                    this._startHeartbeat();
-                } else if (!this.forcedClose && !this.isReconnecting) {
-                    this.connect();
-                }
-            }
-        }
-
-        _handleOnline() {
-            console.log("[WS] 网络已恢复，尝试重连");
-            if (!this.forcedClose && this.readyState !== WebSocket.OPEN) {
-                this._clearReconnectTimer(); // 清除当前的重连计划
-                this.connect(); // 立即尝试连接
-            }
-        }
-
-        _handleOffline() {
-            console.log("[WS] 网络已断开");
-            this._clearReconnectTimer(); // 停止重连尝试
-            // ws.onclose 会被触发，从而启动重连逻辑，但我们已经停止了
-            // 所以这里可以手动触发一次 close 事件来通知应用层
-            if (this.ws) this.ws.onclose({ code: 1006, reason: "Network offline" });
-        }
+    /**
+     * @class WebSocketManager - 一个纯粹、强大的 WebSocket 连接管理引擎
+     *
+     * @features
+     * - 智能断线重连 (指数退避算法)
+     * - 网络状态监听
+     * - 高度可定制的心跳保活机制 (通过注入函数实现)
+     * - 页面可见性 API 集成
+     * - 消息发送队列
+     * - 清晰的生命周期管理
+     * - 优雅的资源销毁
+     * - 可配置的数据序列化/反序列化
+     * - 纯粹的消息传递，不关心消息内容
+     */
+    class WebSocketManager {
+        /**
+         * @param {string} url - WebSocket 服务器的地址
+         * @param {object} [options={}] - 配置选项
+         * @param {number} [options.heartbeatInterval=30000] - 心跳间隔 (毫秒)
+         * @param {number} [options.heartbeatTimeout=10000] - 心跳超时时间 (毫秒)
+         * @param {number} [options.reconnectBaseInterval=1000] - 重连基础间隔 (毫秒)
+         * @param {number} [options.maxReconnectInterval=30000] - 最大重连间隔 (毫秒)
+         * @param {number} [options.maxReconnectAttempts=Infinity] - 最大重连次数
+         * @param {boolean} [options.autoConnect=true] - 是否在实例化后自动连接
+         * @param {boolean} [options.serializeData=false] - 发送数据时是否自动序列化为JSON字符串
+         * @param {boolean} [options.deserializeData=false] - 接收数据时是否自动反序列化为JSON对象
+         * @param {function|null} [options.getPingMessage=null] - 返回要发送的 ping 消息内容的函数。如果为 null，则不发送心跳。
+         * @param {function|null} [options.isPongMessage=null] - 判断接收到的消息是否为 pong 的函数。接收 MessageEvent 对象作为参数，返回布尔值。
+         * @param {object} [options.protocols] - WebSocket 协议
+         */
+        constructor(url, options = {}) {
+            this.url = url;
+
+            // 默认的心跳实现，用于向后兼容
+            const defaultGetPingMessage = () => JSON.stringify({ type: "ping" });
+            const defaultIsPongMessage = (event) => {
+                try {
+                    const message = JSON.parse(event.data);
+                    return message.type === "pong";
+                } catch (e) {
+                    return false;
+                }
+            };
+
+            this.options = {
+                heartbeatInterval: 30000,
+                heartbeatTimeout: 10000,
+                reconnectBaseInterval: 1000,
+                maxReconnectInterval: 30000,
+                maxReconnectAttempts: Infinity,
+                autoConnect: true,
+                serializeData: false,
+                deserializeData: false,
+                getPingMessage: defaultGetPingMessage, // 默认提供 ping 消息生成器
+                isPongMessage: defaultIsPongMessage, // 默认提供 pong 消息判断器
+                ...options
+            };
+
+            // WebSocket 实例
+            this.ws = null;
+
+            // 状态管理
+            this.readyState = WebSocket.CLOSED;
+            this.reconnectAttempts = 0;
+            this.forcedClose = false;
+            this.isReconnecting = false;
+
+            // 定时器
+            this.heartbeatTimer = null;
+            this.heartbeatTimeoutTimer = null;
+            this.reconnectTimer = null;
+
+            // 消息队列
+            this.messageQueue = [];
+
+            // 事件监听器
+            this.listeners = new Map();
+
+            // 绑定方法上下文
+            this._onOpen = this._onOpen.bind(this);
+            this._onMessage = this._onMessage.bind(this);
+            this._onClose = this._onClose.bind(this);
+            this._onError = this._onError.bind(this);
+            this._handleVisibilityChange = this._handleVisibilityChange.bind(this);
+            this._handleOnline = this._handleOnline.bind(this);
+            this._handleOffline = this._handleOffline.bind(this);
+
+            this._setupEventListeners();
+
+            if (this.options.autoConnect) {
+                this.connect();
+            }
+        }
+
+        // --- 公共 API ---
+
+        /**
+         * 连接到 WebSocket 服务器
+         */
+        connect() {
+            if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
+                return;
+            }
+
+            this.forcedClose = false;
+            this._updateReadyState(WebSocket.CONNECTING);
+            console.log(`[WS] 正在连接到 ${this.url}...`);
+            this._emit("connecting");
+
+            try {
+                this.ws = new WebSocket(this.url, this.options.protocols);
+                this.ws.onopen = this._onOpen;
+                this.ws.onmessage = this._onMessage;
+                this.ws.onclose = this._onClose;
+                this.ws.onerror = this._onError;
+            } catch (error) {
+                console.error("[WS] 连接失败:", error);
+                this._onError(error);
+            }
+        }
+
+        /**
+         * 发送数据
+         * @param {string|object|ArrayBuffer|Blob} data - 要发送的数据
+         */
+        send(data) {
+            if (this.readyState === WebSocket.OPEN) {
+                let message;
+                // 根据配置决定是否序列化数据
+                if (this.options.serializeData) {
+                    message = JSON.stringify(data);
+                } else {
+                    message = data;
+                }
+                this.ws.send(message);
+                console.log("[WS] 消息已发送:", message);
+            } else {
+                console.warn("[WS] 连接未打开，消息已加入队列:", data);
+                this.messageQueue.push(data);
+            }
+        }
+
+        /**
+         * 主动关闭连接
+         * @param {number} [code=1000] - 关闭代码
+         * @param {string} [reason=''] - 关闭原因
+         */
+        close(code = 1000, reason = "Normal closure") {
+            this.forcedClose = true;
+            this._stopHeartbeat();
+            this._clearReconnectTimer();
+            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                this.ws.close(code, reason);
+            } else {
+                this._updateReadyState(WebSocket.CLOSED);
+                this._emit("close", { code, reason, wasClean: true });
+            }
+        }
+
+        /**
+         * 彻底销毁实例，清理所有资源
+         */
+        destroy() {
+            console.log("[WS] 正在销毁实例...");
+            this.close(1000, "Instance destroyed");
+            this._removeEventListeners();
+            this.messageQueue = [];
+            this.listeners.clear();
+            this.ws = null;
+        }
+
+        /**
+         * 添加事件监听器
+         * @param {string} eventName - 事件名 (e.g., 'open', 'message', 'close', 'error', 'reconnect')
+         * @param {function} callback - 回调函数
+         */
+        on(eventName, callback) {
+            if (!this.listeners.has(eventName)) {
+                this.listeners.set(eventName, []);
+            }
+            this.listeners.get(eventName).push(callback);
+        }
+
+        /**
+         * 移除事件监听器
+         * @param {string} eventName - 事件名
+         * @param {function} callback - 回调函数
+         */
+        off(eventName, callback) {
+            if (this.listeners.has(eventName)) {
+                const callbacks = this.listeners.get(eventName);
+                const index = callbacks.indexOf(callback);
+                if (index > -1) {
+                    callbacks.splice(index, 1);
+                }
+            }
+        }
+
+        // --- 内部方法 ---
+
+        _onOpen(event) {
+            console.log("[WS] 连接已建立");
+            this._updateReadyState(WebSocket.OPEN);
+            this.reconnectAttempts = 0;
+            this.isReconnecting = false;
+
+            // 如果配置了 getPingMessage，则启动心跳
+            if (this.options.getPingMessage) {
+                this._startHeartbeat();
+            }
+
+            this._flushMessageQueue();
+            this._emit("open", event);
+        }
+
+        /**
+         * 纯粹的消息处理方法：处理心跳，然后将数据交给使用者
+         * @param {MessageEvent} event
+         */
+        _onMessage(event) {
+            // --- 步骤 1: 使用注入的函数优先处理内部心跳机制 ---
+            if (this.options.isPongMessage && this.options.isPongMessage(event)) {
+                this._handlePong();
+                return; // 是心跳消息，处理完毕，直接返回
+            }
+
+            // --- 步骤 2: 根据用户配置处理业务消息 ---
+            if (this.options.deserializeData) {
+                try {
+                    const parsedMessage = JSON.parse(event.data);
+                    this._emit("message", parsedMessage, event);
+                } catch (e) {
+                    this._emit("message", event.data, event);
+                }
+            } else {
+                this._emit("message", event.data, event);
+            }
+        }
+
+        _onClose(event) {
+            console.log("[WS] 连接已关闭", event);
+            this._updateReadyState(WebSocket.CLOSED);
+            this._stopHeartbeat();
+            this._emit("close", event);
+
+            if (!this.forcedClose) {
+                this._scheduleReconnect();
+            }
+        }
+
+        _onError(event) {
+            console.error("[WS] 连接发生错误:", event);
+            this._emit("error", event);
+        }
+
+        // --- 心跳机制 ---
+        _startHeartbeat() {
+            // 如果没有配置 getPingMessage，则无法启动心跳
+            if (!this.options.getPingMessage) {
+                return;
+            }
+
+            this._stopHeartbeat();
+            this.heartbeatTimer = setInterval(() => {
+                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                    try {
+                        // 调用注入的函数获取消息内容并发送
+                        const pingMessage = this.options.getPingMessage();
+                        this.ws.send(pingMessage);
+                        console.log("[WS] 发送 Ping:", pingMessage);
+                        this._setHeartbeatTimeout();
+                    } catch (error) {
+                        console.error("[WS] 发送 Ping 消息失败:", error);
+                    }
+                }
+            }, this.options.heartbeatInterval);
+        }
+
+        _stopHeartbeat() {
+            if (this.heartbeatTimer) {
+                clearInterval(this.heartbeatTimer);
+                this.heartbeatTimer = null;
+            }
+            this._clearHeartbeatTimeout();
+        }
+
+        _setHeartbeatTimeout() {
+            this._clearHeartbeatTimeout();
+            this.heartbeatTimeoutTimer = setTimeout(() => {
+                console.error("[WS] 心跳超时，主动断开连接");
+                this.ws.close(1006, "Heartbeat timeout");
+            }, this.options.heartbeatTimeout);
+        }
+
+        _clearHeartbeatTimeout() {
+            if (this.heartbeatTimeoutTimer) {
+                clearTimeout(this.heartbeatTimeoutTimer);
+                this.heartbeatTimeoutTimer = null;
+            }
+        }
+
+        _handlePong() {
+            console.log("[WS] 收到 Pong");
+            this._clearHeartbeatTimeout();
+        }
+
+        // --- 重连机制 ---
+        _scheduleReconnect() {
+            if (this.forcedClose || this.isReconnecting || this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+                if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+                    console.error("[WS] 已达到最大重连次数，停止重连");
+                    this._emit("reconnect-failed");
+                }
+                return;
+            }
+
+            this.isReconnecting = true;
+            const interval = Math.min(this.options.reconnectBaseInterval * Math.pow(2, this.reconnectAttempts), this.options.maxReconnectInterval);
+
+            console.log(`[WS] ${interval / 1000}秒后将尝试第 ${this.reconnectAttempts + 1} 次重连...`);
+            this._emit("reconnect-attempt", { attempt: this.reconnectAttempts + 1, interval });
+
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectAttempts++;
+                this.connect();
+            }, interval);
+        }
+
+        _clearReconnectTimer() {
+            if (this.reconnectTimer) {
+                clearTimeout(this.reconnectTimer);
+                this.reconnectTimer = null;
+            }
+        }
+
+        // --- 消息队列 ---
+        _flushMessageQueue() {
+            if (this.messageQueue.length === 0) return;
+            console.log(`[WS] 发送队列中的 ${this.messageQueue.length} 条消息`);
+            const queue = [...this.messageQueue];
+            this.messageQueue = [];
+            queue.forEach((data) => this.send(data));
+        }
+
+        // --- 事件系统 ---
+        _emit(eventName, ...args) {
+            if (this.listeners.has(eventName)) {
+                this.listeners.get(eventName).forEach((callback) => callback(...args));
+            }
+        }
+
+        // --- 状态与监听器管理 ---
+        _updateReadyState(newState) {
+            this.readyState = newState;
+            this._emit("ready-state-change", newState);
+        }
+
+        _setupEventListeners() {
+            document.addEventListener("visibilitychange", this._handleVisibilityChange);
+            window.addEventListener("online", this._handleOnline);
+            window.addEventListener("offline", this._handleOffline);
+        }
+
+        _removeEventListeners() {
+            document.removeEventListener("visibilitychange", this._handleVisibilityChange);
+            window.removeEventListener("online", this._handleOnline);
+            window.removeEventListener("offline", this._handleOffline);
+        }
+
+        _handleVisibilityChange() {
+            // 如果未启用心跳，不需要处理页面可见性变化
+            if (!this.options.getPingMessage) {
+                return;
+            }
+
+            if (document.hidden) {
+                console.log("[WS] 页面隐藏，停止心跳");
+                this._stopHeartbeat();
+            } else {
+                console.log("[WS] 页面可见，检查连接状态");
+                if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                    this._startHeartbeat();
+                } else if (!this.forcedClose && !this.isReconnecting) {
+                    this.connect();
+                }
+            }
+        }
+
+        _handleOnline() {
+            console.log("[WS] 网络已恢复，尝试重连");
+            if (!this.forcedClose && this.readyState !== WebSocket.OPEN) {
+                this._clearReconnectTimer(); // 清除当前的重连计划
+                this.connect(); // 立即尝试连接
+            }
+        }
+
+        _handleOffline() {
+            console.log("[WS] 网络已断开");
+            this._clearReconnectTimer(); // 停止重连尝试
+            // ws.onclose 会被触发，从而启动重连逻辑，但我们已经停止了
+            // 所以这里可以手动触发一次 close 事件来通知应用层
+            if (this.ws) this.ws.onclose({ code: 1006, reason: "Network offline" });
+        }
     }
 
     exports.AudioStreamResampler = AudioStreamResampler;
@@ -1875,7 +2105,6 @@ registerProcessor('audio-stream-resampler-processor', AudioStreamResamplerProces
     exports.MyId = MyId;
     exports.WebSocketManager = WebSocketManager;
     exports.assignExisting = assignExisting;
-    exports.calcTimeDifference = calcTimeDifference;
     exports.debounce = debounce;
     exports.deepCloneByJSON = deepCloneByJSON;
     exports.downloadByBlob = downloadByBlob;
@@ -1887,14 +2116,13 @@ registerProcessor('audio-stream-resampler-processor', AudioStreamResamplerProces
     exports.fetchOrDownloadByUrl = fetchOrDownloadByUrl;
     exports.findObjAttrValueById = findObjAttrValueById;
     exports.flatCompleteTree2NestedTree = flatCompleteTree2NestedTree;
-    exports.formatDuration = formatDuration;
-    exports.formatDurationMaxDay = formatDurationMaxDay;
-    exports.formatDurationMaxHour = formatDurationMaxHour;
+    exports.formatTimeForLocale = formatTimeForLocale;
     exports.getAllSearchParams = getAllSearchParams;
     exports.getDataType = getDataType;
     exports.getFunctionArgNames = getFunctionArgNames;
     exports.getGUID = getGUID;
     exports.getSearchParam = getSearchParam;
+    exports.getTimePeriodName = getTimePeriodName;
     exports.getViewportSize = getViewportSize;
     exports.isBlob = isBlob;
     exports.isDate = isDate;
@@ -1902,6 +2130,9 @@ registerProcessor('audio-stream-resampler-processor', AudioStreamResamplerProces
     exports.isNonEmptyString = isNonEmptyString;
     exports.isPlainObject = isPlainObject;
     exports.isPromise = isPromise;
+    exports.millisecond2Duration = millisecond2Duration;
+    exports.millisecond2DurationMaxDay = millisecond2DurationMaxDay;
+    exports.millisecond2DurationMaxHour = millisecond2DurationMaxHour;
     exports.moveItem = moveItem;
     exports.nestedTree2IdMap = nestedTree2IdMap;
     exports.pcmToWavBlob = pcmToWavBlob;
@@ -1911,6 +2142,9 @@ registerProcessor('audio-stream-resampler-processor', AudioStreamResamplerProces
     exports.randomHanOrEn = randomHanOrEn;
     exports.randomIntInRange = randomIntInRange;
     exports.readBlobAsText = readBlobAsText;
+    exports.second2Duration = second2Duration;
+    exports.second2DurationMaxDay = second2DurationMaxDay;
+    exports.second2DurationMaxHour = second2DurationMaxHour;
     exports.shuffle = shuffle;
     exports.throttle = throttle;
     exports.toDate = toDate;