a2bei4-utils 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +2 -2
  3. package/dist/a2bei4.utils.cjs.js +1051 -250
  4. package/dist/a2bei4.utils.cjs.js.map +1 -1
  5. package/dist/a2bei4.utils.cjs.min.js +1 -1
  6. package/dist/a2bei4.utils.cjs.min.js.map +1 -1
  7. package/dist/a2bei4.utils.esm.js +1047 -251
  8. package/dist/a2bei4.utils.esm.js.map +1 -1
  9. package/dist/a2bei4.utils.esm.min.js +1 -1
  10. package/dist/a2bei4.utils.esm.min.js.map +1 -1
  11. package/dist/a2bei4.utils.umd.js +1051 -250
  12. package/dist/a2bei4.utils.umd.js.map +1 -1
  13. package/dist/a2bei4.utils.umd.min.js +1 -1
  14. package/dist/a2bei4.utils.umd.min.js.map +1 -1
  15. package/dist/arr.cjs +27 -27
  16. package/dist/arr.cjs.map +1 -1
  17. package/dist/arr.js +27 -27
  18. package/dist/arr.js.map +1 -1
  19. package/dist/audio.cjs +281 -0
  20. package/dist/audio.cjs.map +1 -0
  21. package/dist/audio.js +278 -0
  22. package/dist/audio.js.map +1 -0
  23. package/dist/common.cjs +6 -6
  24. package/dist/common.cjs.map +1 -1
  25. package/dist/common.js +6 -6
  26. package/dist/common.js.map +1 -1
  27. package/dist/download.cjs +43 -0
  28. package/dist/download.cjs.map +1 -1
  29. package/dist/download.js +43 -1
  30. package/dist/download.js.map +1 -1
  31. package/dist/evt.cjs +148 -148
  32. package/dist/evt.cjs.map +1 -1
  33. package/dist/evt.js +148 -148
  34. package/dist/evt.js.map +1 -1
  35. package/dist/id.cjs +68 -68
  36. package/dist/id.cjs.map +1 -1
  37. package/dist/id.js +68 -68
  38. package/dist/id.js.map +1 -1
  39. package/dist/timer.cjs +0 -1
  40. package/dist/timer.cjs.map +1 -1
  41. package/dist/timer.js +0 -1
  42. package/dist/timer.js.map +1 -1
  43. package/dist/tree.cjs +75 -0
  44. package/dist/tree.cjs.map +1 -1
  45. package/dist/tree.js +75 -1
  46. package/dist/tree.js.map +1 -1
  47. package/dist/webSocket.cjs +409 -0
  48. package/dist/webSocket.cjs.map +1 -0
  49. package/dist/webSocket.js +407 -0
  50. package/dist/webSocket.js.map +1 -0
  51. package/package.json +11 -1
  52. package/readme.txt +8 -5
  53. package/types/audio.d.ts +57 -0
  54. package/types/download.d.ts +12 -1
  55. package/types/index.d.ts +207 -1
  56. package/types/tree.d.ts +17 -1
  57. package/types/webSocket.d.ts +124 -0
