a2bei4-utils 1.0.2 → 1.0.4

package/dist/webSocket.js.map

@@ -1 +1 @@
-{"version":3,"file":"webSocket.js","sources":["../src/source/webSocket.js"],"sourcesContent":["/**\n * @class WebSocketManager - 一个纯粹、强大的 WebSocket 连接管理引擎\n *\n * @features\n * - 智能断线重连 (指数退避算法)\n * - 网络状态监听\n * - 高度可定制的心跳保活机制 (通过注入函数实现)\n * - 页面可见性 API 集成\n * - 消息发送队列\n * - 清晰的生命周期管理\n * - 优雅的资源销毁\n * - 可配置的数据序列化/反序列化\n * - 纯粹的消息传递，不关心消息内容\n */\nexport class WebSocketManager {\n    /**\n     * @param {string} url - WebSocket 服务器的地址\n     * @param {object} [options={}] - 配置选项\n     * @param {number} [options.heartbeatInterval=30000] - 心跳间隔 (毫秒)\n     * @param {number} [options.heartbeatTimeout=10000] - 心跳超时时间 (毫秒)\n     * @param {number} [options.reconnectBaseInterval=1000] - 重连基础间隔 (毫秒)\n     * @param {number} [options.maxReconnectInterval=30000] - 最大重连间隔 (毫秒)\n     * @param {number} [options.maxReconnectAttempts=Infinity] - 最大重连次数\n     * @param {boolean} [options.autoConnect=true] - 是否在实例化后自动连接\n     * @param {boolean} [options.serializeData=false] - 发送数据时是否自动序列化为JSON字符串\n     * @param {boolean} [options.deserializeData=false] - 接收数据时是否自动反序列化为JSON对象\n     * @param {function|null} [options.getPingMessage=null] - 返回要发送的 ping 消息内容的函数。如果为 null，则不发送心跳。\n     * @param {function|null} [options.isPongMessage=null] - 判断接收到的消息是否为 pong 的函数。接收 MessageEvent 对象作为参数，返回布尔值。\n     * @param {object} [options.protocols] - WebSocket 协议\n     */\n    constructor(url, options = {}) {\n        this.url = url;\n\n        // 默认的心跳实现，用于向后兼容\n        const defaultGetPingMessage = () => JSON.stringify({ type: \"ping\" });\n        const defaultIsPongMessage = (event) => {\n            try {\n                const message = JSON.parse(event.data);\n                return message.type === \"pong\";\n            } catch (e) {\n                return false;\n            }\n        };\n\n        this.options = {\n            heartbeatInterval: 30000,\n            heartbeatTimeout: 10000,\n            reconnectBaseInterval: 1000,\n            maxReconnectInterval: 30000,\n            maxReconnectAttempts: Infinity,\n            autoConnect: true,\n            serializeData: false,\n            deserializeData: false,\n            getPingMessage: defaultGetPingMessage, // 默认提供 ping 消息生成器\n            isPongMessage: defaultIsPongMessage, // 默认提供 pong 消息判断器\n            ...options\n        };\n\n        // WebSocket 实例\n        this.ws = null;\n\n        // 状态管理\n        this.readyState = WebSocket.CLOSED;\n        this.reconnectAttempts = 0;\n        this.forcedClose = false;\n        this.isReconnecting = false;\n\n        // 定时器\n        this.heartbeatTimer = null;\n        this.heartbeatTimeoutTimer = null;\n        this.reconnectTimer = null;\n\n        // 消息队列\n        this.messageQueue = [];\n\n        // 事件监听器\n        this.listeners = new Map();\n\n        // 绑定方法上下文\n        this._onOpen = this._onOpen.bind(this);\n        this._onMessage = this._onMessage.bind(this);\n        this._onClose = this._onClose.bind(this);\n        this._onError = this._onError.bind(this);\n        this._handleVisibilityChange = this._handleVisibilityChange.bind(this);\n        this._handleOnline = this._handleOnline.bind(this);\n        this._handleOffline = this._handleOffline.bind(this);\n\n        this._setupEventListeners();\n\n        if (this.options.autoConnect) {\n            this.connect();\n        }\n    }\n\n    // --- 公共 API ---\n\n    /**\n     * 连接到 WebSocket 服务器\n     */\n    connect() {\n        if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {\n            return;\n        }\n\n        this.forcedClose = false;\n        this._updateReadyState(WebSocket.CONNECTING);\n        console.log(`[WS] 正在连接到 ${this.url}...`);\n        this._emit(\"connecting\");\n\n        try {\n            this.ws = new WebSocket(this.url, this.options.protocols);\n            this.ws.onopen = this._onOpen;\n            this.ws.onmessage = this._onMessage;\n            this.ws.onclose = this._onClose;\n            this.ws.onerror = this._onError;\n        } catch (error) {\n            console.error(\"[WS] 连接失败:\", error);\n            this._onError(error);\n        }\n    }\n\n    /**\n     * 发送数据\n     * @param {string|object|ArrayBuffer|Blob} data - 要发送的数据\n     */\n    send(data) {\n        if (this.readyState === WebSocket.OPEN) {\n            let message;\n            // 根据配置决定是否序列化数据\n            if (this.options.serializeData) {\n                message = JSON.stringify(data);\n            } else {\n                message = data;\n            }\n            this.ws.send(message);\n            console.log(\"[WS] 消息已发送:\", message);\n        } else {\n            console.warn(\"[WS] 连接未打开，消息已加入队列:\", data);\n            this.messageQueue.push(data);\n        }\n    }\n\n    /**\n     * 主动关闭连接\n     * @param {number} [code=1000] - 关闭代码\n     * @param {string} [reason=''] - 关闭原因\n     */\n    close(code = 1000, reason = \"Normal closure\") {\n        this.forcedClose = true;\n        this._stopHeartbeat();\n        this._clearReconnectTimer();\n        if (this.ws && this.ws.readyState === WebSocket.OPEN) {\n            this.ws.close(code, reason);\n        } else {\n            this._updateReadyState(WebSocket.CLOSED);\n            this._emit(\"close\", { code, reason, wasClean: true });\n        }\n    }\n\n    /**\n     * 彻底销毁实例，清理所有资源\n     */\n    destroy() {\n        console.log(\"[WS] 正在销毁实例...\");\n        this.close(1000, \"Instance destroyed\");\n        this._removeEventListeners();\n        this.messageQueue = [];\n        this.listeners.clear();\n        this.ws = null;\n    }\n\n    /**\n     * 添加事件监听器\n     * @param {string} eventName - 事件名 (e.g., 'open', 'message', 'close', 'error', 'reconnect')\n     * @param {function} callback - 回调函数\n     */\n    on(eventName, callback) {\n        if (!this.listeners.has(eventName)) {\n            this.listeners.set(eventName, []);\n        }\n        this.listeners.get(eventName).push(callback);\n    }\n\n    /**\n     * 移除事件监听器\n     * @param {string} eventName - 事件名\n     * @param {function} callback - 回调函数\n     */\n    off(eventName, callback) {\n        if (this.listeners.has(eventName)) {\n            const callbacks = this.listeners.get(eventName);\n            const index = callbacks.indexOf(callback);\n            if (index > -1) {\n                callbacks.splice(index, 1);\n            }\n        }\n    }\n\n    // --- 内部方法 ---\n\n    _onOpen(event) {\n        console.log(\"[WS] 连接已建立\");\n        this._updateReadyState(WebSocket.OPEN);\n        this.reconnectAttempts = 0;\n        this.isReconnecting = false;\n\n        // 如果配置了 getPingMessage，则启动心跳\n        if (this.options.getPingMessage) {\n            this._startHeartbeat();\n        }\n\n        this._flushMessageQueue();\n        this._emit(\"open\", event);\n    }\n\n    /**\n     * 纯粹的消息处理方法：处理心跳，然后将数据交给使用者\n     * @param {MessageEvent} event\n     */\n    _onMessage(event) {\n        // --- 步骤 1: 使用注入的函数优先处理内部心跳机制 ---\n        if (this.options.isPongMessage && this.options.isPongMessage(event)) {\n            this._handlePong();\n            return; // 是心跳消息，处理完毕，直接返回\n        }\n\n        // --- 步骤 2: 根据用户配置处理业务消息 ---\n        if (this.options.deserializeData) {\n            try {\n                const parsedMessage = JSON.parse(event.data);\n                this._emit(\"message\", parsedMessage, event);\n            } catch (e) {\n                this._emit(\"message\", event.data, event);\n            }\n        } else {\n            this._emit(\"message\", event.data, event);\n        }\n    }\n\n    _onClose(event) {\n        console.log(\"[WS] 连接已关闭\", event);\n        this._updateReadyState(WebSocket.CLOSED);\n        this._stopHeartbeat();\n        this._emit(\"close\", event);\n\n        if (!this.forcedClose) {\n            this._scheduleReconnect();\n        }\n    }\n\n    _onError(event) {\n        console.error(\"[WS] 连接发生错误:\", event);\n        this._emit(\"error\", event);\n    }\n\n    // --- 心跳机制 ---\n    _startHeartbeat() {\n        // 如果没有配置 getPingMessage，则无法启动心跳\n        if (!this.options.getPingMessage) {\n            return;\n        }\n\n        this._stopHeartbeat();\n        this.heartbeatTimer = setInterval(() => {\n            if (this.ws && this.ws.readyState === WebSocket.OPEN) {\n                try {\n                    // 调用注入的函数获取消息内容并发送\n                    const pingMessage = this.options.getPingMessage();\n                    this.ws.send(pingMessage);\n                    console.log(\"[WS] 发送 Ping:\", pingMessage);\n                    this._setHeartbeatTimeout();\n                } catch (error) {\n                    console.error(\"[WS] 发送 Ping 消息失败:\", error);\n                }\n            }\n        }, this.options.heartbeatInterval);\n    }\n\n    _stopHeartbeat() {\n        if (this.heartbeatTimer) {\n            clearInterval(this.heartbeatTimer);\n            this.heartbeatTimer = null;\n        }\n        this._clearHeartbeatTimeout();\n    }\n\n    _setHeartbeatTimeout() {\n        this._clearHeartbeatTimeout();\n        this.heartbeatTimeoutTimer = setTimeout(() => {\n            console.error(\"[WS] 心跳超时，主动断开连接\");\n            this.ws.close(1006, \"Heartbeat timeout\");\n        }, this.options.heartbeatTimeout);\n    }\n\n    _clearHeartbeatTimeout() {\n        if (this.heartbeatTimeoutTimer) {\n            clearTimeout(this.heartbeatTimeoutTimer);\n            this.heartbeatTimeoutTimer = null;\n        }\n    }\n\n    _handlePong() {\n        console.log(\"[WS] 收到 Pong\");\n        this._clearHeartbeatTimeout();\n    }\n\n    // --- 重连机制 ---\n    _scheduleReconnect() {\n        if (this.forcedClose || this.isReconnecting || this.reconnectAttempts >= this.options.maxReconnectAttempts) {\n            if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {\n                console.error(\"[WS] 已达到最大重连次数，停止重连\");\n                this._emit(\"reconnect-failed\");\n            }\n            return;\n        }\n\n        this.isReconnecting = true;\n        const interval = Math.min(this.options.reconnectBaseInterval * Math.pow(2, this.reconnectAttempts), this.options.maxReconnectInterval);\n\n        console.log(`[WS] ${interval / 1000}秒后将尝试第 ${this.reconnectAttempts + 1} 次重连...`);\n        this._emit(\"reconnect-attempt\", { attempt: this.reconnectAttempts + 1, interval });\n\n        this.reconnectTimer = setTimeout(() => {\n            this.reconnectAttempts++;\n            this.connect();\n        }, interval);\n    }\n\n    _clearReconnectTimer() {\n        if (this.reconnectTimer) {\n            clearTimeout(this.reconnectTimer);\n            this.reconnectTimer = null;\n        }\n    }\n\n    // --- 消息队列 ---\n    _flushMessageQueue() {\n        if (this.messageQueue.length === 0) return;\n        console.log(`[WS] 发送队列中的 ${this.messageQueue.length} 条消息`);\n        const queue = [...this.messageQueue];\n        this.messageQueue = [];\n        queue.forEach((data) => this.send(data));\n    }\n\n    // --- 事件系统 ---\n    _emit(eventName, ...args) {\n        if (this.listeners.has(eventName)) {\n            this.listeners.get(eventName).forEach((callback) => callback(...args));\n        }\n    }\n\n    // --- 状态与监听器管理 ---\n    _updateReadyState(newState) {\n        this.readyState = newState;\n        this._emit(\"ready-state-change\", newState);\n    }\n\n    _setupEventListeners() {\n        document.addEventListener(\"visibilitychange\", this._handleVisibilityChange);\n        window.addEventListener(\"online\", this._handleOnline);\n        window.addEventListener(\"offline\", this._handleOffline);\n    }\n\n    _removeEventListeners() {\n        document.removeEventListener(\"visibilitychange\", this._handleVisibilityChange);\n        window.removeEventListener(\"online\", this._handleOnline);\n        window.removeEventListener(\"offline\", this._handleOffline);\n    }\n\n    _handleVisibilityChange() {\n        // 如果未启用心跳，不需要处理页面可见性变化\n        if (!this.options.getPingMessage) {\n            return;\n        }\n\n        if (document.hidden) {\n            console.log(\"[WS] 页面隐藏，停止心跳\");\n            this._stopHeartbeat();\n        } else {\n            console.log(\"[WS] 页面可见，检查连接状态\");\n            if (this.ws && this.ws.readyState === WebSocket.OPEN) {\n                this._startHeartbeat();\n            } else if (!this.forcedClose && !this.isReconnecting) {\n                this.connect();\n            }\n        }\n    }\n\n    _handleOnline() {\n        console.log(\"[WS] 网络已恢复，尝试重连\");\n        if (!this.forcedClose && this.readyState !== WebSocket.OPEN) {\n            this._clearReconnectTimer(); // 清除当前的重连计划\n            this.connect(); // 立即尝试连接\n        }\n    }\n\n    _handleOffline() {\n        console.log(\"[WS] 网络已断开\");\n        this._clearReconnectTimer(); // 停止重连尝试\n        // ws.onclose 会被触发，从而启动重连逻辑，但我们已经停止了\n        // 所以这里可以手动触发一次 close 事件来通知应用层\n        if (this.ws) this.ws.onclose({ code: 1006, reason: \"Network offline\" });\n    }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"webSocket.js","sources":["../src/source/webSocket.js"],"sourcesContent":["/**\r\n * @class WebSocketManager - 一个纯粹、强大的 WebSocket 连接管理引擎\r\n *\r\n * @features\r\n * - 智能断线重连 (指数退避算法)\r\n * - 网络状态监听\r\n * - 高度可定制的心跳保活机制 (通过注入函数实现)\r\n * - 页面可见性 API 集成\r\n * - 消息发送队列\r\n * - 清晰的生命周期管理\r\n * - 优雅的资源销毁\r\n * - 可配置的数据序列化/反序列化\r\n * - 纯粹的消息传递，不关心消息内容\r\n */\r\nexport class WebSocketManager {\r\n    /**\r\n     * @param {string} url - WebSocket 服务器的地址\r\n     * @param {object} [options={}] - 配置选项\r\n     * @param {number} [options.heartbeatInterval=30000] - 心跳间隔 (毫秒)\r\n     * @param {number} [options.heartbeatTimeout=10000] - 心跳超时时间 (毫秒)\r\n     * @param {number} [options.reconnectBaseInterval=1000] - 重连基础间隔 (毫秒)\r\n     * @param {number} [options.maxReconnectInterval=30000] - 最大重连间隔 (毫秒)\r\n     * @param {number} [options.maxReconnectAttempts=Infinity] - 最大重连次数\r\n     * @param {boolean} [options.autoConnect=true] - 是否在实例化后自动连接\r\n     * @param {boolean} [options.serializeData=false] - 发送数据时是否自动序列化为JSON字符串\r\n     * @param {boolean} [options.deserializeData=false] - 接收数据时是否自动反序列化为JSON对象\r\n     * @param {function|null} [options.getPingMessage=null] - 返回要发送的 ping 消息内容的函数。如果为 null，则不发送心跳。\r\n     * @param {function|null} [options.isPongMessage=null] - 判断接收到的消息是否为 pong 的函数。接收 MessageEvent 对象作为参数，返回布尔值。\r\n     * @param {object} [options.protocols] - WebSocket 协议\r\n     */\r\n    constructor(url, options = {}) {\r\n        this.url = url;\r\n\r\n        // 默认的心跳实现，用于向后兼容\r\n        const defaultGetPingMessage = () => JSON.stringify({ type: \"ping\" });\r\n        const defaultIsPongMessage = (event) => {\r\n            try {\r\n                const message = JSON.parse(event.data);\r\n                return message.type === \"pong\";\r\n            } catch (e) {\r\n                return false;\r\n            }\r\n        };\r\n\r\n        this.options = {\r\n            heartbeatInterval: 30000,\r\n            heartbeatTimeout: 10000,\r\n            reconnectBaseInterval: 1000,\r\n            maxReconnectInterval: 30000,\r\n            maxReconnectAttempts: Infinity,\r\n            autoConnect: true,\r\n            serializeData: false,\r\n            deserializeData: false,\r\n            getPingMessage: defaultGetPingMessage, // 默认提供 ping 消息生成器\r\n            isPongMessage: defaultIsPongMessage, // 默认提供 pong 消息判断器\r\n            ...options\r\n        };\r\n\r\n        // WebSocket 实例\r\n        this.ws = null;\r\n\r\n        // 状态管理\r\n        this.readyState = WebSocket.CLOSED;\r\n        this.reconnectAttempts = 0;\r\n        this.forcedClose = false;\r\n        this.isReconnecting = false;\r\n\r\n        // 定时器\r\n        this.heartbeatTimer = null;\r\n        this.heartbeatTimeoutTimer = null;\r\n        this.reconnectTimer = null;\r\n\r\n        // 消息队列\r\n        this.messageQueue = [];\r\n\r\n        // 事件监听器\r\n        this.listeners = new Map();\r\n\r\n        // 绑定方法上下文\r\n        this._onOpen = this._onOpen.bind(this);\r\n        this._onMessage = this._onMessage.bind(this);\r\n        this._onClose = this._onClose.bind(this);\r\n        this._onError = this._onError.bind(this);\r\n        this._handleVisibilityChange = this._handleVisibilityChange.bind(this);\r\n        this._handleOnline = this._handleOnline.bind(this);\r\n        this._handleOffline = this._handleOffline.bind(this);\r\n\r\n        this._setupEventListeners();\r\n\r\n        if (this.options.autoConnect) {\r\n            this.connect();\r\n        }\r\n    }\r\n\r\n    // --- 公共 API ---\r\n\r\n    /**\r\n     * 连接到 WebSocket 服务器\r\n     */\r\n    connect() {\r\n        if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {\r\n            return;\r\n        }\r\n\r\n        this.forcedClose = false;\r\n        this._updateReadyState(WebSocket.CONNECTING);\r\n        console.log(`[WS] 正在连接到 ${this.url}...`);\r\n        this._emit(\"connecting\");\r\n\r\n        try {\r\n            this.ws = new WebSocket(this.url, this.options.protocols);\r\n            this.ws.onopen = this._onOpen;\r\n            this.ws.onmessage = this._onMessage;\r\n            this.ws.onclose = this._onClose;\r\n            this.ws.onerror = this._onError;\r\n        } catch (error) {\r\n            console.error(\"[WS] 连接失败:\", error);\r\n            this._onError(error);\r\n        }\r\n    }\r\n\r\n    /**\r\n     * 发送数据\r\n     * @param {string|object|ArrayBuffer|Blob} data - 要发送的数据\r\n     */\r\n    send(data) {\r\n        if (this.readyState === WebSocket.OPEN) {\r\n            let message;\r\n            // 根据配置决定是否序列化数据\r\n            if (this.options.serializeData) {\r\n                message = JSON.stringify(data);\r\n            } else {\r\n                message = data;\r\n            }\r\n            this.ws.send(message);\r\n            console.log(\"[WS] 消息已发送:\", message);\r\n        } else {\r\n            console.warn(\"[WS] 连接未打开，消息已加入队列:\", data);\r\n            this.messageQueue.push(data);\r\n        }\r\n    }\r\n\r\n    /**\r\n     * 主动关闭连接\r\n     * @param {number} [code=1000] - 关闭代码\r\n     * @param {string} [reason=''] - 关闭原因\r\n     */\r\n    close(code = 1000, reason = \"Normal closure\") {\r\n        this.forcedClose = true;\r\n        this._stopHeartbeat();\r\n        this._clearReconnectTimer();\r\n        if (this.ws && this.ws.readyState === WebSocket.OPEN) {\r\n            this.ws.close(code, reason);\r\n        } else {\r\n            this._updateReadyState(WebSocket.CLOSED);\r\n            this._emit(\"close\", { code, reason, wasClean: true });\r\n        }\r\n    }\r\n\r\n    /**\r\n     * 彻底销毁实例，清理所有资源\r\n     */\r\n    destroy() {\r\n        console.log(\"[WS] 正在销毁实例...\");\r\n        this.close(1000, \"Instance destroyed\");\r\n        this._removeEventListeners();\r\n        this.messageQueue = [];\r\n        this.listeners.clear();\r\n        this.ws = null;\r\n    }\r\n\r\n    /**\r\n     * 添加事件监听器\r\n     * @param {string} eventName - 事件名 (e.g., 'open', 'message', 'close', 'error', 'reconnect')\r\n     * @param {function} callback - 回调函数\r\n     */\r\n    on(eventName, callback) {\r\n        if (!this.listeners.has(eventName)) {\r\n            this.listeners.set(eventName, []);\r\n        }\r\n        this.listeners.get(eventName).push(callback);\r\n    }\r\n\r\n    /**\r\n     * 移除事件监听器\r\n     * @param {string} eventName - 事件名\r\n     * @param {function} callback - 回调函数\r\n     */\r\n    off(eventName, callback) {\r\n        if (this.listeners.has(eventName)) {\r\n            const callbacks = this.listeners.get(eventName);\r\n            const index = callbacks.indexOf(callback);\r\n            if (index > -1) {\r\n                callbacks.splice(index, 1);\r\n            }\r\n        }\r\n    }\r\n\r\n    // --- 内部方法 ---\r\n\r\n    _onOpen(event) {\r\n        console.log(\"[WS] 连接已建立\");\r\n        this._updateReadyState(WebSocket.OPEN);\r\n        this.reconnectAttempts = 0;\r\n        this.isReconnecting = false;\r\n\r\n        // 如果配置了 getPingMessage，则启动心跳\r\n        if (this.options.getPingMessage) {\r\n            this._startHeartbeat();\r\n        }\r\n\r\n        this._flushMessageQueue();\r\n        this._emit(\"open\", event);\r\n    }\r\n\r\n    /**\r\n     * 纯粹的消息处理方法：处理心跳，然后将数据交给使用者\r\n     * @param {MessageEvent} event\r\n     */\r\n    _onMessage(event) {\r\n        // --- 步骤 1: 使用注入的函数优先处理内部心跳机制 ---\r\n        if (this.options.isPongMessage && this.options.isPongMessage(event)) {\r\n            this._handlePong();\r\n            return; // 是心跳消息，处理完毕，直接返回\r\n        }\r\n\r\n        // --- 步骤 2: 根据用户配置处理业务消息 ---\r\n        if (this.options.deserializeData) {\r\n            try {\r\n                const parsedMessage = JSON.parse(event.data);\r\n                this._emit(\"message\", parsedMessage, event);\r\n            } catch (e) {\r\n                this._emit(\"message\", event.data, event);\r\n            }\r\n        } else {\r\n            this._emit(\"message\", event.data, event);\r\n        }\r\n    }\r\n\r\n    _onClose(event) {\r\n        console.log(\"[WS] 连接已关闭\", event);\r\n        this._updateReadyState(WebSocket.CLOSED);\r\n        this._stopHeartbeat();\r\n        this._emit(\"close\", event);\r\n\r\n        if (!this.forcedClose) {\r\n            this._scheduleReconnect();\r\n        }\r\n    }\r\n\r\n    _onError(event) {\r\n        console.error(\"[WS] 连接发生错误:\", event);\r\n        this._emit(\"error\", event);\r\n    }\r\n\r\n    // --- 心跳机制 ---\r\n    _startHeartbeat() {\r\n        // 如果没有配置 getPingMessage，则无法启动心跳\r\n        if (!this.options.getPingMessage) {\r\n            return;\r\n        }\r\n\r\n        this._stopHeartbeat();\r\n        this.heartbeatTimer = setInterval(() => {\r\n            if (this.ws && this.ws.readyState === WebSocket.OPEN) {\r\n                try {\r\n                    // 调用注入的函数获取消息内容并发送\r\n                    const pingMessage = this.options.getPingMessage();\r\n                    this.ws.send(pingMessage);\r\n                    console.log(\"[WS] 发送 Ping:\", pingMessage);\r\n                    this._setHeartbeatTimeout();\r\n                } catch (error) {\r\n                    console.error(\"[WS] 发送 Ping 消息失败:\", error);\r\n                }\r\n            }\r\n        }, this.options.heartbeatInterval);\r\n    }\r\n\r\n    _stopHeartbeat() {\r\n        if (this.heartbeatTimer) {\r\n            clearInterval(this.heartbeatTimer);\r\n            this.heartbeatTimer = null;\r\n        }\r\n        this._clearHeartbeatTimeout();\r\n    }\r\n\r\n    _setHeartbeatTimeout() {\r\n        this._clearHeartbeatTimeout();\r\n        this.heartbeatTimeoutTimer = setTimeout(() => {\r\n            console.error(\"[WS] 心跳超时，主动断开连接\");\r\n            this.ws.close(1006, \"Heartbeat timeout\");\r\n        }, this.options.heartbeatTimeout);\r\n    }\r\n\r\n    _clearHeartbeatTimeout() {\r\n        if (this.heartbeatTimeoutTimer) {\r\n            clearTimeout(this.heartbeatTimeoutTimer);\r\n            this.heartbeatTimeoutTimer = null;\r\n        }\r\n    }\r\n\r\n    _handlePong() {\r\n        console.log(\"[WS] 收到 Pong\");\r\n        this._clearHeartbeatTimeout();\r\n    }\r\n\r\n    // --- 重连机制 ---\r\n    _scheduleReconnect() {\r\n        if (this.forcedClose || this.isReconnecting || this.reconnectAttempts >= this.options.maxReconnectAttempts) {\r\n            if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {\r\n                console.error(\"[WS] 已达到最大重连次数，停止重连\");\r\n                this._emit(\"reconnect-failed\");\r\n            }\r\n            return;\r\n        }\r\n\r\n        this.isReconnecting = true;\r\n        const interval = Math.min(this.options.reconnectBaseInterval * Math.pow(2, this.reconnectAttempts), this.options.maxReconnectInterval);\r\n\r\n        console.log(`[WS] ${interval / 1000}秒后将尝试第 ${this.reconnectAttempts + 1} 次重连...`);\r\n        this._emit(\"reconnect-attempt\", { attempt: this.reconnectAttempts + 1, interval });\r\n\r\n        this.reconnectTimer = setTimeout(() => {\r\n            this.reconnectAttempts++;\r\n            this.connect();\r\n        }, interval);\r\n    }\r\n\r\n    _clearReconnectTimer() {\r\n        if (this.reconnectTimer) {\r\n            clearTimeout(this.reconnectTimer);\r\n            this.reconnectTimer = null;\r\n        }\r\n    }\r\n\r\n    // --- 消息队列 ---\r\n    _flushMessageQueue() {\r\n        if (this.messageQueue.length === 0) return;\r\n        console.log(`[WS] 发送队列中的 ${this.messageQueue.length} 条消息`);\r\n        const queue = [...this.messageQueue];\r\n        this.messageQueue = [];\r\n        queue.forEach((data) => this.send(data));\r\n    }\r\n\r\n    // --- 事件系统 ---\r\n    _emit(eventName, ...args) {\r\n        if (this.listeners.has(eventName)) {\r\n            this.listeners.get(eventName).forEach((callback) => callback(...args));\r\n        }\r\n    }\r\n\r\n    // --- 状态与监听器管理 ---\r\n    _updateReadyState(newState) {\r\n        this.readyState = newState;\r\n        this._emit(\"ready-state-change\", newState);\r\n    }\r\n\r\n    _setupEventListeners() {\r\n        document.addEventListener(\"visibilitychange\", this._handleVisibilityChange);\r\n        window.addEventListener(\"online\", this._handleOnline);\r\n        window.addEventListener(\"offline\", this._handleOffline);\r\n    }\r\n\r\n    _removeEventListeners() {\r\n        document.removeEventListener(\"visibilitychange\", this._handleVisibilityChange);\r\n        window.removeEventListener(\"online\", this._handleOnline);\r\n        window.removeEventListener(\"offline\", this._handleOffline);\r\n    }\r\n\r\n    _handleVisibilityChange() {\r\n        // 如果未启用心跳，不需要处理页面可见性变化\r\n        if (!this.options.getPingMessage) {\r\n            return;\r\n        }\r\n\r\n        if (document.hidden) {\r\n            console.log(\"[WS] 页面隐藏，停止心跳\");\r\n            this._stopHeartbeat();\r\n        } else {\r\n            console.log(\"[WS] 页面可见，检查连接状态\");\r\n            if (this.ws && this.ws.readyState === WebSocket.OPEN) {\r\n                this._startHeartbeat();\r\n            } else if (!this.forcedClose && !this.isReconnecting) {\r\n                this.connect();\r\n            }\r\n        }\r\n    }\r\n\r\n    _handleOnline() {\r\n        console.log(\"[WS] 网络已恢复，尝试重连\");\r\n        if (!this.forcedClose && this.readyState !== WebSocket.OPEN) {\r\n            this._clearReconnectTimer(); // 清除当前的重连计划\r\n            this.connect(); // 立即尝试连接\r\n        }\r\n    }\r\n\r\n    _handleOffline() {\r\n        console.log(\"[WS] 网络已断开\");\r\n        this._clearReconnectTimer(); // 停止重连尝试\r\n        // ws.onclose 会被触发，从而启动重连逻辑，但我们已经停止了\r\n        // 所以这里可以手动触发一次 close 事件来通知应用层\r\n        if (this.ws) this.ws.onclose({ code: 1006, reason: \"Network offline\" });\r\n    }\r\n}\r\n"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAM,gBAAgB,CAAC;AAC9B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,EAAE,EAAE;AACnC,QAAQ,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;AACvB;AACA;AACA,QAAQ,MAAM,qBAAqB,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AAC7E,QAAQ,MAAM,oBAAoB,GAAG,CAAC,KAAK,KAAK;AAChD,YAAY,IAAI;AAChB,gBAAgB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACvD,gBAAgB,OAAO,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC;AAC/C,YAAY,CAAC,CAAC,OAAO,CAAC,EAAE;AACxB,gBAAgB,OAAO,KAAK,CAAC;AAC7B,YAAY,CAAC;AACb,QAAQ,CAAC,CAAC;AACV;AACA,QAAQ,IAAI,CAAC,OAAO,GAAG;AACvB,YAAY,iBAAiB,EAAE,KAAK;AACpC,YAAY,gBAAgB,EAAE,KAAK;AACnC,YAAY,qBAAqB,EAAE,IAAI;AACvC,YAAY,oBAAoB,EAAE,KAAK;AACvC,YAAY,oBAAoB,EAAE,QAAQ;AAC1C,YAAY,WAAW,EAAE,IAAI;AAC7B,YAAY,aAAa,EAAE,KAAK;AAChC,YAAY,eAAe,EAAE,KAAK;AAClC,YAAY,cAAc,EAAE,qBAAqB;AACjD,YAAY,aAAa,EAAE,oBAAoB;AAC/C,YAAY,GAAG,OAAO;AACtB,SAAS,CAAC;AACV;AACA;AACA,QAAQ,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;AACvB;AACA;AACA,QAAQ,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC;AAC3C,QAAQ,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;AACnC,QAAQ,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;AACjC,QAAQ,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;AACpC;AACA;AACA,QAAQ,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;AACnC,QAAQ,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;AAC1C,QAAQ,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;AACnC;AACA;AACA,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;AAC/B;AACA;AACA,QAAQ,IAAI,CAAC,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;AACnC;AACA;AACA,QAAQ,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/C,QAAQ,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrD,QAAQ,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjD,QAAQ,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjD,QAAQ,IAAI,CAAC,uBAAuB,GAAG,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/E,QAAQ,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3D,QAAQ,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7D;AACA,QAAQ,IAAI,CAAC,oBAAoB,EAAE,CAAC;AACpC;AACA,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE;AACtC,YAAY,IAAI,CAAC,OAAO,EAAE,CAAC;AAC3B,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,OAAO,GAAG;AACd,QAAQ,IAAI,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,UAAU,IAAI,IAAI,CAAC,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,CAAC,EAAE;AAC/G,YAAY,OAAO;AACnB,QAAQ,CAAC;AACT;AACA,QAAQ,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;AACjC,QAAQ,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;AACrD,QAAQ,OAAO,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AACjD,QAAQ,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACjC;AACA,QAAQ,IAAI;AACZ,YAAY,IAAI,CAAC,EAAE,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AACtE,YAAY,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;AAC1C,YAAY,IAAI,CAAC,EAAE,CAAC,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC;AAChD,YAAY,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;AAC5C,YAAY,IAAI,CAAC,EAAE,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;AAC5C,QAAQ,CAAC,CAAC,OAAO,KAAK,EAAE;AACxB,YAAY,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AAC/C,YAAY,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACjC,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA;AACA;AACA;AACA,IAAI,IAAI,CAAC,IAAI,EAAE;AACf,QAAQ,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE;AAChD,YAAY,IAAI,OAAO,CAAC;AACxB;AACA,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE;AAC5C,gBAAgB,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC/C,YAAY,CAAC,MAAM;AACnB,gBAAgB,OAAO,GAAG,IAAI,CAAC;AAC/B,YAAY,CAAC;AACb,YAAY,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAClC,YAAY,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AAChD,QAAQ,CAAC,MAAM;AACf,YAAY,OAAO,CAAC,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;AACtD,YAAY,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzC,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,KAAK,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE;AAClD,QAAQ,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;AAChC,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;AAC9B,QAAQ,IAAI,CAAC,oBAAoB,EAAE,CAAC;AACpC,QAAQ,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE;AAC9D,YAAY,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACxC,QAAQ,CAAC,MAAM;AACf,YAAY,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACrD,YAAY,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;AAClE,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA;AACA;AACA,IAAI,OAAO,GAAG;AACd,QAAQ,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACtC,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;AAC/C,QAAQ,IAAI,CAAC,qBAAqB,EAAE,CAAC;AACrC,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;AAC/B,QAAQ,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;AAC/B,QAAQ,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;AACvB,IAAI,CAAC;AACL;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE;AAC5B,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;AAC5C,YAAY,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AAC9C,QAAQ,CAAC;AACT,QAAQ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACrD,IAAI,CAAC;AACL;AACA;AACA;AACA;AACA;AACA;AACA,IAAI,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE;AAC7B,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;AAC3C,YAAY,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAC5D,YAAY,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACtD,YAAY,IAAI,KAAK,GAAG,EAAE,EAAE;AAC5B,gBAAgB,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAC3C,YAAY,CAAC;AACb,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA;AACA,IAAI,OAAO,CAAC,KAAK,EAAE;AACnB,QAAQ,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAClC,QAAQ,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC/C,QAAQ,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;AACnC,QAAQ,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;AACpC;AACA;AACA,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE;AACzC,YAAY,IAAI,CAAC,eAAe,EAAE,CAAC;AACnC,QAAQ,CAAC;AACT;AACA,QAAQ,IAAI,CAAC,kBAAkB,EAAE,CAAC;AAClC,QAAQ,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAClC,IAAI,CAAC;AACL;AACA;AACA;AACA;AACA;AACA,IAAI,UAAU,CAAC,KAAK,EAAE;AACtB;AACA,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE;AAC7E,YAAY,IAAI,CAAC,WAAW,EAAE,CAAC;AAC/B,YAAY,OAAO;AACnB,QAAQ,CAAC;AACT;AACA;AACA,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE;AAC1C,YAAY,IAAI;AAChB,gBAAgB,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7D,gBAAgB,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;AAC5D,YAAY,CAAC,CAAC,OAAO,CAAC,EAAE;AACxB,gBAAgB,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACzD,YAAY,CAAC;AACb,QAAQ,CAAC,MAAM;AACf,YAAY,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACrD,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA,IAAI,QAAQ,CAAC,KAAK,EAAE;AACpB,QAAQ,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;AACzC,QAAQ,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AACjD,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;AAC9B,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACnC;AACA,QAAQ,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;AAC/B,YAAY,IAAI,CAAC,kBAAkB,EAAE,CAAC;AACtC,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA,IAAI,QAAQ,CAAC,KAAK,EAAE;AACpB,QAAQ,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AAC7C,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACnC,IAAI,CAAC;AACL;AACA;AACA,IAAI,eAAe,GAAG;AACtB;AACA,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE;AAC1C,YAAY,OAAO;AACnB,QAAQ,CAAC;AACT;AACA,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;AAC9B,QAAQ,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,MAAM;AAChD,YAAY,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE;AAClE,gBAAgB,IAAI;AACpB;AACA,oBAAoB,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;AACtE,oBAAoB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAC9C,oBAAoB,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;AAC9D,oBAAoB,IAAI,CAAC,oBAAoB,EAAE,CAAC;AAChD,gBAAgB,CAAC,CAAC,OAAO,KAAK,EAAE;AAChC,oBAAoB,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;AAC/D,gBAAgB,CAAC;AACjB,YAAY,CAAC;AACb,QAAQ,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAC3C,IAAI,CAAC;AACL;AACA,IAAI,cAAc,GAAG;AACrB,QAAQ,IAAI,IAAI,CAAC,cAAc,EAAE;AACjC,YAAY,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC/C,YAAY,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;AACvC,QAAQ,CAAC;AACT,QAAQ,IAAI,CAAC,sBAAsB,EAAE,CAAC;AACtC,IAAI,CAAC;AACL;AACA,IAAI,oBAAoB,GAAG;AAC3B,QAAQ,IAAI,CAAC,sBAAsB,EAAE,CAAC;AACtC,QAAQ,IAAI,CAAC,qBAAqB,GAAG,UAAU,CAAC,MAAM;AACtD,YAAY,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;AAC9C,YAAY,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;AACrD,QAAQ,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAC1C,IAAI,CAAC;AACL;AACA,IAAI,sBAAsB,GAAG;AAC7B,QAAQ,IAAI,IAAI,CAAC,qBAAqB,EAAE;AACxC,YAAY,YAAY,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AACrD,YAAY,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;AAC9C,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA,IAAI,WAAW,GAAG;AAClB,QAAQ,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AACpC,QAAQ,IAAI,CAAC,sBAAsB,EAAE,CAAC;AACtC,IAAI,CAAC;AACL;AACA;AACA,IAAI,kBAAkB,GAAG;AACzB,QAAQ,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE;AACpH,YAAY,IAAI,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE;AAC7E,gBAAgB,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;AACrD,gBAAgB,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;AAC/C,YAAY,CAAC;AACb,YAAY,OAAO;AACnB,QAAQ,CAAC;AACT;AACA,QAAQ,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;AACnC,QAAQ,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAC/I;AACA,QAAQ,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAC1F,QAAQ,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,iBAAiB,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC3F;AACA,QAAQ,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,MAAM;AAC/C,YAAY,IAAI,CAAC,iBAAiB,EAAE,CAAC;AACrC,YAAY,IAAI,CAAC,OAAO,EAAE,CAAC;AAC3B,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;AACrB,IAAI,CAAC;AACL;AACA,IAAI,oBAAoB,GAAG;AAC3B,QAAQ,IAAI,IAAI,CAAC,cAAc,EAAE;AACjC,YAAY,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC9C,YAAY,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;AACvC,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA,IAAI,kBAAkB,GAAG;AACzB,QAAQ,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,OAAO;AACnD,QAAQ,OAAO,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,QAAQ,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;AAC7C,QAAQ,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;AAC/B,QAAQ,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,IAAI,CAAC;AACL;AACA;AACA,IAAI,KAAK,CAAC,SAAS,EAAE,GAAG,IAAI,EAAE;AAC9B,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;AAC3C,YAAY,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACnF,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA;AACA,IAAI,iBAAiB,CAAC,QAAQ,EAAE;AAChC,QAAQ,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC;AACnC,QAAQ,IAAI,CAAC,KAAK,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACnD,IAAI,CAAC;AACL;AACA,IAAI,oBAAoB,GAAG;AAC3B,QAAQ,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,IAAI,CAAC,uBAAuB,CAAC,CAAC;AACpF,QAAQ,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;AAC9D,QAAQ,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;AAChE,IAAI,CAAC;AACL;AACA,IAAI,qBAAqB,GAAG;AAC5B,QAAQ,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,IAAI,CAAC,uBAAuB,CAAC,CAAC;AACvF,QAAQ,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;AACjE,QAAQ,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;AACnE,IAAI,CAAC;AACL;AACA,IAAI,uBAAuB,GAAG;AAC9B;AACA,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE;AAC1C,YAAY,OAAO;AACnB,QAAQ,CAAC;AACT;AACA,QAAQ,IAAI,QAAQ,CAAC,MAAM,EAAE;AAC7B,YAAY,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAC1C,YAAY,IAAI,CAAC,cAAc,EAAE,CAAC;AAClC,QAAQ,CAAC,MAAM;AACf,YAAY,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAC5C,YAAY,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE;AAClE,gBAAgB,IAAI,CAAC,eAAe,EAAE,CAAC;AACvC,YAAY,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE;AAClE,gBAAgB,IAAI,CAAC,OAAO,EAAE,CAAC;AAC/B,YAAY,CAAC;AACb,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA,IAAI,aAAa,GAAG;AACpB,QAAQ,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AACvC,QAAQ,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE;AACrE,YAAY,IAAI,CAAC,oBAAoB,EAAE,CAAC;AACxC,YAAY,IAAI,CAAC,OAAO,EAAE,CAAC;AAC3B,QAAQ,CAAC;AACT,IAAI,CAAC;AACL;AACA,IAAI,cAAc,GAAG;AACrB,QAAQ,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAClC,QAAQ,IAAI,CAAC,oBAAoB,EAAE,CAAC;AACpC;AACA;AACA,QAAQ,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;AAChF,IAAI,CAAC;AACL;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2bei4-utils",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "🧰 零依赖、ESM 的 JS 业务工具箱：数组乱序/深浅克隆、防抖节流、URL/query 解析、Date/时长格式化、随机汉字/字母、文件下载、事件总线、UUID/分布式短 ID、树结构互转等 40+ 常用函数 & 类，Tree-Shaking 友好。",
   "private": false,
   "type": "module",

package/readme.txt

@@ -2,20 +2,30 @@
 
 -->  官方 npm 仓库地址： https://registry.npmjs.org/
 -->  阿里云 npm 仓库地址： https://registry.npmmirror.com/
--->  --registry 显示指定的仓库地址，如：http://192.168.x.x:4873
+-->  --registry 显示指定的仓库地址，如： http://192.168.x.x:4873
 
+0、清理
+    # 清理 pnpm 缓存
+    pnpm store prune
 
-0、首次安装依赖
-pnpm i -D @rollup/plugin-commonjs @rollup/plugin-node-resolve @rollup/plugin-terser prettier rollup rollup-plugin-dts rollup-plugin-filesize typescript
+    # 删除 node_modules 和 lock 文件：
+    #   使用 PowerShell 原生命令，-ErrorAction SilentlyContinue 可以防止路径不存在时报错
+    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue node_modules, pnpm-lock.yaml
 
-1、如果没有用户，先注册用户
-pnpm adduser --registry https://registry.npmjs.org/
+    #   使用 CMD 原生命令，/s 表示递归删除，/q 表示安静模式，不提示确认
+    rmdir /s /q node_modules & del /f pnpm-lock.yaml
 
-2、用户登录
-pnpm login --registry https://registry.npmjs.org/
+1、首次安装依赖
+    pnpm i -D @rollup/plugin-commonjs @rollup/plugin-node-resolve @rollup/plugin-terser prettier rollup rollup-plugin-dts rollup-plugin-filesize typescript
 
-3、发布
-pnpm publish --registry https://registry.npmjs.org/
+2、如果没有用户，先注册用户
+    pnpm adduser --registry https://registry.npmjs.org/
 
-4、撤销发布
-pnpm unpublish a2bei4-utils --force --registry https://registry.npmjs.org/
+3、用户登录
+    pnpm login --registry https://registry.npmjs.org/
+
+4、发布
+    pnpm publish --registry https://registry.npmjs.org/
+
+5、撤销发布
+    pnpm unpublish a2bei4-utils --force --registry https://registry.npmjs.org/

package/types/date.d.ts

@@ -19,59 +19,257 @@ declare function toDate(val: any): Date | null;
  */
 declare function randomDateInRange(date1: Date, date2: Date): Date;
 /**
- * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ * @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 不是正整数
  *
- * @param {string|number|Date} originalTime - 原始时间（可转 Date 的任意值）
- * @param {Date} [currentTime=new Date()] - 基准时间，默认当前
- * @returns {{days:number,hours:string,minutes:string,seconds:string}}
+ * @example
+ * // 基本用法
+ * millisecond2Duration(42070000500);
+ * // 返回: { years: 1, months: 4, days: 1, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
  */
-declare function calcTimeDifference(originalTime: string | number | Date, currentTime?: Date): {
-    days: number;
-    hours: string;
-    minutes: string;
-    seconds: string;
-};
+declare function millisecond2Duration(milliseconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
 /**
- * 将总秒数格式化成人类可读的时间段文本。
- * 固定进制：1 年=365 天，1 月=30 天。
+ * 将毫秒转换为时间持续对象（最大单位为天）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxDayObject} 包含天、小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { days: 486, hours: 22, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxDay(42070000500);
+ */
+declare function millisecond2DurationMaxDay(milliseconds: number): DurationMaxDayObject;
+/**
+ * 将毫秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} milliseconds - 毫秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 milliseconds 不是有效数字时抛出
+ * @throws {RangeError} 当 milliseconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * millisecond2DurationMaxHour(42070000500);
+ */
+declare function millisecond2DurationMaxHour(milliseconds: number): DurationMaxHourObject;
+/**
+ * 将秒转换为时间持续对象。
  *
- * @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 为非数字或负数时抛出
- */
-declare function formatDuration(totalSeconds: number, options?: {
-    labels?: Partial<{
-        year: string;
-        month: string;
-        day: string;
-        hour: string;
-        minute: string;
-        second: string;
-    }> | undefined;
-    maxUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    minUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
-    showZero?: boolean | undefined;
-}): string;
+ * @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 }
+ */
+declare function second2Duration(seconds: number, options?: {
+    yearDays?: number | undefined;
+    monthDays?: number | undefined;
+}): DurationObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为天）。
+ * @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);
+ */
+declare function second2DurationMaxDay(seconds: number): DurationMaxDayObject;
+/**
+ * 将秒转换为时间持续对象（最大单位为小时）。
+ * @param {number} seconds - 秒数（非负整数）
+ * @returns {DurationMaxHourObject} 包含小时、分钟、秒、毫秒的时间持续对象
+ * @throws {TypeError} 当 seconds 不是有效数字时抛出
+ * @throws {RangeError} 当 seconds 为负数时抛出
+ * @example
+ * // 返回 { hours: 11686, minutes: 6, seconds: 40, milliseconds: 500 }
+ * second2DurationMaxHour(42070000.5);
+ */
+declare function second2DurationMaxHour(seconds: number): DurationMaxHourObject;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“天”。
+ * 根据小时数返回对应的时间段名称。
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @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 范围时抛出
  */
-declare function formatDurationMaxDay(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function getTimePeriodName(hour: number, locales?: {
+    earlyMorning?: string | undefined;
+    morning?: string | undefined;
+    noon?: string | undefined;
+    afternoon?: string | undefined;
+    evening?: string | undefined;
+}): string;
 /**
- * 快捷调用 {@link formatDuration}，最大单位到“小时”。
+ * 格式化时间戳为本地化的时间字符串。
+ *
+ * @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=['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六']] - 星期几的本地化字符串数组。
  *
- * @param {number} totalSeconds
- * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
- * @returns {string}
+ * @returns {string} - 格式化后的时间字符串。
  */
-declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+declare function formatTimeForLocale(timestamp: number, locales?: {
+    justNow?: string | undefined;
+    today?: string | undefined;
+    yesterday?: string | undefined;
+    beforeYesterday?: string | undefined;
+    year?: string | undefined;
+    month?: string | undefined;
+    day?: string | undefined;
+    timePeriod?: {
+        earlyMorning?: string | undefined;
+        morning?: string | undefined;
+        noon?: string | undefined;
+        afternoon?: string | undefined;
+        evening?: string | undefined;
+    } | undefined;
+    weekDays?: string[] | undefined;
+}): string;
+/**
+ * 时间持续对象（完整版本，包含年月日时分秒毫秒）
+ */
+type DurationObject = {
+    /**
+     * - 年数
+     */
+    years: number;
+    /**
+     * - 月数（0-11）
+     */
+    months: number;
+    /**
+     * - 天数（0-29，取决于 monthDays）
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为天）
+ */
+type DurationMaxDayObject = {
+    /**
+     * - 天数
+     */
+    days: number;
+    /**
+     * - 小时数（0-23）
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
+/**
+ * 时间持续对象（最大单位为小时）
+ */
+type DurationMaxHourObject = {
+    /**
+     * - 小时数
+     */
+    hours: number;
+    /**
+     * - 分钟数（0-59）
+     */
+    minutes: number;
+    /**
+     * - 秒数（0-59）
+     */
+    seconds: number;
+    /**
+     * - 毫秒数（0-999）
+     */
+    milliseconds: number;
+};
 
-export { calcTimeDifference, formatDuration, formatDurationMaxDay, formatDurationMaxHour, randomDateInRange, toDate };
+export { formatTimeForLocale, getTimePeriodName, millisecond2Duration, millisecond2DurationMaxDay, millisecond2DurationMaxHour, randomDateInRange, second2Duration, second2DurationMaxDay, second2DurationMaxHour, toDate };
+export type { DurationMaxDayObject, DurationMaxHourObject, DurationObject };