@meng-xi/vite-plugin 0.1.0 → 0.1.2

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 (110) hide show
  1. package/README-en.md +264 -533
  2. package/README.md +253 -522
  3. package/dist/common/format/index.cjs +1 -0
  4. package/dist/common/format/index.d.cts +156 -0
  5. package/dist/common/format/index.d.mts +156 -0
  6. package/dist/common/format/index.d.ts +156 -0
  7. package/dist/common/format/index.mjs +1 -0
  8. package/dist/common/fs/index.cjs +1 -0
  9. package/dist/common/fs/index.d.cts +150 -0
  10. package/dist/common/fs/index.d.mts +150 -0
  11. package/dist/common/fs/index.d.ts +150 -0
  12. package/dist/common/fs/index.mjs +1 -0
  13. package/dist/common/html/index.cjs +2 -0
  14. package/dist/common/html/index.d.cts +109 -0
  15. package/dist/common/html/index.d.mts +109 -0
  16. package/dist/common/html/index.d.ts +109 -0
  17. package/dist/common/html/index.mjs +2 -0
  18. package/dist/common/index.cjs +1 -1
  19. package/dist/common/index.d.cts +7 -417
  20. package/dist/common/index.d.mts +7 -417
  21. package/dist/common/index.d.ts +7 -417
  22. package/dist/common/index.mjs +1 -1
  23. package/dist/common/object/index.cjs +1 -0
  24. package/dist/common/object/index.d.cts +30 -0
  25. package/dist/common/object/index.d.mts +30 -0
  26. package/dist/common/object/index.d.ts +30 -0
  27. package/dist/common/object/index.mjs +1 -0
  28. package/dist/common/script/index.cjs +1 -0
  29. package/dist/common/script/index.d.cts +54 -0
  30. package/dist/common/script/index.d.mts +54 -0
  31. package/dist/common/script/index.d.ts +54 -0
  32. package/dist/common/script/index.mjs +1 -0
  33. package/dist/common/validation/index.cjs +1 -0
  34. package/dist/common/validation/index.d.cts +93 -0
  35. package/dist/common/validation/index.d.mts +93 -0
  36. package/dist/common/validation/index.d.ts +93 -0
  37. package/dist/common/validation/index.mjs +1 -0
  38. package/dist/factory/index.cjs +1 -1
  39. package/dist/factory/index.d.cts +1 -1
  40. package/dist/factory/index.d.mts +1 -1
  41. package/dist/factory/index.d.ts +1 -1
  42. package/dist/factory/index.mjs +1 -1
  43. package/dist/index.cjs +1 -1
  44. package/dist/index.d.cts +16 -3
  45. package/dist/index.d.mts +16 -3
  46. package/dist/index.d.ts +16 -3
  47. package/dist/index.mjs +1 -1
  48. package/dist/plugins/buildProgress/index.cjs +2 -0
  49. package/dist/plugins/buildProgress/index.d.cts +187 -0
  50. package/dist/plugins/buildProgress/index.d.mts +187 -0
  51. package/dist/plugins/buildProgress/index.d.ts +187 -0
  52. package/dist/plugins/buildProgress/index.mjs +2 -0
  53. package/dist/plugins/compressAssets/index.cjs +1 -0
  54. package/dist/plugins/compressAssets/index.d.cts +132 -0
  55. package/dist/plugins/compressAssets/index.d.mts +132 -0
  56. package/dist/plugins/compressAssets/index.d.ts +132 -0
  57. package/dist/plugins/compressAssets/index.mjs +1 -0
  58. package/dist/plugins/copyFile/index.cjs +1 -0
  59. package/dist/plugins/copyFile/index.d.cts +78 -0
  60. package/dist/plugins/copyFile/index.d.mts +78 -0
  61. package/dist/plugins/copyFile/index.d.ts +78 -0
  62. package/dist/plugins/copyFile/index.mjs +1 -0
  63. package/dist/plugins/faviconManager/index.cjs +1 -0
  64. package/dist/plugins/faviconManager/index.d.cts +143 -0
  65. package/dist/plugins/faviconManager/index.d.mts +143 -0
  66. package/dist/plugins/faviconManager/index.d.ts +143 -0
  67. package/dist/plugins/faviconManager/index.mjs +1 -0
  68. package/dist/plugins/generateRouter/index.cjs +35 -0
  69. package/dist/plugins/generateRouter/index.d.cts +215 -0
  70. package/dist/plugins/generateRouter/index.d.mts +215 -0
  71. package/dist/plugins/generateRouter/index.d.ts +215 -0
  72. package/dist/plugins/generateRouter/index.mjs +35 -0
  73. package/dist/plugins/generateVersion/index.cjs +1 -0
  74. package/dist/plugins/generateVersion/index.d.cts +184 -0
  75. package/dist/plugins/generateVersion/index.d.mts +184 -0
  76. package/dist/plugins/generateVersion/index.d.ts +184 -0
  77. package/dist/plugins/generateVersion/index.mjs +1 -0
  78. package/dist/plugins/htmlInject/index.cjs +7 -0
  79. package/dist/plugins/htmlInject/index.d.cts +278 -0
  80. package/dist/plugins/htmlInject/index.d.mts +278 -0
  81. package/dist/plugins/htmlInject/index.d.ts +278 -0
  82. package/dist/plugins/htmlInject/index.mjs +7 -0
  83. package/dist/plugins/index.cjs +1 -1
  84. package/dist/plugins/index.d.cts +11 -1714
  85. package/dist/plugins/index.d.mts +11 -1714
  86. package/dist/plugins/index.d.ts +11 -1714
  87. package/dist/plugins/index.mjs +1 -1
  88. package/dist/plugins/loadingManager/index.cjs +487 -0
  89. package/dist/plugins/loadingManager/index.d.cts +769 -0
  90. package/dist/plugins/loadingManager/index.d.mts +769 -0
  91. package/dist/plugins/loadingManager/index.d.ts +769 -0
  92. package/dist/plugins/loadingManager/index.mjs +487 -0
  93. package/dist/plugins/versionUpdateChecker/index.cjs +185 -0
  94. package/dist/plugins/versionUpdateChecker/index.d.cts +200 -0
  95. package/dist/plugins/versionUpdateChecker/index.d.mts +200 -0
  96. package/dist/plugins/versionUpdateChecker/index.d.ts +200 -0
  97. package/dist/plugins/versionUpdateChecker/index.mjs +185 -0
  98. package/dist/shared/vite-plugin.Bcg6RW2N.cjs +3 -0
  99. package/dist/shared/{vite-plugin.CiHfwMiN.d.ts → vite-plugin.DRRlWY8P.d.cts} +50 -0
  100. package/dist/shared/{vite-plugin.CiHfwMiN.d.cts → vite-plugin.DRRlWY8P.d.mts} +50 -0
  101. package/dist/shared/{vite-plugin.CiHfwMiN.d.mts → vite-plugin.DRRlWY8P.d.ts} +50 -0
  102. package/dist/shared/{vite-plugin.B88RyRN8.mjs → vite-plugin.DcExl6jd.mjs} +2 -2
  103. package/package.json +80 -3
  104. package/dist/shared/vite-plugin.CawoITTT.cjs +0 -1
  105. package/dist/shared/vite-plugin.D6Law9Ke.mjs +0 -706
  106. package/dist/shared/vite-plugin.D8L9KzuW.cjs +0 -706
  107. package/dist/shared/vite-plugin.DFjf9wFM.mjs +0 -2
  108. package/dist/shared/vite-plugin.DSb6XzBn.mjs +0 -1
  109. package/dist/shared/vite-plugin.IGZeStMa.cjs +0 -3
  110. package/dist/shared/vite-plugin.Tab4qcIM.cjs +0 -2