@@ -1,30 +1,306 @@
1
- /**
2
- * 使用 Fisher-Yates 算法对数组 **原地** 随机乱序。
3
- * @template T
4
- * @param {T[]} arr - 要乱序的数组
5
- * @returns {T[]} 返回传入的同一数组实例(已乱序)
6
- */
7
- function shuffle(arr) {
8
- // 方式一:
9
- // arr.sort(() => Math.random() - 0.5);
10
- // 方式二:
11
- for (let i = arr.length - 1; i > 0; i--) {
12
- const j = Math.floor(Math.random() * (i + 1));
13
- [arr[i], arr[j]] = [arr[j], arr[i]];
14
- }
15
- return arr;
16
- }
17
-
18
- /**
19
- * 将数组中的元素从 `fromIndex` 移动到 `toIndex`,**原地** 修改并返回该数组。
20
- * @template T
21
- * @param {T[]} arr - 要操作的数组
22
- * @param {number} fromIndex - 原始下标
23
- * @param {number} toIndex - 目标下标
24
- * @returns {T[]} 返回传入的同一数组实例
25
- */
26
- function moveItem(arr, fromIndex, toIndex) {
27
- arr.splice(toIndex, 0, arr.splice(fromIndex, 1)[0]);
1
+ /**
2
+ * 使用 Fisher-Yates 算法对数组 **原地** 随机乱序。
3
+ * @template T
4
+ * @param {T[]} arr - 要乱序的数组
5
+ * @returns {T[]} 返回传入的同一数组实例(已乱序)
6
+ */
7
+ function shuffle(arr) {
8
+ // 方式一:
9
+ // arr.sort(() => Math.random() - 0.5);
10
+ // 方式二:
11
+ for (let i = arr.length - 1; i > 0; i--) {
12
+ const j = Math.floor(Math.random() * (i + 1));
13
+ [arr[i], arr[j]] = [arr[j], arr[i]];
14
+ }
15
+ return arr;
16
+ }
17
+
18
+ /**
19
+ * 将数组中的元素从 `fromIndex` 移动到 `toIndex`,**原地** 修改并返回该数组。
20
+ * @template T
21
+ * @param {T[]} arr - 要操作的数组
22
+ * @param {number} fromIndex - 原始下标
23
+ * @param {number} toIndex - 目标下标
24
+ * @returns {T[]} 返回传入的同一数组实例
25
+ */
26
+ function moveItem(arr, fromIndex, toIndex) {
27
+ arr.splice(toIndex, 0, arr.splice(fromIndex, 1)[0]);
28
+ }
29
+
30
+ const AudioStreamResamplerProcessorCode = `
31
+ class AudioStreamResamplerProcessor extends AudioWorkletProcessor {
32
+ constructor(options) {
33
+ super();
34
+ const config = options.processorOptions || {};
35
+ this.targetSampleRate = config.targetSampleRate || 16000;
36
+ this.sourceSampleRate = sampleRate;
37
+ this.downsampleRatio = this.sourceSampleRate / this.targetSampleRate;
38
+
39
+ // 16000Hz 用 60ms chunk (960 samples),其他用 1024
40
+ this.chunkSize = this.targetSampleRate === 16000 ? 960 : 1024;
41
+
42
+ const sourceBufferSize = config.sourceBufferSize || 16384; // ~340ms @48kHz
43
+ const pcmBufferSize = config.pcmBufferSize || (this.chunkSize * 10); // 更大缓冲,减少溢出概率
44
+
45
+ this.sourceBuffer = new Float32Array(sourceBufferSize);
46
+ this.sourceBufferLength = 0;
47
+
48
+ this.pcmBuffer = new Int16Array(pcmBufferSize);
49
+ this.pcmBufferIndex = 0;
50
+ }
51
+
52
+ process(inputs, outputs, parameters) {
53
+ const input = inputs[0];
54
+ if (!input || input.length === 0 || input[0].length === 0) return true;
55
+ const inputChannel = input[0];
56
+
57
+ // 1. 写入源缓冲区(溢出时覆盖最旧数据)
58
+ const newLength = this.sourceBufferLength + inputChannel.length;
59
+ if (newLength > this.sourceBuffer.length) {
60
+ const overflow = newLength - this.sourceBuffer.length;
61
+ this.sourceBuffer.copyWithin(0, overflow);
62
+ this.sourceBufferLength = this.sourceBuffer.length - inputChannel.length;
63
+ }
64
+ this.sourceBuffer.set(inputChannel, this.sourceBufferLength);
65
+ this.sourceBufferLength += inputChannel.length;
66
+
67
+ // 2. 计算可降采样样本数
68
+ const availableOutputSamples = Math.floor(this.sourceBufferLength / this.downsampleRatio);
69
+ if (availableOutputSamples === 0) return true;
70
+
71
+ // 3. 线性插值降采样
72
+ const downsampled = new Float32Array(availableOutputSamples);
73
+ for (let i = 0; i < availableOutputSamples; i++) {
74
+ const srcIndex = i * this.downsampleRatio;
75
+ const srcIndexInt = Math.floor(srcIndex);
76
+ const fraction = srcIndex - srcIndexInt;
77
+ const val0 = this.sourceBuffer[srcIndexInt];
78
+ const val1 = srcIndexInt + 1 < this.sourceBufferLength ? this.sourceBuffer[srcIndexInt + 1] : val0;
79
+ downsampled[i] = val0 + (val1 - val0) * fraction;
80
+ }
81
+
82
+ // 4. Float32 → Int16 PCM
83
+ const pcmData = this.floatTo16BitPCM(downsampled);
84
+
85
+ // 5. 写入 PCM 缓冲区(空间不足时直接覆盖最旧,缓冲区足够大基本不会触发)
86
+ if (this.pcmBufferIndex + pcmData.length > this.pcmBuffer.length) {
87
+ // 简单策略:从头覆盖(丢弃最旧数据)
88
+ this.pcmBufferIndex = 0;
89
+ }
90
+ this.pcmBuffer.set(pcmData, this.pcmBufferIndex);
91
+ this.pcmBufferIndex += pcmData.length;
92
+
93
+ // 6. 发送所有完整的 chunk(关键:复制到新数组再转移)
94
+ while (this.pcmBufferIndex >= this.chunkSize) {
95
+ // 方法1:推荐,使用 slice(隐式复制到新 ArrayBuffer)
96
+ const chunk = this.pcmBuffer.slice(0, this.chunkSize);
97
+
98
+ // 方法2:等价写法
99
+ // const chunk = new Int16Array(this.pcmBuffer.subarray(0, this.chunkSize));
100
+
101
+ this.port.postMessage(chunk, [chunk.buffer]); // 转移新缓冲区,安全!
102
+
103
+ // 移动剩余数据到开头
104
+ this.pcmBuffer.copyWithin(0, this.chunkSize, this.pcmBufferIndex);
105
+ this.pcmBufferIndex -= this.chunkSize;
106
+ }
107
+
108
+ // 7. 清理已消费的源数据
109
+ const consumedSrc = Math.floor(availableOutputSamples * this.downsampleRatio + 0.5); // 四舍五入更准
110
+ if (consumedSrc > 0) {
111
+ this.sourceBuffer.copyWithin(0, consumedSrc, this.sourceBufferLength);
112
+ this.sourceBufferLength -= consumedSrc;
113
+ }
114
+
115
+ return true;
116
+ }
117
+
118
+ floatTo16BitPCM(input) {
119
+ const output = new Int16Array(input.length);
120
+ for (let i = 0; i < input.length; i++) {
121
+ const s = Math.max(-1, Math.min(1, input[i]));
122
+ output[i] = s < 0 ? s * 0x8000 : s * 0x7FFF;
123
+ }
124
+ return output;
125
+ }
126
+ }
127
+
128
+ registerProcessor('audio-stream-resampler-processor', AudioStreamResamplerProcessor);
129
+ `;
130
+
131
+ /**
132
+ * 浏览器端实时音频流重采样器。
133
+ * 基于 AudioWorklet 将麦克风/媒体流转换为 16 kHz、16-bit、单声道 PCM,
134
+ * 并通过回调逐块输出,可选保存完整 PCM 用于后续合并。
135
+ */
136
+ class AudioStreamResampler {
137
+ /**
138
+ * @param {object} config
139
+ * @param {function(Int16Array)} config.onData - 收到一个 chunk PCM 数据的回调
140
+ * @param {function(string, string)} [config.onStateChange] - 状态变化回调
141
+ * @param {object} [config.processorOptions] - 传递给 AudioWorklet 的选项
142
+ * @param {boolean} [config.saveFullPcm=false] - 是否在内部保存所有 PCM 用于 stop 时合并(长时间录音建议关闭)
143
+ */
144
+ constructor(config) {
145
+ this.onData = config.onData || (() => {});
146
+ this.onStateChange = config.onStateChange || (() => {});
147
+ this.processorOptions = config.processorOptions || {};
148
+ this.saveFullPcm = config.saveFullPcm ?? false;
149
+
150
+ this.audioContext = null;
151
+ this.workletNode = null;
152
+ this.source = null;
153
+ this.workletUrl = null;
154
+ this.fullPcmData = this.saveFullPcm ? [] : null;
155
+
156
+ this.isInitialized = false;
157
+ this.isProcessing = false;
158
+ }
159
+
160
+ /**
161
+ * 初始化 AudioContext 并加载 AudioWorklet。
162
+ * 完成后状态变为 `"ready"`。
163
+ */
164
+ async init() {
165
+ this.onStateChange("initializing", "正在初始化音频环境...");
166
+ try {
167
+ this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
168
+
169
+ const blob = new Blob([AudioStreamResamplerProcessorCode], { type: "application/javascript" });
170
+ this.workletUrl = URL.createObjectURL(blob);
171
+ await this.audioContext.audioWorklet.addModule(this.workletUrl);
172
+
173
+ this.workletNode = new AudioWorkletNode(this.audioContext, "audio-stream-resampler-processor", {
174
+ processorOptions: this.processorOptions
175
+ });
176
+
177
+ this.workletNode.port.onmessage = (event) => {
178
+ const chunk = event.data; // Int16Array
179
+ this.onData(chunk);
180
+ if (this.saveFullPcm) {
181
+ this.fullPcmData.push(chunk);
182
+ }
183
+ };
184
+
185
+ this.isInitialized = true;
186
+ this.onStateChange("ready", "音频环境已就绪");
187
+ } catch (err) {
188
+ console.error("AudioStreamResampler init error:", err);
189
+ this.onStateChange("error", `初始化失败: ${err.message}`);
190
+ }
191
+ }
192
+
193
+ /**
194
+ * 绑定媒体流,开始实时处理。
195
+ * @param {MediaStream} stream - 通过 getUserMedia 或其他方式获得的流
196
+ */
197
+ setMediaStream(stream) {
198
+ if (!this.isInitialized) {
199
+ console.error("请先调用 init()");
200
+ return;
201
+ }
202
+
203
+ if (this.source) {
204
+ this.source.disconnect();
205
+ }
206
+
207
+ this.source = this.audioContext.createMediaStreamSource(stream);
208
+ this.source.connect(this.workletNode);
209
+ // workletNode 默认连接到 destination,可选断开以静音
210
+ // this.workletNode.connect(this.audioContext.destination);
211
+
212
+ this.isProcessing = true;
213
+ this.onStateChange("processing", "正在处理音频流...");
214
+ }
215
+
216
+ /**
217
+ * 停止处理并释放资源。
218
+ * @param {(fullPcm: Int16Array) => void} [callback] - 若构造时 `saveFullPcm=true`,会把合并后的完整 PCM 通过此回调传出
219
+ */
220
+ stop(callback) {
221
+ if (!this.isProcessing) return;
222
+
223
+ this.onStateChange("stopping", "正在停止...");
224
+
225
+ if (this.source) {
226
+ this.source.disconnect();
227
+ this.source = null;
228
+ }
229
+
230
+ this._cleanup();
231
+
232
+ this.onStateChange("stopped", "已停止");
233
+
234
+ if (this.saveFullPcm && callback && typeof callback === "function") {
235
+ const totalLength = this.fullPcmData.reduce((sum, chunk) => sum + chunk.length, 0);
236
+ const combined = new Int16Array(totalLength);
237
+ let offset = 0;
238
+ for (const chunk of this.fullPcmData) {
239
+ combined.set(chunk, offset);
240
+ offset += chunk.length;
241
+ }
242
+ callback(combined);
243
+ }
244
+ }
245
+
246
+ _cleanup() {
247
+ if (this.workletNode) {
248
+ this.workletNode.disconnect();
249
+ this.workletNode.port.close();
250
+ this.workletNode = null;
251
+ }
252
+ if (this.audioContext && this.audioContext.state !== "closed") {
253
+ this.audioContext.close();
254
+ this.audioContext = null;
255
+ }
256
+ if (this.workletUrl) {
257
+ URL.revokeObjectURL(this.workletUrl);
258
+ this.workletUrl = null;
259
+ }
260
+
261
+ this.isProcessing = false;
262
+ this.isInitialized = false;
263
+ if (this.fullPcmData) {
264
+ this.fullPcmData.length = 0;
265
+ }
266
+ }
267
+ }
268
+
269
+ /**
270
+ * 将 16-bit 单声道 PCM 数据封装成标准 WAV Blob。
271
+ *
272
+ * @param {Int16Array} pcmData - PCM 采样数据
273
+ * @param {number} [sampleRate=16000] - 采样率,默认 16 kHz
274
+ * @returns {Blob} audio/wav Blob
275
+ */
276
+ function pcmToWavBlob(pcmData, sampleRate = 16000) {
277
+ const length = pcmData.length;
278
+ const buffer = new ArrayBuffer(44 + length * 2);
279
+ const view = new DataView(buffer);
280
+ const writeString = (offset, string) => {
281
+ for (let i = 0; i < string.length; i++) {
282
+ view.setUint8(offset + i, string.charCodeAt(i));
283
+ }
284
+ };
285
+ writeString(0, "RIFF");
286
+ view.setUint32(4, 36 + length * 2, true);
287
+ writeString(8, "WAVE");
288
+ writeString(12, "fmt ");
289
+ view.setUint32(16, 16, true);
290
+ view.setUint16(20, 1, true);
291
+ view.setUint16(22, 1, true);
292
+ view.setUint32(24, sampleRate, true);
293
+ view.setUint32(28, sampleRate * 2, true);
294
+ view.setUint16(32, 2, true);
295
+ view.setUint16(34, 16, true);
296
+ writeString(36, "data");
297
+ view.setUint32(40, length * 2, true);
298
+ let offset = 44;
299
+ for (let i = 0; i < length; i++) {
300
+ view.setInt16(offset, pcmData[i], true);
301
+ offset += 2;
302
+ }
303
+ return new Blob([buffer], { type: "audio/wav" });
28
304
  }
29
305
 
30
306
  /**
@@ -85,7 +361,7 @@ function getSearchParam(key) {
85
361
 
86
362
  /**
87
363
  * 返回任意值的运行时类型字符串(小写形式)。
88
- *
364
+ *
89
365
  * @param {*} obj 待检测的值
90
366
  * @returns {keyof globalThis|"blob"|"file"|"formdata"|string} 小写类型名
91
367
  */
@@ -98,7 +374,7 @@ function getDataType(obj) {
98
374
 
99
375
  /**
100
376
  * 判断值是否为原生 Blob(含 File)。
101
- *
377
+ *
102
378
  * @param {*} obj - 待检测的值
103
379
  * @returns {obj is Blob}
104
380
  */
@@ -108,7 +384,7 @@ function isBlob(obj) {
108
384
 
109
385
  /**
110
386
  * 判断值是否为**纯粹**的 Object(即 `{}` 或 `new Object()`,不含数组、null、自定义类等)。
111
- *
387
+ *
112
388
  * @param {*} obj - 待检测的值
113
389
  * @returns {obj is Record<PropertyKey, any>}
114
390
  */
@@ -118,7 +394,7 @@ function isPlainObject(obj) {
118
394
 
119
395
  /**
120
396
  * 判断值是否为 Promise(含 Promise 子类)。
121
- *
397
+ *
122
398
  * @param {*} obj - 待检测的值
123
399
  * @returns {obj is Promise<any>}
124
400
  */
@@ -138,7 +414,7 @@ function isDate(t) {
138
414
 
139
415
  /**
140
416
  * 判断值是否为函数(含异步函数、生成器函数、类)。
141
- *
417
+ *
142
418
  * @param {*} obj - 待检测的值
143
419
  * @returns {obj is Function}
144
420
  */
@@ -148,7 +424,7 @@ function isFunction(obj) {
148
424
 
149
425
  /**
150
426
  * 判断值是否为**非空**字符串。
151
- *
427
+ *
152
428
  * @param {*} obj - 待检测的值
153
429
  * @returns {obj is string}
154
430
  */
@@ -640,6 +916,7 @@ function formatDurationMaxHour(totalSeconds, options = {}) {
640
916
 
641
917
  /**
642
918
  * 通过动态创建 `<a>` 标签触发浏览器下载。
919
+ * 注意:此方法可能无法强制下载浏览器原生支持的文件(如图片、PDF),浏览器可能会选择直接打开。
643
920
  *
644
921
  * @param {string} url - 任意可下载地址(同源或允许跨域)
645
922
  * @param {string} [fileName] - 保存到本地的文件名;不传时使用时间戳
@@ -700,224 +977,265 @@ function downloadJSON(data, fileName) {
700
977
  downloadByData(data, fileName, "application/json");
701
978
  }
702
979
 
703
- /**
704
- * 简单、高性能的通用事件总线。
705
- * - 支持命名空间事件
706
- * - 支持一次性监听器
707
- * - 返回唯一 flag,用于精确卸载
708
- * - emit 时可选自定义 this 指向
709
- */
710
- class MyEvent {
711
- constructor() {
712
- this.evtPool = new Map();
713
- }
714
-
715
- /**
716
- * 注册事件监听器。
717
- * @param {string} name - 事件名
718
- * @param {Function} fn - 回调函数
719
- * @returns {string} flag - 唯一标识,用于 off
720
- */
721
- on(name, fn) {
722
- let flag = Date.now() + "_" + parseInt(Math.random() * 1e8);
723
- const evtItem = {
724
- flag,
725
- fn
726
- };
727
- if (this.evtPool.has(name)) {
728
- this.evtPool.get(name).push(evtItem);
729
- } else {
730
- this.evtPool.set(name, [evtItem]);
731
- }
732
- return flag;
733
- }
734
-
735
- /**
736
- * 注册一次性监听器,触发后自动移除。
737
- * @param {string} name - 事件名
738
- * @param {Function} fn - 回调函数
739
- * @returns {string} flag - 唯一标识
740
- */
741
- once(name, fn) {
742
- const _this = this;
743
- let wrapper;
744
- wrapper = function (data) {
745
- _this.off(name, wrapper);
746
- fn.call(this, data);
747
- };
748
- return this.on(name, wrapper);
749
- }
750
-
751
- /**
752
- * 移除指定事件监听器。
753
- * @param {string} name - 事件名
754
- * @param {Function|string} fnOrFlag - 回调函数或 flag
755
- */
756
- off(name, fnOrFlag) {
757
- if (!this.evtPool.has(name)) return;
758
- const evtItems = this.evtPool.get(name);
759
- const filtered = evtItems.filter((item) => item.fn !== fnOrFlag && item.flag !== fnOrFlag);
760
- if (filtered.length === 0) {
761
- this.evtPool.delete(name);
762
- } else {
763
- this.evtPool.set(name, filtered);
764
- }
765
- }
766
-
767
- /**
768
- * 触发事件(同步执行)。
769
- * @param {string} name - 事件名
770
- * @param {*} [data] - 任意载荷
771
- * @param {*} [fnThis] - 回调内部 this 指向,默认 undefined
772
- */
773
- emit(name, data, fnThis) {
774
- if (!this.evtPool.has(name)) return;
775
- const evtItems = this.evtPool.get(name);
776
- evtItems.forEach((item) => {
777
- try {
778
- item.fn.call(fnThis, data);
779
- } catch (err) {
780
- console.error(`Error in event listener for "${name}":`, err);
781
- }
782
- });
783
- }
784
- }
785
-
786
- /**
787
- * 跨页通信插件:通过 localStorage + storage 事件将当前实例的 emit 广播到其他同源页面。
788
- * 支持节流、命名空间隔离。
789
- */
790
- const MyEvent_CrossPagePlugin = (() => {
791
- const INSTALLED = new WeakSet(); // 防止重复安装
792
-
793
- return {
794
- /**
795
- * 为指定 MyEvent 实例安装跨页插件。
796
- * @param {MyEvent} bus - 事件总线实例
797
- * @param {Options} [opts] - 配置项
798
- */
799
- install(bus, opts = {}) {
800
- if (INSTALLED.has(bus)) return;
801
- INSTALLED.add(bus);
802
-
803
- const ns = `___my-event-cross-page-${opts.namespace || "default"}___`;
804
- const delay = opts.throttle || 16;
805
- let last = 0;
806
-
807
- // 1、重写 emit
808
- const rawEmit = bus.emit;
809
- bus.emit = function (name, data, fnThis) {
810
- rawEmit.call(bus, name, data, fnThis); // 本地先执行
811
- const now = Date.now();
812
- if (now - last < delay) return;
813
- last = now;
814
- const key = ns + name;
815
- try {
816
- localStorage.setItem(key, JSON.stringify({ name, data, ts: now }));
817
- localStorage.removeItem(key); // 触发 storage 事件
818
- } catch (e) {}
819
- };
820
-
821
- // 2、监听其他页广播
822
- function onStorageHandler(e) {
823
- if (!e.key || !e.key.startsWith(ns)) return;
824
- let payload;
825
- try {
826
- payload = JSON.parse(e.newValue || "{}");
827
- } catch {
828
- return;
829
- }
830
- if (!payload.ts || payload.ts <= last) return;
831
- rawEmit.call(bus, e.key.slice(ns.length), payload.data); // 仅本地
832
- }
833
- addEventListener("storage", onStorageHandler);
834
-
835
- // 3、保存卸载器
836
- bus._uninstallCrossPage = () => {
837
- removeEventListener("storage", onStorageHandler);
838
- bus.emit = rawEmit;
839
- INSTALLED.delete(bus);
840
- };
841
- },
842
-
843
- /**
844
- * 卸载插件,恢复原始 emit 并停止监听。
845
- * @param {MyEvent} bus - 事件总线实例
846
- */
847
- uninstall(bus) {
848
- if (typeof bus._uninstallCrossPage === "function") bus._uninstallCrossPage();
849
- }
850
- };
980
+ /**
981
+ * 通过 `fetch` 获取资源并强制下载,避免浏览器直接打开文件。
982
+ * 此方法适用于下载图片、PDF 等浏览器默认会打开的文件类型。
983
+ * 如果 `fetch` 失败(如 CORS 策略阻止),会回退到 `downloadByUrl` 方法作为备选方案。
984
+ *
985
+ * @param {string} url - 文件的 URL 地址
986
+ * @param {string} [fileName] - 保存到本地的文件名。如果不提供,会尝试从 URL 中自动提取
987
+ * @returns {Promise<void>} 返回一个 Promise,在下载开始或失败后 resolve
988
+ */
989
+ async function fetchOrDownloadByUrl(url, fileName) {
990
+ // 如果未提供文件名,尝试从 URL 路径中提取
991
+ if (!fileName) {
992
+ try {
993
+ const urlPathname = new URL(url).pathname;
994
+ // 获取路径的最后一部分作为文件名,并移除可能的查询参数
995
+ fileName = urlPathname.substring(urlPathname.lastIndexOf("/") + 1).split("?")[0];
996
+ } catch (e) {}
997
+ // 如果提取后文件名为空(例如 URL 以 '/' 结尾),也使用时间戳
998
+ if (!fileName) {
999
+ fileName = Date.now().toString();
1000
+ }
1001
+ }
1002
+
1003
+ try {
1004
+ const response = await fetch(url, {
1005
+ method: "GET",
1006
+ mode: "cors",
1007
+ cache: "no-cache"
1008
+ });
1009
+
1010
+ if (!response.ok) {
1011
+ throw new Error(`HTTP error! ${response.status}: ${response.statusText}`);
1012
+ }
1013
+
1014
+ const blob = await response.blob();
1015
+ downloadByBlob(blob, fileName);
1016
+ } catch (error) {
1017
+ downloadByUrl(url, fileName);
1018
+ }
1019
+ }
1020
+
1021
+ /**
1022
+ * 简单、高性能的通用事件总线。
1023
+ * - 支持命名空间事件
1024
+ * - 支持一次性监听器
1025
+ * - 返回唯一 flag,用于精确卸载
1026
+ * - emit 时可选自定义 this 指向
1027
+ */
1028
+ class MyEvent {
1029
+ constructor() {
1030
+ this.evtPool = new Map();
1031
+ }
1032
+
1033
+ /**
1034
+ * 注册事件监听器。
1035
+ * @param {string} name - 事件名
1036
+ * @param {Function} fn - 回调函数
1037
+ * @returns {string} flag - 唯一标识,用于 off
1038
+ */
1039
+ on(name, fn) {
1040
+ let flag = Date.now() + "_" + parseInt(Math.random() * 1e8);
1041
+ const evtItem = {
1042
+ flag,
1043
+ fn
1044
+ };
1045
+ if (this.evtPool.has(name)) {
1046
+ this.evtPool.get(name).push(evtItem);
1047
+ } else {
1048
+ this.evtPool.set(name, [evtItem]);
1049
+ }
1050
+ return flag;
1051
+ }
1052
+
1053
+ /**
1054
+ * 注册一次性监听器,触发后自动移除。
1055
+ * @param {string} name - 事件名
1056
+ * @param {Function} fn - 回调函数
1057
+ * @returns {string} flag - 唯一标识
1058
+ */
1059
+ once(name, fn) {
1060
+ const _this = this;
1061
+ let wrapper;
1062
+ wrapper = function (data) {
1063
+ _this.off(name, wrapper);
1064
+ fn.call(this, data);
1065
+ };
1066
+ return this.on(name, wrapper);
1067
+ }
1068
+
1069
+ /**
1070
+ * 移除指定事件监听器。
1071
+ * @param {string} name - 事件名
1072
+ * @param {Function|string} fnOrFlag - 回调函数或 flag
1073
+ */
1074
+ off(name, fnOrFlag) {
1075
+ if (!this.evtPool.has(name)) return;
1076
+ const evtItems = this.evtPool.get(name);
1077
+ const filtered = evtItems.filter((item) => item.fn !== fnOrFlag && item.flag !== fnOrFlag);
1078
+ if (filtered.length === 0) {
1079
+ this.evtPool.delete(name);
1080
+ } else {
1081
+ this.evtPool.set(name, filtered);
1082
+ }
1083
+ }
1084
+
1085
+ /**
1086
+ * 触发事件(同步执行)。
1087
+ * @param {string} name - 事件名
1088
+ * @param {*} [data] - 任意载荷
1089
+ * @param {*} [fnThis] - 回调内部 this 指向,默认 undefined
1090
+ */
1091
+ emit(name, data, fnThis) {
1092
+ if (!this.evtPool.has(name)) return;
1093
+ const evtItems = this.evtPool.get(name);
1094
+ evtItems.forEach((item) => {
1095
+ try {
1096
+ item.fn.call(fnThis, data);
1097
+ } catch (err) {
1098
+ console.error(`Error in event listener for "${name}":`, err);
1099
+ }
1100
+ });
1101
+ }
1102
+ }
1103
+
1104
+ /**
1105
+ * 跨页通信插件:通过 localStorage + storage 事件将当前实例的 emit 广播到其他同源页面。
1106
+ * 支持节流、命名空间隔离。
1107
+ */
1108
+ const MyEvent_CrossPagePlugin = (() => {
1109
+ const INSTALLED = new WeakSet(); // 防止重复安装
1110
+
1111
+ return {
1112
+ /**
1113
+ * 为指定 MyEvent 实例安装跨页插件。
1114
+ * @param {MyEvent} bus - 事件总线实例
1115
+ * @param {Options} [opts] - 配置项
1116
+ */
1117
+ install(bus, opts = {}) {
1118
+ if (INSTALLED.has(bus)) return;
1119
+ INSTALLED.add(bus);
1120
+
1121
+ const ns = `___my-event-cross-page-${opts.namespace || "default"}___`;
1122
+ const delay = opts.throttle || 16;
1123
+ let last = 0;
1124
+
1125
+ // 1、重写 emit
1126
+ const rawEmit = bus.emit;
1127
+ bus.emit = function (name, data, fnThis) {
1128
+ rawEmit.call(bus, name, data, fnThis); // 本地先执行
1129
+ const now = Date.now();
1130
+ if (now - last < delay) return;
1131
+ last = now;
1132
+ const key = ns + name;
1133
+ try {
1134
+ localStorage.setItem(key, JSON.stringify({ name, data, ts: now }));
1135
+ localStorage.removeItem(key); // 触发 storage 事件
1136
+ } catch (e) {}
1137
+ };
1138
+
1139
+ // 2、监听其他页广播
1140
+ function onStorageHandler(e) {
1141
+ if (!e.key || !e.key.startsWith(ns)) return;
1142
+ let payload;
1143
+ try {
1144
+ payload = JSON.parse(e.newValue || "{}");
1145
+ } catch {
1146
+ return;
1147
+ }
1148
+ if (!payload.ts || payload.ts <= last) return;
1149
+ rawEmit.call(bus, e.key.slice(ns.length), payload.data); // 仅本地
1150
+ }
1151
+ addEventListener("storage", onStorageHandler);
1152
+
1153
+ // 3、保存卸载器
1154
+ bus._uninstallCrossPage = () => {
1155
+ removeEventListener("storage", onStorageHandler);
1156
+ bus.emit = rawEmit;
1157
+ INSTALLED.delete(bus);
1158
+ };
1159
+ },
1160
+
1161
+ /**
1162
+ * 卸载插件,恢复原始 emit 并停止监听。
1163
+ * @param {MyEvent} bus - 事件总线实例
1164
+ */
1165
+ uninstall(bus) {
1166
+ if (typeof bus._uninstallCrossPage === "function") bus._uninstallCrossPage();
1167
+ }
1168
+ };
851
1169
  })();
852
1170
 
853
- /**
854
- * 生成 RFC4122 版本 4 的 GUID/UUID。
855
- * 收集来源:《基于mvc的javascript web富应用开发》 书中介绍是Robert Kieffer写的,还留了网址 http://goo.gl/0b0hu ,但实际访问不了。
856
- * 格式:`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
857
- *
858
- * @returns {string} 36 位大写 GUID
859
- *
860
- * @example
861
- * // A2E0F340-6C3B-4D7F-B8C1-1E4F6A8B9C0D
862
- * console.log(getGUID())
863
- */
864
- function getGUID() {
865
- return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
866
- let r = (Math.random() * 16) | 0,
867
- v = c == "x" ? r : (r & 0x3) | 0x8;
868
- return v.toString(16).toUpperCase();
869
- });
870
- }
871
-
872
- /**
873
- * 分布式短 ID 生成器。
874
- * 格式:`${timestamp}${flag}${serial}`,其中:
875
- * - timestamp:毫秒级时间戳
876
- * - flag:客户端标识串(自定义)
877
- * - serial:同一毫秒内的序号,左补零到固定长度
878
- */
879
- class MyId {
880
- #ts = Date.now(); // 时间戳
881
- #sn = 0; // 序号(保证同一客户端之间的唯一项)
882
- #flag = ""; // 客户端标识(保证不同客户端之间的唯一项)
883
- #len = 5; // 序号位长度(我的电脑测试,同一时间戳内可以for循环执行了1000次左右,没有一次超过3k,所以5位应该够用了)
884
- // 测试代码
885
- // 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); }
886
-
887
- /**
888
- * @param {object} [option]
889
- * @param {string} [option.flag] - 客户端标识,默认空串
890
- * @param {number} [option.len=5] - 序号位长度(位数),安全范围 ≥0
891
- */
892
- constructor(option = {}) {
893
- if (option) {
894
- if (typeof option.flag === "string") {
895
- this.#flag = option.flag;
896
- }
897
- if (Number.isSafeInteger(option.len) && len >= 0) {
898
- this.#len = option.len;
899
- }
900
- }
901
- }
902
-
903
- /**
904
- * 生成下一个全局唯一字符串 ID。
905
- * 同一毫秒序号自动递增;序号溢出时会在控制台警告。
906
- * @returns {string}
907
- */
908
- nextId() {
909
- let ts = Date.now();
910
- if (ts === this.#ts) {
911
- this.#sn++;
912
- if (this.#sn >= 10 ** this.#len) {
913
- console.log("长度不够用了!!!");
914
- }
915
- } else {
916
- this.#sn = 0;
917
- this.#ts = ts;
918
- }
919
- return ts.toString() + this.#flag + this.#sn.toString().padStart(this.#len, "0");
920
- }
1171
+ /**
1172
+ * 生成 RFC4122 版本 4 的 GUID/UUID。
1173
+ * 收集来源:《基于mvc的javascript web富应用开发》 书中介绍是Robert Kieffer写的,还留了网址 http://goo.gl/0b0hu ,但实际访问不了。
1174
+ * 格式:`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
1175
+ *
1176
+ * @returns {string} 36 位大写 GUID
1177
+ *
1178
+ * @example
1179
+ * // A2E0F340-6C3B-4D7F-B8C1-1E4F6A8B9C0D
1180
+ * console.log(getGUID())
1181
+ */
1182
+ function getGUID() {
1183
+ return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
1184
+ let r = (Math.random() * 16) | 0,
1185
+ v = c == "x" ? r : (r & 0x3) | 0x8;
1186
+ return v.toString(16).toUpperCase();
1187
+ });
1188
+ }
1189
+
1190
+ /**
1191
+ * 分布式短 ID 生成器。
1192
+ * 格式:`${timestamp}${flag}${serial}`,其中:
1193
+ * - timestamp:毫秒级时间戳
1194
+ * - flag:客户端标识串(自定义)
1195
+ * - serial:同一毫秒内的序号,左补零到固定长度
1196
+ */
1197
+ class MyId {
1198
+ #ts = Date.now(); // 时间戳
1199
+ #sn = 0; // 序号(保证同一客户端之间的唯一项)
1200
+ #flag = ""; // 客户端标识(保证不同客户端之间的唯一项)
1201
+ #len = 5; // 序号位长度(我的电脑测试,同一时间戳内可以for循环执行了1000次左右,没有一次超过3k,所以5位应该够用了)
1202
+ // 测试代码
1203
+ // 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); }
1204
+
1205
+ /**
1206
+ * @param {object} [option]
1207
+ * @param {string} [option.flag] - 客户端标识,默认空串
1208
+ * @param {number} [option.len=5] - 序号位长度(位数),安全范围 ≥0
1209
+ */
1210
+ constructor(option = {}) {
1211
+ if (option) {
1212
+ if (typeof option.flag === "string") {
1213
+ this.#flag = option.flag;
1214
+ }
1215
+ if (Number.isSafeInteger(option.len) && len >= 0) {
1216
+ this.#len = option.len;
1217
+ }
1218
+ }
1219
+ }
1220
+
1221
+ /**
1222
+ * 生成下一个全局唯一字符串 ID。
1223
+ * 同一毫秒序号自动递增;序号溢出时会在控制台警告。
1224
+ * @returns {string}
1225
+ */
1226
+ nextId() {
1227
+ let ts = Date.now();
1228
+ if (ts === this.#ts) {
1229
+ this.#sn++;
1230
+ if (this.#sn >= 10 ** this.#len) {
1231
+ console.log("长度不够用了!!!");
1232
+ }
1233
+ } else {
1234
+ this.#sn = 0;
1235
+ this.#ts = ts;
1236
+ }
1237
+ return ts.toString() + this.#flag + this.#sn.toString().padStart(this.#len, "0");
1238
+ }
921
1239
  }
922
1240
 
923
1241
  /**
@@ -925,7 +1243,6 @@ class MyId {
925
1243
  * 每次任务执行完成后才计算下一次间隔,避免任务堆积。
926
1244
  */
927
1245
  class IntervalTimer {
928
-
929
1246
  /**
930
1247
  * 创建定时器实例。
931
1248
  * @param {() => void} fn - 每次间隔要执行的业务函数
@@ -1066,5 +1383,484 @@ const findObjAttrValueById = function findObjAttrValueByIdFn(id, arr, resultKey
1066
1383
  }
1067
1384
  };
1068
1385
 
1069
- export { IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };
1386
+ /**
1387
+ * 从服务端返回的已选 id 数组里,提取出
1388
+ * 1. 叶子节点
1389
+ * 2. 所有子节点都被选中的父节点
1390
+ * 其余父节点一律丢弃(由前端 Tree 自动算半选)
1391
+ *
1392
+ * @param {Array} treeData 完整树
1393
+ * @param {Array} selectedKeys 后端给的选中 id 数组
1394
+ * @param {String} idKey 节点唯一字段
1395
+ * @param {String} childrenKey 子节点字段
1396
+ * @returns {{checked: string[], halfChecked: string[]}}
1397
+ */
1398
+ function extractFullyCheckedKeys(treeData, selectedKeys, idKey = "id", childrenKey = "children") {
1399
+ const selectedSet = new Set(selectedKeys);
1400
+ const checked = new Set();
1401
+ const halfChecked = new Set();
1402
+
1403
+ /* 返回值含义
1404
+ 0 - 未选中
1405
+ 1 - 半选
1406
+ 2 - 全选
1407
+ */
1408
+ function dfs(node) {
1409
+ const nodeId = node[idKey];
1410
+ const children = node[childrenKey] || [];
1411
+
1412
+ // 叶子
1413
+ if (!children.length) {
1414
+ if (selectedSet.has(nodeId)) {
1415
+ checked.add(nodeId);
1416
+ return 2;
1417
+ }
1418
+ return 0;
1419
+ }
1420
+
1421
+ // 非叶子
1422
+ let allChecked = true;
1423
+ let someChecked = false;
1424
+
1425
+ children.forEach((child) => {
1426
+ const childState = dfs(child);
1427
+ if (childState !== 2) allChecked = false;
1428
+ if (childState >= 1) someChecked = true;
1429
+ });
1430
+
1431
+ // 当前节点本身在 selectedKeys 里,但子节点未全选 → 只能算半选
1432
+ if (selectedSet.has(nodeId)) {
1433
+ if (allChecked) {
1434
+ checked.add(nodeId);
1435
+ return 2;
1436
+ }
1437
+ halfChecked.add(nodeId);
1438
+ return 1;
1439
+ }
1440
+
1441
+ // 当前节点不在 selectedKeys 里,看子节点
1442
+ if (allChecked) {
1443
+ checked.add(nodeId);
1444
+ return 2;
1445
+ }
1446
+ if (someChecked) {
1447
+ halfChecked.add(nodeId);
1448
+ return 1;
1449
+ }
1450
+ return 0;
1451
+ }
1452
+
1453
+ treeData.forEach(dfs);
1454
+ return {
1455
+ checked: [...checked],
1456
+ halfChecked: [...halfChecked]
1457
+ };
1458
+ }
1459
+
1460
+ /**
1461
+ * @class WebSocketManager - 一个功能强大、高度可定制的 WebSocket 助手类
1462
+ *
1463
+ * @features
1464
+ * - 智能断线重连 (指数退避算法)
1465
+ * - 网络状态监听
1466
+ * - 高度可定制的心跳保活机制 (通过注入函数实现)
1467
+ * - 页面可见性 API 集成
1468
+ * - 消息发送队列
1469
+ * - 事件驱动的消息分发
1470
+ * - 清晰的生命周期管理
1471
+ * - 优雅的资源销毁
1472
+ * - 可配置的数据序列化/反序列化
1473
+ */
1474
+ class WebSocketManager {
1475
+ /**
1476
+ * @param {string} url - WebSocket 服务器的地址
1477
+ * @param {object} [options={}] - 配置选项
1478
+ * @param {number} [options.heartbeatInterval=30000] - 心跳间隔 (毫秒)
1479
+ * @param {number} [options.heartbeatTimeout=10000] - 心跳超时时间 (毫秒)
1480
+ * @param {number} [options.reconnectBaseInterval=1000] - 重连基础间隔 (毫秒)
1481
+ * @param {number} [options.maxReconnectInterval=30000] - 最大重连间隔 (毫秒)
1482
+ * @param {number} [options.maxReconnectAttempts=Infinity] - 最大重连次数
1483
+ * @param {boolean} [options.autoConnect=true] - 是否在实例化后自动连接
1484
+ * @param {boolean} [options.serializeData=false] - 发送数据时是否自动序列化为JSON字符串
1485
+ * @param {boolean} [options.deserializeData=false] - 接收数据时是否自动反序列化为JSON对象
1486
+ * @param {function|null} [options.getPingMessage=null] - 返回要发送的 ping 消息内容的函数。如果为 null,则不发送心跳。
1487
+ * @param {function|null} [options.isPongMessage=null] - 判断接收到的消息是否为 pong 的函数。接收 MessageEvent 对象作为参数,返回布尔值。
1488
+ * @param {object} [options.protocols] - WebSocket 协议
1489
+ */
1490
+ constructor(url, options = {}) {
1491
+ this.url = url;
1492
+
1493
+ // 默认的心跳实现,用于向后兼容
1494
+ const defaultGetPingMessage = () => JSON.stringify({ type: "ping" });
1495
+ const defaultIsPongMessage = (event) => {
1496
+ try {
1497
+ const message = JSON.parse(event.data);
1498
+ return message.type === "pong";
1499
+ } catch (e) {
1500
+ return false;
1501
+ }
1502
+ };
1503
+
1504
+ this.options = {
1505
+ heartbeatInterval: 30000,
1506
+ heartbeatTimeout: 10000,
1507
+ reconnectBaseInterval: 1000,
1508
+ maxReconnectInterval: 30000,
1509
+ maxReconnectAttempts: Infinity,
1510
+ autoConnect: true,
1511
+ serializeData: false,
1512
+ deserializeData: false,
1513
+ getPingMessage: defaultGetPingMessage, // 默认提供 ping 消息生成器
1514
+ isPongMessage: defaultIsPongMessage, // 默认提供 pong 消息判断器
1515
+ ...options
1516
+ };
1517
+
1518
+ // WebSocket 实例
1519
+ this.ws = null;
1520
+
1521
+ // 状态管理
1522
+ this.readyState = WebSocket.CLOSED;
1523
+ this.reconnectAttempts = 0;
1524
+ this.forcedClose = false;
1525
+ this.isReconnecting = false;
1526
+
1527
+ // 定时器
1528
+ this.heartbeatTimer = null;
1529
+ this.heartbeatTimeoutTimer = null;
1530
+ this.reconnectTimer = null;
1531
+
1532
+ // 消息队列
1533
+ this.messageQueue = [];
1534
+
1535
+ // 事件监听器
1536
+ this.listeners = new Map();
1537
+
1538
+ // 绑定方法上下文
1539
+ this._onOpen = this._onOpen.bind(this);
1540
+ this._onMessage = this._onMessage.bind(this);
1541
+ this._onClose = this._onClose.bind(this);
1542
+ this._onError = this._onError.bind(this);
1543
+ this._handleVisibilityChange = this._handleVisibilityChange.bind(this);
1544
+ this._handleOnline = this._handleOnline.bind(this);
1545
+ this._handleOffline = this._handleOffline.bind(this);
1546
+
1547
+ this._setupEventListeners();
1548
+
1549
+ if (this.options.autoConnect) {
1550
+ this.connect();
1551
+ }
1552
+ }
1553
+
1554
+ // --- 公共 API ---
1555
+
1556
+ /**
1557
+ * 连接到 WebSocket 服务器
1558
+ */
1559
+ connect() {
1560
+ if (this.ws && (this.ws.readyState === WebSocket.CONNECTING || this.ws.readyState === WebSocket.OPEN)) {
1561
+ return;
1562
+ }
1563
+
1564
+ this.forcedClose = false;
1565
+ this._updateReadyState(WebSocket.CONNECTING);
1566
+ console.log(`[WS] 正在连接到 ${this.url}...`);
1567
+ this._emit("connecting");
1568
+
1569
+ try {
1570
+ this.ws = new WebSocket(this.url, this.options.protocols);
1571
+ this.ws.onopen = this._onOpen;
1572
+ this.ws.onmessage = this._onMessage;
1573
+ this.ws.onclose = this._onClose;
1574
+ this.ws.onerror = this._onError;
1575
+ } catch (error) {
1576
+ console.error("[WS] 连接失败:", error);
1577
+ this._onError(error);
1578
+ }
1579
+ }
1580
+
1581
+ /**
1582
+ * 发送数据
1583
+ * @param {string|object|ArrayBuffer|Blob} data - 要发送的数据
1584
+ */
1585
+ send(data) {
1586
+ if (this.readyState === WebSocket.OPEN) {
1587
+ let message;
1588
+ // 根据配置决定是否序列化数据
1589
+ if (this.options.serializeData) {
1590
+ message = JSON.stringify(data);
1591
+ } else {
1592
+ message = data;
1593
+ }
1594
+ this.ws.send(message);
1595
+ console.log("[WS] 消息已发送:", message);
1596
+ } else {
1597
+ console.warn("[WS] 连接未打开,消息已加入队列:", data);
1598
+ this.messageQueue.push(data);
1599
+ }
1600
+ }
1601
+
1602
+ /**
1603
+ * 主动关闭连接
1604
+ * @param {number} [code=1000] - 关闭代码
1605
+ * @param {string} [reason=''] - 关闭原因
1606
+ */
1607
+ close(code = 1000, reason = "Normal closure") {
1608
+ this.forcedClose = true;
1609
+ this._stopHeartbeat();
1610
+ this._clearReconnectTimer();
1611
+ if (this.ws && this.ws.readyState === WebSocket.OPEN) {
1612
+ this.ws.close(code, reason);
1613
+ } else {
1614
+ this._updateReadyState(WebSocket.CLOSED);
1615
+ this._emit("close", { code, reason, wasClean: true });
1616
+ }
1617
+ }
1618
+
1619
+ /**
1620
+ * 彻底销毁实例,清理所有资源
1621
+ */
1622
+ destroy() {
1623
+ console.log("[WS] 正在销毁实例...");
1624
+ this.close(1000, "Instance destroyed");
1625
+ this._removeEventListeners();
1626
+ this.messageQueue = [];
1627
+ this.listeners.clear();
1628
+ this.ws = null;
1629
+ }
1630
+
1631
+ /**
1632
+ * 添加事件监听器
1633
+ * @param {string} eventName - 事件名 (e.g., 'open', 'message', 'close', 'error', 'reconnect')
1634
+ * @param {function} callback - 回调函数
1635
+ */
1636
+ on(eventName, callback) {
1637
+ if (!this.listeners.has(eventName)) {
1638
+ this.listeners.set(eventName, []);
1639
+ }
1640
+ this.listeners.get(eventName).push(callback);
1641
+ }
1642
+
1643
+ /**
1644
+ * 移除事件监听器
1645
+ * @param {string} eventName - 事件名
1646
+ * @param {function} callback - 回调函数
1647
+ */
1648
+ off(eventName, callback) {
1649
+ if (this.listeners.has(eventName)) {
1650
+ const callbacks = this.listeners.get(eventName);
1651
+ const index = callbacks.indexOf(callback);
1652
+ if (index > -1) {
1653
+ callbacks.splice(index, 1);
1654
+ }
1655
+ }
1656
+ }
1657
+
1658
+ // --- 内部方法 ---
1659
+
1660
+ _onOpen(event) {
1661
+ console.log("[WS] 连接已建立");
1662
+ this._updateReadyState(WebSocket.OPEN);
1663
+ this.reconnectAttempts = 0;
1664
+ this.isReconnecting = false;
1665
+
1666
+ // 如果配置了 getPingMessage,则启动心跳
1667
+ if (this.options.getPingMessage) {
1668
+ this._startHeartbeat();
1669
+ }
1670
+
1671
+ this._flushMessageQueue();
1672
+ this._emit("open", event);
1673
+ }
1674
+
1675
+ /**
1676
+ * 优化后的消息处理方法,使用注入的函数来判断心跳
1677
+ * @param {MessageEvent} event
1678
+ */
1679
+ _onMessage(event) {
1680
+ // --- 步骤 1: 使用注入的函数优先处理内部心跳机制 ---
1681
+ if (this.options.isPongMessage && this.options.isPongMessage(event)) {
1682
+ this._handlePong();
1683
+ return; // 是心跳消息,处理完毕,直接返回
1684
+ }
1685
+
1686
+ // --- 步骤 2: 根据用户配置处理业务消息 ---
1687
+ if (this.options.deserializeData) {
1688
+ try {
1689
+ const parsedMessage = JSON.parse(event.data);
1690
+ this._emit("message", parsedMessage);
1691
+ } catch (e) {
1692
+ this._emit("message", event.data);
1693
+ }
1694
+ } else {
1695
+ this._emit("message", event.data);
1696
+ }
1697
+ }
1698
+
1699
+ _onClose(event) {
1700
+ console.log("[WS] 连接已关闭", event);
1701
+ this._updateReadyState(WebSocket.CLOSED);
1702
+ this._stopHeartbeat();
1703
+ this._emit("close", event);
1704
+
1705
+ if (!this.forcedClose) {
1706
+ this._scheduleReconnect();
1707
+ }
1708
+ }
1709
+
1710
+ _onError(event) {
1711
+ console.error("[WS] 连接发生错误:", event);
1712
+ this._emit("error", event);
1713
+ }
1714
+
1715
+ // --- 心跳机制 (重构) ---
1716
+ _startHeartbeat() {
1717
+ // 如果没有配置 getPingMessage,则无法启动心跳
1718
+ if (!this.options.getPingMessage) {
1719
+ return;
1720
+ }
1721
+
1722
+ this._stopHeartbeat();
1723
+ this.heartbeatTimer = setInterval(() => {
1724
+ if (this.ws && this.ws.readyState === WebSocket.OPEN) {
1725
+ try {
1726
+ // 调用注入的函数获取消息内容并发送
1727
+ const pingMessage = this.options.getPingMessage();
1728
+ this.ws.send(pingMessage);
1729
+ console.log("[WS] 发送 Ping:", pingMessage);
1730
+ this._setHeartbeatTimeout();
1731
+ } catch (error) {
1732
+ console.error("[WS] 发送 Ping 消息失败:", error);
1733
+ }
1734
+ }
1735
+ }, this.options.heartbeatInterval);
1736
+ }
1737
+
1738
+ _stopHeartbeat() {
1739
+ if (this.heartbeatTimer) {
1740
+ clearInterval(this.heartbeatTimer);
1741
+ this.heartbeatTimer = null;
1742
+ }
1743
+ this._clearHeartbeatTimeout();
1744
+ }
1745
+
1746
+ _setHeartbeatTimeout() {
1747
+ this._clearHeartbeatTimeout();
1748
+ this.heartbeatTimeoutTimer = setTimeout(() => {
1749
+ console.error("[WS] 心跳超时,主动断开连接");
1750
+ this.ws.close(1006, "Heartbeat timeout");
1751
+ }, this.options.heartbeatTimeout);
1752
+ }
1753
+
1754
+ _clearHeartbeatTimeout() {
1755
+ if (this.heartbeatTimeoutTimer) {
1756
+ clearTimeout(this.heartbeatTimeoutTimer);
1757
+ this.heartbeatTimeoutTimer = null;
1758
+ }
1759
+ }
1760
+
1761
+ _handlePong() {
1762
+ console.log("[WS] 收到 Pong");
1763
+ this._clearHeartbeatTimeout();
1764
+ }
1765
+
1766
+ // --- 重连机制 ---
1767
+ _scheduleReconnect() {
1768
+ if (this.forcedClose || this.isReconnecting || this.reconnectAttempts >= this.options.maxReconnectAttempts) {
1769
+ if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
1770
+ console.error("[WS] 已达到最大重连次数,停止重连");
1771
+ this._emit("reconnect-failed");
1772
+ }
1773
+ return;
1774
+ }
1775
+
1776
+ this.isReconnecting = true;
1777
+ const interval = Math.min(this.options.reconnectBaseInterval * Math.pow(2, this.reconnectAttempts), this.options.maxReconnectInterval);
1778
+
1779
+ console.log(`[WS] ${interval / 1000}秒后将尝试第 ${this.reconnectAttempts + 1} 次重连...`);
1780
+ this._emit("reconnect-attempt", { attempt: this.reconnectAttempts + 1, interval });
1781
+
1782
+ this.reconnectTimer = setTimeout(() => {
1783
+ this.reconnectAttempts++;
1784
+ this.connect();
1785
+ }, interval);
1786
+ }
1787
+
1788
+ _clearReconnectTimer() {
1789
+ if (this.reconnectTimer) {
1790
+ clearTimeout(this.reconnectTimer);
1791
+ this.reconnectTimer = null;
1792
+ }
1793
+ }
1794
+
1795
+ // --- 消息队列 ---
1796
+ _flushMessageQueue() {
1797
+ if (this.messageQueue.length === 0) return;
1798
+ console.log(`[WS] 发送队列中的 ${this.messageQueue.length} 条消息`);
1799
+ const queue = [...this.messageQueue];
1800
+ this.messageQueue = [];
1801
+ queue.forEach((data) => this.send(data));
1802
+ }
1803
+
1804
+ // --- 事件系统 ---
1805
+ _emit(eventName, ...args) {
1806
+ if (this.listeners.has(eventName)) {
1807
+ this.listeners.get(eventName).forEach((callback) => callback(...args));
1808
+ }
1809
+ }
1810
+
1811
+ // --- 状态与监听器管理 ---
1812
+ _updateReadyState(newState) {
1813
+ this.readyState = newState;
1814
+ this._emit("ready-state-change", newState);
1815
+ }
1816
+
1817
+ _setupEventListeners() {
1818
+ document.addEventListener("visibilitychange", this._handleVisibilityChange);
1819
+ window.addEventListener("online", this._handleOnline);
1820
+ window.addEventListener("offline", this._handleOffline);
1821
+ }
1822
+
1823
+ _removeEventListeners() {
1824
+ document.removeEventListener("visibilitychange", this._handleVisibilityChange);
1825
+ window.removeEventListener("online", this._handleOnline);
1826
+ window.removeEventListener("offline", this._handleOffline);
1827
+ }
1828
+
1829
+ _handleVisibilityChange() {
1830
+ // 如果未启用心跳,不需要处理页面可见性变化
1831
+ if (!this.options.enableHeartbeat) {
1832
+ return;
1833
+ }
1834
+
1835
+ if (document.hidden) {
1836
+ console.log("[WS] 页面隐藏,停止心跳");
1837
+ this._stopHeartbeat();
1838
+ } else {
1839
+ console.log("[WS] 页面可见,检查连接状态");
1840
+ if (this.ws && this.ws.readyState === WebSocket.OPEN) {
1841
+ this._startHeartbeat();
1842
+ } else if (!this.forcedClose && !this.isReconnecting) {
1843
+ this.connect();
1844
+ }
1845
+ }
1846
+ }
1847
+
1848
+ _handleOnline() {
1849
+ console.log("[WS] 网络已恢复,尝试重连");
1850
+ if (!this.forcedClose && this.readyState !== WebSocket.OPEN) {
1851
+ this._clearReconnectTimer(); // 清除当前的重连计划
1852
+ this.connect(); // 立即尝试连接
1853
+ }
1854
+ }
1855
+
1856
+ _handleOffline() {
1857
+ console.log("[WS] 网络已断开");
1858
+ this._clearReconnectTimer(); // 停止重连尝试
1859
+ // ws.onclose 会被触发,从而启动重连逻辑,但我们已经停止了
1860
+ // 所以这里可以手动触发一次 close 事件来通知应用层
1861
+ if (this.ws) this.ws.onclose({ code: 1006, reason: "Network offline" });
1862
+ }
1863
+ }
1864
+
1865
+ 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 };
1070
1866
  //# sourceMappingURL=a2bei4.utils.esm.js.map