a2bei4-utils 1.0.2 → 1.0.4

package/dist/a2bei4.utils.esm.js

@@ -1,1866 +1,2096 @@
-/**
- * 使用 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)));
+/**
+ * 视口尺寸对象。
+ * @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];
 }
 
-/**
- * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
- *
- * @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)
-    };
+//#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);
+    });
 }
 
-/**
- * 将总秒数格式化成人类可读的时间段文本。
- * 固定进制：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("");
+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 formatDurationMaxDay(totalSeconds, options = {}) {
-    return formatDuration(totalSeconds, { ...options, maxUnit: "day" });
-}
-
-/**
- * 快捷调用 {@link formatDuration}，最大单位到“小时”。
- *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
- */
-function formatDurationMaxHour(totalSeconds, options = {}) {
-    return formatDuration(totalSeconds, { ...options, maxUnit: "hour" });
-}
-
-/**
- * 通过动态创建 `<a>` 标签触发浏览器下载。
- * 注意：此方法可能无法强制下载浏览器原生支持的文件（如图片、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;
-    }
+/**
+ * 生成 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");
+    }
 }
 
-/**
- * 把嵌套树拍平成 `{ [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;
+/**
+ * 基于 `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;
+    }
 }
 
-/**
- * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。
- *
- * @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]: 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]
+    };
 }
 
-/**
- * 在嵌套树中按 `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" });
+    }
 }
 
-export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };
+export { AudioStreamResampler, IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, WebSocketManager, assignExisting, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, extractFullyCheckedKeys, fetchOrDownloadByUrl, findObjAttrValueById, flatCompleteTree2NestedTree, formatTimeForLocale, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getTimePeriodName, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, moveItem, nestedTree2IdMap, pcmToWavBlob, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, second2Duration, second2DurationMaxDay, second2DurationMaxHour, shuffle, throttle, toDate };
 //# sourceMappingURL=a2bei4.utils.esm.js.map