@@ -0,0 +1,769 @@
1
+ import { BasePluginOptions, PluginFactory } from '../../factory/index.mjs';
2
+ import 'vite';
3
+ import '../../shared/vite-plugin.CLr0ttuO.mjs';
4
+ import '../../shared/vite-plugin.DRRlWY8P.mjs';
5
+
6
+ /**
7
+ * Loading 组件的显示位置
8
+ *
9
+ * @remarks 控制加载指示器在视口中的垂直对齐方式
10
+ *
11
+ * @defaultValue `'center'`
12
+ *
13
+ * @example
14
+ * ```typescript
15
+ * loadingManager({ position: 'top' })
16
+ * ```
17
+ */
18
+ type LoadingPosition = 'center' | 'top' | 'bottom';
19
+ /**
20
+ * Loading 自动绑定请求拦截的模式
21
+ *
22
+ * @remarks 决定插件自动拦截哪些类型的网络请求来管理 loading 状态
23
+ *
24
+ * @defaultValue `'none'`
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * // 自动拦截所有 fetch 请求
29
+ * loadingManager({ autoBind: 'fetch' })
30
+ * ```
31
+ */
32
+ type AutoBindMode = 'fetch' | 'xhr' | 'all' | 'none';
33
+ /**
34
+ * Loading 旋转图标的内置类型
35
+ *
36
+ * @remarks 提供四种内置加载动画,无需自定义 CSS 即可使用
37
+ *
38
+ * @defaultValue `'spinner'`
39
+ *
40
+ * @example
41
+ * ```typescript
42
+ * loadingManager({ spinnerType: 'dots' })
43
+ * ```
44
+ */
45
+ type SpinnerType = 'spinner' | 'dots' | 'pulse' | 'bar';
46
+ /**
47
+ * 当 `defaultVisible` 为 `true` 时,loading 的自动隐藏时机
48
+ *
49
+ * @remarks 仅在 {@link LoadingManagerOptions.defaultVisible} 为 `true` 时生效,
50
+ * 决定 loading 在页面加载过程中的自动隐藏策略
51
+ *
52
+ * @defaultValue `'DOMContentLoaded'`
53
+ *
54
+ * @example
55
+ * ```typescript
56
+ * // Vue/React SPA:手动控制隐藏时机
57
+ * loadingManager({ defaultVisible: true, autoHideOn: 'manual' })
58
+ * // 在应用入口:window.__LOADING_MANAGER__.hide()
59
+ * ```
60
+ */
61
+ type AutoHideOn = 'DOMContentLoaded' | 'load' | 'manual';
62
+ /**
63
+ * Loading 过渡动画配置
64
+ *
65
+ * @remarks 控制 loading 显示/隐藏时的 CSS 过渡效果
66
+ */
67
+ interface TransitionConfig {
68
+ /**
69
+ * 是否启用过渡动画
70
+ *
71
+ * @defaultValue `true`
72
+ */
73
+ enabled?: boolean;
74
+ /**
75
+ * 过渡动画持续时间(毫秒)
76
+ *
77
+ * @defaultValue `200`
78
+ *
79
+ * @throws 配置验证时若为负数将抛出错误
80
+ */
81
+ duration?: number;
82
+ /**
83
+ * CSS 过渡缓动函数
84
+ *
85
+ * @defaultValue `'ease-out'`
86
+ *
87
+ * @example
88
+ * ```typescript
89
+ * { easing: 'cubic-bezier(0.4, 0, 0.2, 1)' }
90
+ * ```
91
+ */
92
+ easing?: string;
93
+ }
94
+ /**
95
+ * Loading 自定义样式配置
96
+ *
97
+ * @remarks 控制 loading 遮罩层、图标和文本的视觉表现
98
+ */
99
+ interface LoadingStyle {
100
+ /**
101
+ * 遮罩层背景色(CSS 颜色值)
102
+ *
103
+ * @defaultValue `'rgba(255, 255, 255, 0.7)'`
104
+ */
105
+ overlayColor?: string;
106
+ /**
107
+ * Loading 图标颜色(CSS 颜色值)
108
+ *
109
+ * @defaultValue `'#4361ee'`
110
+ */
111
+ spinnerColor?: string;
112
+ /**
113
+ * Loading 图标大小(CSS 长度值)
114
+ *
115
+ * @defaultValue `'40px'`
116
+ */
117
+ spinnerSize?: string;
118
+ /**
119
+ * 文本颜色(CSS 颜色值)
120
+ *
121
+ * @defaultValue `'#333'`
122
+ */
123
+ textColor?: string;
124
+ /**
125
+ * 文本大小(CSS 长度值)
126
+ *
127
+ * @defaultValue `'14px'`
128
+ */
129
+ textSize?: string;
130
+ /**
131
+ * 自定义 CSS 类名,附加到 overlay 元素上
132
+ *
133
+ * @remarks 可用于覆盖默认样式或添加额外样式
134
+ */
135
+ customClass?: string;
136
+ /**
137
+ * 自定义内联样式字符串,附加到 overlay 元素上
138
+ *
139
+ * @remarks 将作为 `style` 属性值直接注入
140
+ */
141
+ customStyle?: string;
142
+ /**
143
+ * 遮罩层 z-index 值
144
+ *
145
+ * @defaultValue `9999`
146
+ *
147
+ * @throws 配置验证时若为负数将抛出错误
148
+ */
149
+ zIndex?: number;
150
+ /**
151
+ * 是否启用遮罩层的指针事件
152
+ *
153
+ * @remarks
154
+ * 对应 CSS `pointer-events` 属性,控制遮罩层是否拦截用户的点击、滚动等交互操作:
155
+ * - `true`(默认):启用指针事件(`pointer-events: auto`),遮罩层阻止所有交互
156
+ * - `false`:禁用指针事件(`pointer-events: none`),遮罩层允许交互穿透
157
+ *
158
+ * @defaultValue `true`
159
+ *
160
+ * @example
161
+ * ```typescript
162
+ * // 阻止交互(默认行为)
163
+ * loadingManager({ style: { pointerEvents: true } })
164
+ *
165
+ * // 允许交互穿透(如仅展示加载状态,不阻止操作)
166
+ * loadingManager({ style: { pointerEvents: false } })
167
+ * ```
168
+ */
169
+ pointerEvents?: boolean;
170
+ /**
171
+ * 是否启用 backdrop-filter 模糊效果
172
+ *
173
+ * @remarks 启用后遮罩层下方的页面内容将被高斯模糊处理,
174
+ * 需要浏览器支持 `backdrop-filter` CSS 属性
175
+ *
176
+ * @defaultValue `false`
177
+ */
178
+ backdropBlur?: boolean;
179
+ /**
180
+ * backdrop-filter 模糊程度(单位:px)
181
+ *
182
+ * @remarks 仅在 {@link backdropBlur} 为 `true` 时生效
183
+ *
184
+ * @defaultValue `4`
185
+ *
186
+ * @throws 配置验证时若为负数将抛出错误
187
+ */
188
+ backdropBlurAmount?: number;
189
+ }
190
+ /**
191
+ * Loading 最小显示时间配置
192
+ *
193
+ * @remarks 确保 loading 至少显示指定时长,避免快速闪烁
194
+ */
195
+ interface MinDisplayTime {
196
+ /**
197
+ * 是否启用最小显示时间
198
+ *
199
+ * @defaultValue `true`
200
+ */
201
+ enabled?: boolean;
202
+ /**
203
+ * 最小显示时间(毫秒)
204
+ *
205
+ * @remarks 即使请求在更短时间内完成,loading 也会至少显示此时长
206
+ *
207
+ * @defaultValue `300`
208
+ *
209
+ * @throws 配置验证时若为负数将抛出错误
210
+ */
211
+ duration?: number;
212
+ }
213
+ /**
214
+ * Loading 延迟显示配置
215
+ *
216
+ * @remarks 当请求在短时间内完成时,延迟显示可避免 loading 闪烁
217
+ */
218
+ interface DelayShow {
219
+ /**
220
+ * 是否启用延迟显示
221
+ *
222
+ * @defaultValue `true`
223
+ */
224
+ enabled?: boolean;
225
+ /**
226
+ * 延迟时间(毫秒)
227
+ *
228
+ * @remarks 请求开始后等待此时长再显示 loading;
229
+ * 若请求在此时间内完成,则不会显示 loading
230
+ *
231
+ * @defaultValue `200`
232
+ *
233
+ * @throws 配置验证时若为负数将抛出错误
234
+ */
235
+ duration?: number;
236
+ }
237
+ /**
238
+ * Loading 防抖隐藏配置
239
+ *
240
+ * @remarks 当频繁触发 hide 操作时,延迟执行以避免 loading 闪烁
241
+ */
242
+ interface DebounceHide {
243
+ /**
244
+ * 是否启用防抖隐藏
245
+ *
246
+ * @defaultValue `false`
247
+ */
248
+ enabled?: boolean;
249
+ /**
250
+ * 防抖等待时间(毫秒)
251
+ *
252
+ * @remarks 在最后一次 hide 调用后等待此时长再执行隐藏
253
+ *
254
+ * @defaultValue `100`
255
+ *
256
+ * @throws 配置验证时若为负数将抛出错误
257
+ */
258
+ duration?: number;
259
+ }
260
+ /**
261
+ * Loading 请求过滤配置
262
+ *
263
+ * @remarks 用于精细控制哪些网络请求会触发 loading 状态变化
264
+ */
265
+ interface RequestFilter {
266
+ /**
267
+ * 需要排除的 URL 正则表达式数组
268
+ *
269
+ * @remarks 匹配的 URL 不会触发 loading
270
+ *
271
+ * @example
272
+ * ```typescript
273
+ * { excludeUrls: [/\/api\/health/, /\/static\//] }
274
+ * ```
275
+ */
276
+ excludeUrls?: RegExp[];
277
+ /**
278
+ * 需要包含的 URL 正则表达式数组
279
+ *
280
+ * @remarks 仅匹配的 URL 才会触发 loading。
281
+ * 与 {@link excludeUrls} 互斥,{@link includeUrls} 优先级更高
282
+ *
283
+ * @example
284
+ * ```typescript
285
+ * { includeUrls: [/\/api\/data/] }
286
+ * ```
287
+ */
288
+ includeUrls?: RegExp[];
289
+ /**
290
+ * 需要排除的 HTTP 方法数组(不区分大小写)
291
+ *
292
+ * @example
293
+ * ```typescript
294
+ * { excludeMethods: ['OPTIONS', 'HEAD'] }
295
+ * ```
296
+ */
297
+ excludeMethods?: string[];
298
+ /**
299
+ * 需要排除的 URL 字符串前缀数组
300
+ *
301
+ * @remarks 使用前缀匹配(`indexOf === 0`),比正则更高效
302
+ *
303
+ * @example
304
+ * ```typescript
305
+ * { excludeUrlPrefixes: ['http://localhost', 'data:'] }
306
+ * ```
307
+ */
308
+ excludeUrlPrefixes?: string[];
309
+ }
310
+ /**
311
+ * Loading 生命周期回调
312
+ *
313
+ * @remarks 回调以 **函数体字符串** 形式提供,因为插件在构建时注入代码到浏览器端,
314
+ * 无法直接传递函数引用。字符串应为有效的 JavaScript 函数体代码。
315
+ */
316
+ interface LoadingCallbacks {
317
+ /**
318
+ * Loading 显示前的回调
319
+ *
320
+ * @remarks 函数体内 `return false` 可阻止显示
321
+ *
322
+ * @example
323
+ * ```typescript
324
+ * { onBeforeShow: 'if (someCondition) return false;' }
325
+ * ```
326
+ */
327
+ onBeforeShow?: string;
328
+ /**
329
+ * Loading 显示后的回调
330
+ *
331
+ * @example
332
+ * ```typescript
333
+ * { onShow: 'console.log("loading shown")' }
334
+ * ```
335
+ */
336
+ onShow?: string;
337
+ /**
338
+ * Loading 隐藏前的回调
339
+ *
340
+ * @remarks 函数体内 `return false` 可阻止隐藏
341
+ *
342
+ * @example
343
+ * ```typescript
344
+ * { onBeforeHide: 'if (shouldKeepVisible) return false;' }
345
+ * ```
346
+ */
347
+ onBeforeHide?: string;
348
+ /**
349
+ * Loading 隐藏后的回调
350
+ *
351
+ * @example
352
+ * ```typescript
353
+ * { onHide: 'console.log("loading hidden")' }
354
+ * ```
355
+ */
356
+ onHide?: string;
357
+ /**
358
+ * Loading 销毁时的回调
359
+ *
360
+ * @remarks 在 DOM 清理和拦截器恢复之后执行
361
+ */
362
+ onDestroy?: string;
363
+ }
364
+ /**
365
+ * Loading 管理器实例接口
366
+ *
367
+ * @remarks 注入到浏览器全局变量(默认 `window.__LOADING_MANAGER__`),
368
+ * 提供运行时 loading 状态控制方法
369
+ */
370
+ interface LoadingManager {
371
+ /**
372
+ * 显示 loading
373
+ *
374
+ * @param text - 可选,显示的文本内容;不传则保留默认文本
375
+ *
376
+ * @example
377
+ * ```typescript
378
+ * window.__LOADING_MANAGER__.show()
379
+ * window.__LOADING_MANAGER__.show('正在保存...')
380
+ * ```
381
+ */
382
+ show(text?: string): void;
383
+ /**
384
+ * 隐藏 loading
385
+ *
386
+ * @remarks 受 {@link MinDisplayTime} 和 {@link DebounceHide} 配置约束;
387
+ * 若需忽略这些约束,请使用 {@link forceHide}
388
+ */
389
+ hide(): void;
390
+ /**
391
+ * 强制隐藏 loading,忽略最小显示时间和防抖隐藏
392
+ *
393
+ * @remarks 适用于需要立即隐藏 loading 的紧急场景
394
+ */
395
+ forceHide(): void;
396
+ /**
397
+ * 切换 loading 的显示/隐藏状态
398
+ *
399
+ * @remarks 如果当前显示则调用 {@link hide},如果当前隐藏则调用 {@link show}
400
+ *
401
+ * @param text - 可选,切换为显示时的文本内容;不传则保留默认文本
402
+ *
403
+ * @example
404
+ * ```typescript
405
+ * window.__LOADING_MANAGER__.toggle()
406
+ * window.__LOADING_MANAGER__.toggle('正在加载...')
407
+ * ```
408
+ */
409
+ toggle(text?: string): void;
410
+ /**
411
+ * 启用遮罩层的指针事件,拦截所有点击和滚动操作
412
+ *
413
+ * @remarks 设置遮罩层的 `pointer-events: auto`,恢复默认的交互拦截行为。
414
+ * 适用于运行时动态启用交互阻止,例如在特定操作期间临时锁定页面
415
+ *
416
+ * @example
417
+ * ```typescript
418
+ * window.__LOADING_MANAGER__.enablePointerEvents()
419
+ * ```
420
+ */
421
+ enablePointerEvents(): void;
422
+ /**
423
+ * 禁用遮罩层的指针事件,允许交互穿透
424
+ *
425
+ * @remarks 设置遮罩层的 `pointer-events: none`,使鼠标事件穿透到下层元素。
426
+ * 适用于运行时动态禁用交互阻止,例如需要用户在 loading 期间仍能操作页面
427
+ *
428
+ * @example
429
+ * ```typescript
430
+ * window.__LOADING_MANAGER__.disablePointerEvents()
431
+ * ```
432
+ */
433
+ disablePointerEvents(): void;
434
+ /**
435
+ * 切换遮罩层的指针事件状态
436
+ *
437
+ * @remarks 如果当前启用指针事件则调用 {@link disablePointerEvents},如果当前禁用则调用 {@link enablePointerEvents}
438
+ *
439
+ * @example
440
+ * ```typescript
441
+ * window.__LOADING_MANAGER__.togglePointerEvents()
442
+ * ```
443
+ */
444
+ togglePointerEvents(): void;
445
+ /**
446
+ * 更新 loading 文本内容
447
+ *
448
+ * @param text - 新的文本内容
449
+ *
450
+ * @example
451
+ * ```typescript
452
+ * window.__LOADING_MANAGER__.updateText('正在处理数据...')
453
+ * ```
454
+ */
455
+ updateText(text: string): void;
456
+ /**
457
+ * 获取当前 loading 是否正在显示
458
+ *
459
+ * @returns `true` 表示 loading 正在显示且未被销毁
460
+ */
461
+ isVisible(): boolean;
462
+ /**
463
+ * 获取当前遮罩层是否启用了指针事件
464
+ *
465
+ * @returns `true` 表示指针事件已启用(遮罩层拦截交互),`false` 表示已禁用(允许穿透)
466
+ */
467
+ isPointerEventsEnabled(): boolean;
468
+ /**
469
+ * 获取当前挂起的请求数量
470
+ *
471
+ * @returns 当前正在进行的、被拦截的请求数量
472
+ */
473
+ getPendingCount(): number;
474
+ /**
475
+ * 销毁 loading 实例
476
+ *
477
+ * @remarks 清理 DOM 元素、事件监听器,并恢复原始的 fetch/XHR 拦截。
478
+ * 销毁后所有其他方法调用将被安全忽略
479
+ */
480
+ destroy(): void;
481
+ }
482
+ /**
483
+ * loadingManager 插件的配置选项
484
+ *
485
+ * @remarks 继承自 {@link BasePluginOptions},包含 loading 的所有可配置项
486
+ */
487
+ interface LoadingManagerOptions extends BasePluginOptions {
488
+ /**
489
+ * Loading 显示位置
490
+ *
491
+ * @defaultValue `'center'`
492
+ */
493
+ position?: LoadingPosition;
494
+ /**
495
+ * 默认显示文本
496
+ *
497
+ * @defaultValue `'加载中...'`
498
+ */
499
+ defaultText?: string;
500
+ /**
501
+ * 旋转图标类型
502
+ *
503
+ * @defaultValue `'spinner'`
504
+ */
505
+ spinnerType?: SpinnerType;
506
+ /**
507
+ * 自定义样式配置
508
+ *
509
+ * @remarks 详见 {@link LoadingStyle}
510
+ */
511
+ style?: LoadingStyle;
512
+ /**
513
+ * 过渡动画配置
514
+ *
515
+ * @defaultValue `{ enabled: true, duration: 200, easing: 'ease-out' }`
516
+ */
517
+ transition?: TransitionConfig;
518
+ /**
519
+ * 最小显示时间配置
520
+ *
521
+ * @remarks 详见 {@link MinDisplayTime}
522
+ */
523
+ minDisplayTime?: MinDisplayTime;
524
+ /**
525
+ * 延迟显示配置
526
+ *
527
+ * @remarks 详见 {@link DelayShow}
528
+ */
529
+ delayShow?: DelayShow;
530
+ /**
531
+ * 防抖隐藏配置
532
+ *
533
+ * @remarks 详见 {@link DebounceHide}
534
+ */
535
+ debounceHide?: DebounceHide;
536
+ /**
537
+ * 自动绑定请求拦截模式
538
+ *
539
+ * @defaultValue `'none'`
540
+ */
541
+ autoBind?: AutoBindMode;
542
+ /**
543
+ * 请求过滤配置
544
+ *
545
+ * @remarks 详见 {@link RequestFilter}
546
+ */
547
+ requestFilter?: RequestFilter;
548
+ /**
549
+ * 注入到浏览器全局的变量名
550
+ *
551
+ * @defaultValue `'__LOADING_MANAGER__'`
552
+ *
553
+ * @example
554
+ * ```typescript
555
+ * loadingManager({ globalName: '__MY_LOADING__' })
556
+ * // 使用:window.__MY_LOADING__.show()
557
+ * ```
558
+ */
559
+ globalName?: string;
560
+ /**
561
+ * 自定义 Loading HTML 模板
562
+ *
563
+ * @remarks 如果提供,将替代默认的 loading 模板。
564
+ * 模板中 **必须** 包含一个具有 `data-loading-text` 属性的元素用于文本显示,
565
+ * 否则 {@link LoadingManager.updateText} 将无法工作
566
+ *
567
+ * @example
568
+ * ```typescript
569
+ * loadingManager({
570
+ * customTemplate: '<div class="my-loader"><span data-loading-text></span></div>'
571
+ * })
572
+ * ```
573
+ */
574
+ customTemplate?: string;
575
+ /**
576
+ * Loading DOM 的初始可见状态
577
+ *
578
+ * @defaultValue `false`
579
+ *
580
+ * @remarks
581
+ * 设为 `true` 时,loading DOM 以可见状态注入到 HTML 的 `<head>` 中,
582
+ * 无需等待 JS 执行即可在白屏阶段显示 loading。
583
+ *
584
+ * 典型用法:配合 {@link autoHideOn} 使用,实现"白屏时显示 → 页面就绪后自动隐藏"。
585
+ *
586
+ * @example
587
+ * ```typescript
588
+ * // 白屏阶段即显示 loading,DOMContentLoaded 后自动隐藏
589
+ * loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
590
+ *
591
+ * // 白屏阶段即显示 loading,所有资源加载完成后自动隐藏
592
+ * loadingManager({ defaultVisible: true, autoHideOn: 'load' })
593
+ *
594
+ * // Vue/React SPA:白屏阶段即显示,框架渲染完成后手动隐藏
595
+ * loadingManager({ defaultVisible: true, autoHideOn: 'manual' })
596
+ * // 在应用入口处:window.__LOADING_MANAGER__.hide()
597
+ * ```
598
+ */
599
+ defaultVisible?: boolean;
600
+ /**
601
+ * 当 `defaultVisible` 为 `true` 时,loading 的自动隐藏时机
602
+ *
603
+ * @defaultValue `'DOMContentLoaded'`
604
+ *
605
+ * @remarks 仅在 {@link defaultVisible} 为 `true` 时生效:
606
+ * - `'DOMContentLoaded'` — DOM 解析完成后自动隐藏(适合 SSR/MPA)
607
+ * - `'load'` — 所有资源(图片、样式等)加载完成后自动隐藏(适合资源较重的页面)
608
+ * - `'manual'` — 不自动隐藏,需在应用代码中手动调用 `window.__LOADING_MANAGER__.hide()`
609
+ * (适合 Vue/React SPA,在框架渲染完成后手动隐藏)
610
+ */
611
+ autoHideOn?: AutoHideOn;
612
+ /**
613
+ * 生命周期回调
614
+ *
615
+ * @remarks 回调以函数体字符串形式提供,在运行时执行。
616
+ * 详见 {@link LoadingCallbacks}
617
+ *
618
+ * @example
619
+ * ```typescript
620
+ * loadingManager({
621
+ * callbacks: {
622
+ * onShow: 'console.log("loading shown")',
623
+ * onBeforeShow: 'return true'
624
+ * }
625
+ * })
626
+ * ```
627
+ */
628
+ callbacks?: LoadingCallbacks;
629
+ }
630
+
631
+ /**
632
+ * 全局 Loading 状态管理插件
633
+ *
634
+ * @param options - 插件配置选项,详见 {@link LoadingManagerOptions}
635
+ * @returns Vite 插件实例
636
+ *
637
+ * @example
638
+ * ```typescript
639
+ * // 基本使用
640
+ * loadingManager()
641
+ *
642
+ * // 自定义位置和文本
643
+ * loadingManager({
644
+ * position: 'top',
645
+ * defaultText: '请稍候...'
646
+ * })
647
+ *
648
+ * // 使用不同类型的加载图标
649
+ * loadingManager({
650
+ * spinnerType: 'dots', // spinner | dots | pulse | bar
651
+ * })
652
+ *
653
+ * // 自动拦截 fetch 请求
654
+ * loadingManager({
655
+ * autoBind: 'fetch',
656
+ * requestFilter: {
657
+ * excludeUrls: [/\/api\/health/],
658
+ * excludeUrlPrefixes: ['http://localhost']
659
+ * }
660
+ * })
661
+ *
662
+ * // 自定义样式(含模糊背景)
663
+ * loadingManager({
664
+ * style: {
665
+ * overlayColor: 'rgba(0, 0, 0, 0.5)',
666
+ * spinnerColor: '#ff6b6b',
667
+ * spinnerSize: '50px',
668
+ * backdropBlur: true,
669
+ * backdropBlurAmount: 6
670
+ * }
671
+ * })
672
+ *
673
+ * // 自定义过渡动画
674
+ * loadingManager({
675
+ * transition: {
676
+ * enabled: true,
677
+ * duration: 300,
678
+ * easing: 'cubic-bezier(0.4, 0, 0.2, 1)'
679
+ * }
680
+ * })
681
+ *
682
+ * // 防抖隐藏(避免快速闪烁)
683
+ * loadingManager({
684
+ * debounceHide: {
685
+ * enabled: true,
686
+ * duration: 100
687
+ * }
688
+ * })
689
+ *
690
+ * // 生命周期回调
691
+ * loadingManager({
692
+ * callbacks: {
693
+ * onShow: 'console.log("loading shown")',
694
+ * onBeforeShow: 'return true', // 返回 false 可阻止显示
695
+ * onHide: 'console.log("loading hidden")'
696
+ * }
697
+ * })
698
+ *
699
+ * // 自定义模板
700
+ * loadingManager({
701
+ * customTemplate: '<div class="my-loader"><span data-loading-text></span></div>'
702
+ * })
703
+ *
704
+ * // 白屏阶段即显示 loading,DOMContentLoaded 后自动隐藏
705
+ * loadingManager({
706
+ * defaultVisible: true,
707
+ * autoHideOn: 'DOMContentLoaded'
708
+ * })
709
+ *
710
+ * // 白屏阶段即显示 loading,所有资源加载完成后自动隐藏
711
+ * loadingManager({
712
+ * defaultVisible: true,
713
+ * autoHideOn: 'load'
714
+ * })
715
+ *
716
+ * // Vue/React SPA:白屏阶段即显示,框架渲染完成后手动隐藏
717
+ * loadingManager({
718
+ * defaultVisible: true,
719
+ * autoHideOn: 'manual'
720
+ * })
721
+ * // 在应用入口处手动隐藏:
722
+ * // window.__LOADING_MANAGER__.hide()
723
+ * ```
724
+ *
725
+ * @remarks
726
+ * 该插件在 HTML 中注入全局 Loading 状态管理代码,提供以下能力:
727
+ * - 全局 loading 的创建、显示、隐藏和销毁
728
+ * - 跨组件/页面共享 loading 状态
729
+ * - 多种内置加载图标(spinner / dots / pulse / bar)
730
+ * - 自定义样式、文本和显示位置
731
+ * - 过渡动画配置(淡入淡出)
732
+ * - 自动拦截 fetch/XHR 请求实现 loading 自动管理
733
+ * - 延迟显示和最小显示时间机制
734
+ * - 防抖隐藏避免闪烁
735
+ * - 请求过滤(排除/包含特定 URL、前缀匹配、方法过滤)
736
+ * - 生命周期回调(onBeforeShow / onShow / onBeforeHide / onHide / onDestroy)
737
+ * - 背景模糊效果(backdrop-filter)
738
+ * - 销毁时自动恢复原始 fetch/XHR
739
+ * - SSR 环境安全检测
740
+ * - 白屏阶段即显示 loading(defaultVisible + autoHideOn)
741
+ *
742
+ * 运行时 API:
743
+ * ```typescript
744
+ * // 显示 loading
745
+ * window.__LOADING_MANAGER__.show('加载中...')
746
+ *
747
+ * // 隐藏 loading
748
+ * window.__LOADING_MANAGER__.hide()
749
+ *
750
+ * // 强制隐藏(忽略最小显示时间)
751
+ * window.__LOADING_MANAGER__.forceHide()
752
+ *
753
+ * // 更新文本
754
+ * window.__LOADING_MANAGER__.updateText('正在处理...')
755
+ *
756
+ * // 检查状态
757
+ * window.__LOADING_MANAGER__.isVisible()
758
+ *
759
+ * // 获取挂起请求数
760
+ * window.__LOADING_MANAGER__.getPendingCount()
761
+ *
762
+ * // 销毁(恢复原始 fetch/XHR)
763
+ * window.__LOADING_MANAGER__.destroy()
764
+ * ```
765
+ */
766
+ declare const loadingManager: PluginFactory<LoadingManagerOptions, LoadingManagerOptions>;
767
+
768
+ export { loadingManager };
769
+ export type { AutoBindMode, AutoHideOn, DebounceHide, DelayShow, LoadingCallbacks, LoadingManager, LoadingManagerOptions, LoadingPosition, LoadingStyle, MinDisplayTime, RequestFilter, SpinnerType, TransitionConfig };