@meng-xi/vite-plugin 0.1.2 → 0.1.3
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.
- package/README-en.md +492 -190
- package/README.md +464 -163
- package/dist/common/compress/index.cjs +1 -0
- package/dist/common/compress/index.d.cts +23 -0
- package/dist/common/compress/index.d.mts +23 -0
- package/dist/common/compress/index.d.ts +23 -0
- package/dist/common/compress/index.mjs +1 -0
- package/dist/common/format/index.cjs +1 -1
- package/dist/common/format/index.d.cts +33 -1
- package/dist/common/format/index.d.mts +33 -1
- package/dist/common/format/index.d.ts +33 -1
- package/dist/common/format/index.mjs +1 -1
- package/dist/common/fs/index.cjs +1 -1
- package/dist/common/fs/index.d.cts +70 -2
- package/dist/common/fs/index.d.mts +70 -2
- package/dist/common/fs/index.d.ts +70 -2
- package/dist/common/fs/index.mjs +1 -1
- package/dist/common/index.cjs +1 -1
- package/dist/common/index.d.cts +4 -2
- package/dist/common/index.d.mts +4 -2
- package/dist/common/index.d.ts +4 -2
- package/dist/common/index.mjs +1 -1
- package/dist/common/path/index.cjs +1 -0
- package/dist/common/path/index.d.cts +22 -0
- package/dist/common/path/index.d.mts +22 -0
- package/dist/common/path/index.d.ts +22 -0
- package/dist/common/path/index.mjs +1 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +5 -2
- package/dist/index.d.mts +5 -2
- package/dist/index.d.ts +5 -2
- package/dist/index.mjs +1 -1
- package/dist/plugins/bundleAnalyzer/index.cjs +235 -0
- package/dist/plugins/bundleAnalyzer/index.d.cts +215 -0
- package/dist/plugins/bundleAnalyzer/index.d.mts +215 -0
- package/dist/plugins/bundleAnalyzer/index.d.ts +215 -0
- package/dist/plugins/bundleAnalyzer/index.mjs +235 -0
- package/dist/plugins/compressAssets/index.cjs +1 -1
- package/dist/plugins/compressAssets/index.mjs +1 -1
- package/dist/plugins/generateRouter/index.cjs +4 -4
- package/dist/plugins/generateRouter/index.mjs +1 -1
- package/dist/plugins/generateVersion/index.cjs +1 -1
- package/dist/plugins/generateVersion/index.mjs +1 -1
- package/dist/plugins/htmlInject/index.cjs +7 -7
- package/dist/plugins/htmlInject/index.mjs +2 -2
- package/dist/plugins/index.cjs +1 -1
- package/dist/plugins/index.d.cts +1 -0
- package/dist/plugins/index.d.mts +1 -0
- package/dist/plugins/index.d.ts +1 -0
- package/dist/plugins/index.mjs +1 -1
- package/dist/plugins/loadingManager/index.cjs +1 -1
- package/dist/plugins/loadingManager/index.mjs +1 -1
- package/package.json +16 -1
package/README.md
CHANGED
|
@@ -15,8 +15,9 @@
|
|
|
15
15
|
|
|
16
16
|
## 特性
|
|
17
17
|
|
|
18
|
-
- **开箱即用** - 提供
|
|
18
|
+
- **开箱即用** - 提供 10 个实用插件，覆盖构建进度展示、构建产物分析与压缩、文件复制、路由生成、版本管理、版本更新检查、HTML 注入、图标注入、全局 Loading 状态管理等常见场景
|
|
19
19
|
- **插件开发框架** - 导出 BasePlugin、Logger、Validator 等核心组件，快速构建符合规范的自定义 Vite 插件
|
|
20
|
+
- **通用工具库** - 内置 Common 工具模块，提供格式化、文件系统、压缩、路径处理、HTML 注入、对象操作、脚本生成、参数验证等可复用工具函数
|
|
20
21
|
- **完整生命周期** - 支持初始化、配置解析、销毁等生命周期管理，自动组合钩子逻辑
|
|
21
22
|
- **类型安全** - 完整的 TypeScript 类型定义，配置验证器确保参数正确性
|
|
22
23
|
- **灵活配置** - 所有插件支持详细配置，满足多样化场景需求
|
|
@@ -46,11 +47,12 @@ pnpm add @meng-xi/vite-plugin -D
|
|
|
46
47
|
|
|
47
48
|
```typescript
|
|
48
49
|
import { defineConfig } from 'vite'
|
|
49
|
-
import { buildProgress, compressAssets, copyFile, generateRouter, generateVersion, versionUpdateChecker, htmlInject, faviconManager, loadingManager } from '@meng-xi/vite-plugin'
|
|
50
|
+
import { buildProgress, bundleAnalyzer, compressAssets, copyFile, generateRouter, generateVersion, versionUpdateChecker, htmlInject, faviconManager, loadingManager } from '@meng-xi/vite-plugin'
|
|
50
51
|
|
|
51
52
|
export default defineConfig({
|
|
52
53
|
plugins: [
|
|
53
54
|
buildProgress(),
|
|
55
|
+
bundleAnalyzer({ outputFormat: 'both', sizeThreshold: 200 }),
|
|
54
56
|
compressAssets({ algorithm: 'gzip' }),
|
|
55
57
|
copyFile({ sourceDir: 'src/assets', targetDir: 'dist/assets' }),
|
|
56
58
|
generateRouter({ pagesJsonPath: 'src/pages.json', outputPath: 'src/router.config.ts' }),
|
|
@@ -79,17 +81,18 @@ console.log(routerPlugin.pluginInstance?.options)
|
|
|
79
81
|
|
|
80
82
|
## 内置插件
|
|
81
83
|
|
|
82
|
-
| 插件 | 说明
|
|
83
|
-
| -------------------- |
|
|
84
|
-
| buildProgress | 终端实时构建进度条，支持 bar / spinner / minimal
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
84
|
+
| 插件 | 说明 |
|
|
85
|
+
| -------------------- | --------------------------------------------------------------------- |
|
|
86
|
+
| buildProgress | 终端实时构建进度条，支持 bar / spinner / minimal |
|
|
87
|
+
| bundleAnalyzer | 构建产物体积分析，支持 JSON/HTML 报告、gzip 计算、阈值告警和构建对比 |
|
|
88
|
+
| compressAssets | 构建产物压缩，支持 gzip / brotli / both，并发压缩和统计报告 |
|
|
89
|
+
| copyFile | 构建完成后复制文件或目录，支持增量复制 |
|
|
90
|
+
| generateRouter | 根据 pages.json 自动生成路由配置（uni-app） |
|
|
91
|
+
| generateVersion | 自动生成版本号，支持文件输出和全局变量注入 |
|
|
92
|
+
| versionUpdateChecker | 运行时版本更新检查，支持多种提示样式和自定义回调 |
|
|
93
|
+
| htmlInject | HTML 内容注入，支持多种位置、选择器定位、条件注入、模板变量和安全过滤 |
|
|
94
|
+
| faviconManager | 管理网站图标链接注入和文件复制，支持字符串简写配置 |
|
|
95
|
+
| loadingManager | 全局 Loading 状态管理，支持请求拦截、防抖、过渡动画和白屏 Loading |
|
|
93
96
|
|
|
94
97
|
---
|
|
95
98
|
|
|
@@ -140,6 +143,44 @@ buildProgress({
|
|
|
140
143
|
|
|
141
144
|
---
|
|
142
145
|
|
|
146
|
+
### bundleAnalyzer
|
|
147
|
+
|
|
148
|
+
在 Vite 构建完成后自动分析输出目录中的构建产物，生成体积统计、模块排行、文件类型分布等关键指标，支持 JSON 报告和 HTML 可视化图表。
|
|
149
|
+
|
|
150
|
+
**核心功能：**
|
|
151
|
+
|
|
152
|
+
- 扫描构建输出目录，分析 chunk、模块和资源文件
|
|
153
|
+
- 计算原始大小和 gzip 压缩大小
|
|
154
|
+
- 按文件类型统计体积分布
|
|
155
|
+
- Top N 大模块排行
|
|
156
|
+
- 体积阈值告警（超过阈值 2 倍标记为 critical）
|
|
157
|
+
- 与上次构建结果对比，生成差异报告
|
|
158
|
+
- HTML 报告支持 treemap / sunburst / list 三种可视化图表
|
|
159
|
+
|
|
160
|
+
| 选项 | 类型 | 默认值 | 描述 |
|
|
161
|
+
| ------------------ | --------------------------------------- | ------------------- | ---------------------------------------- |
|
|
162
|
+
| outputFormat | `'json'` \| `'html'` \| `'both'` | `'json'` | 报告输出格式 |
|
|
163
|
+
| outputFile | `string` | `'bundle-analysis'` | 报告输出文件名（不含扩展名） |
|
|
164
|
+
| openAnalyzer | `boolean` | `false` | 是否在生成 HTML 报告后自动打开浏览器 |
|
|
165
|
+
| sizeThreshold | `number` | `100` | 体积告警阈值（KB） |
|
|
166
|
+
| topModules | `number` | `20` | Top N 大模块排行数量 |
|
|
167
|
+
| gzipSize | `boolean` | `true` | 是否计算 gzip 大小 |
|
|
168
|
+
| excludeNodeModules | `boolean` | `false` | 是否排除 node_modules 中的模块 |
|
|
169
|
+
| excludePatterns | `string[]` | `[]` | 需要排除的文件路径模式列表 |
|
|
170
|
+
| includeExtensions | `string[]` | `[]` | 需要包含的文件扩展名列表，为空则包含所有 |
|
|
171
|
+
| compareWith | `string` \| `null` | `null` | 用于对比的之前分析报告路径 |
|
|
172
|
+
| defaultChartType | `'treemap'` \| `'sunburst'` \| `'list'` | `'treemap'` | HTML 报告中图表的默认展示形式 |
|
|
173
|
+
|
|
174
|
+
```typescript
|
|
175
|
+
bundleAnalyzer()
|
|
176
|
+
bundleAnalyzer({ outputFormat: 'both', openAnalyzer: true })
|
|
177
|
+
bundleAnalyzer({ sizeThreshold: 200, topModules: 30, gzipSize: true })
|
|
178
|
+
bundleAnalyzer({ compareWith: 'dist/bundle-analysis.json', defaultChartType: 'sunburst' })
|
|
179
|
+
bundleAnalyzer({ excludeNodeModules: true, includeExtensions: ['.js', '.css'] })
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
143
184
|
### compressAssets
|
|
144
185
|
|
|
145
186
|
在 Vite 构建完成后自动压缩输出目录中的文件，支持 gzip 和 brotli 两种压缩算法。
|
|
@@ -310,57 +351,56 @@ versionUpdateChecker({ enableInDev: true })
|
|
|
310
351
|
|
|
311
352
|
### htmlInject
|
|
312
353
|
|
|
313
|
-
在
|
|
314
|
-
|
|
315
|
-
**注入位置：**
|
|
316
|
-
|
|
317
|
-
| 位置 | 说明 |
|
|
318
|
-
| ------------------ | -------------------------- |
|
|
319
|
-
| `head-start` | 注入到 `<head>` 标签开始后 |
|
|
320
|
-
| `head-end` | 注入到 `</head>` 标签前 |
|
|
321
|
-
| `body-start` | 注入到 `<body>` 标签开始后 |
|
|
322
|
-
| `body-end` | 注入到 `</body>` 标签前 |
|
|
323
|
-
| `before-selector` | 注入到选择器匹配内容前 |
|
|
324
|
-
| `after-selector` | 注入到选择器匹配内容后 |
|
|
325
|
-
| `replace-selector` | 替换选择器匹配的内容 |
|
|
354
|
+
在 HTML 文件中注入自定义内容，支持多种位置、选择器定位、条件注入、模板变量替换和安全过滤。
|
|
326
355
|
|
|
327
356
|
| 选项 | 类型 | 默认值 | 描述 |
|
|
328
357
|
| ------------ | ------------------------ | -------------- | -------------------------- |
|
|
329
358
|
| targetFile | `string` | `'index.html'` | 目标 HTML 文件路径或文件名 |
|
|
330
|
-
| rules | `InjectRule[]` | - |
|
|
359
|
+
| rules | `InjectRule[]` | - | 注入规则列表（必填） |
|
|
331
360
|
| security | `SecurityConfig` | - | 安全过滤配置 |
|
|
332
|
-
| templateVars | `Record<string, string>` |
|
|
333
|
-
| logInjection | `boolean` | `true` |
|
|
361
|
+
| templateVars | `Record<string, string>` | `{}` | 全局模板变量映射 |
|
|
362
|
+
| logInjection | `boolean` | `true` | 是否在控制台输出注入日志 |
|
|
334
363
|
|
|
335
364
|
**InjectRule**
|
|
336
365
|
|
|
337
|
-
| 属性 | 类型
|
|
338
|
-
| -------------------- |
|
|
339
|
-
| id | `string`
|
|
340
|
-
| content | `string`
|
|
341
|
-
| position | `
|
|
342
|
-
| selector | `string`
|
|
343
|
-
| selectorMatch | `'string'` \| `'regex'`
|
|
344
|
-
| priority | `number`
|
|
345
|
-
| condition | `InjectCondition`
|
|
346
|
-
| templateVars | `Record<string, string>`
|
|
347
|
-
| allowScriptInjection | `boolean`
|
|
366
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
367
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------- |
|
|
368
|
+
| id | `string` | - | 规则唯一标识 |
|
|
369
|
+
| content | `string` | - | 注入内容 |
|
|
370
|
+
| position | `'head-start'` \| `'head-end'` \| `'body-start'` \| `'body-end'` \| `'before-selector'` \| `'after-selector'` \| `'replace-selector'` | - | 注入位置 |
|
|
371
|
+
| selector | `string` | - | 选择器字符串（selector 相关位置时必填） |
|
|
372
|
+
| selectorMatch | `'string'` \| `'regex'` | `'string'` | 选择器匹配模式 |
|
|
373
|
+
| priority | `number` | `100` | 规则优先级，数值越小越先执行 |
|
|
374
|
+
| condition | `InjectCondition` | - | 注入条件 |
|
|
375
|
+
| templateVars | `Record<string, string>` | - | 规则级模板变量（覆盖全局 templateVars） |
|
|
376
|
+
| allowScriptInjection | `boolean` | `false` | 是否允许注入脚本等危险内容 |
|
|
377
|
+
|
|
378
|
+
**InjectCondition**
|
|
379
|
+
|
|
380
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
381
|
+
| ------ | ------------------------------------------ | ------- | ------------------ |
|
|
382
|
+
| type | `'env'` \| `'file-contains'` \| `'custom'` | - | 条件类型 |
|
|
383
|
+
| value | `string` \| `(...args: any[]) => boolean` | - | 条件值 |
|
|
384
|
+
| negate | `boolean` | `false` | 是否对条件结果取反 |
|
|
348
385
|
|
|
349
386
|
**SecurityConfig**
|
|
350
387
|
|
|
351
|
-
| 属性 | 类型 | 默认值 | 描述
|
|
352
|
-
| ------------------------ | ---------- | ------ |
|
|
353
|
-
| blockDangerousTags | `boolean` | `true` |
|
|
354
|
-
| blockDangerousAttributes | `boolean` | `true` |
|
|
355
|
-
| allowedTags | `string[]` | - | 允许通过的标签白名单
|
|
356
|
-
| blockedTags | `string[]` | - | 自定义阻止标签列表
|
|
357
|
-
| blockedAttributes | `string[]` | - | 自定义阻止属性列表
|
|
388
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
389
|
+
| ------------------------ | ---------- | ------ | ------------------------------ |
|
|
390
|
+
| blockDangerousTags | `boolean` | `true` | 是否阻止危险标签（script 等） |
|
|
391
|
+
| blockDangerousAttributes | `boolean` | `true` | 是否阻止危险属性（onclick 等） |
|
|
392
|
+
| allowedTags | `string[]` | - | 允许通过的标签白名单 |
|
|
393
|
+
| blockedTags | `string[]` | - | 自定义阻止标签列表 |
|
|
394
|
+
| blockedAttributes | `string[]` | - | 自定义阻止属性列表 |
|
|
358
395
|
|
|
359
396
|
```typescript
|
|
360
397
|
htmlInject({
|
|
361
398
|
rules: [
|
|
362
|
-
{ id: 'meta-description', content: '<meta name="description" content="
|
|
363
|
-
{ id: 'analytics', content: '<script src="
|
|
399
|
+
{ id: 'meta-description', content: '<meta name="description" content="My App">', position: 'head-end' },
|
|
400
|
+
{ id: 'analytics', content: '<script src="https://analytics.example.com/track.js"></script>', position: 'body-end', allowScriptInjection: true },
|
|
401
|
+
{ id: 'env-var', content: '<script>window.__ENV__ = "{{env}}"</script>', position: 'head-end', templateVars: { env: 'production' }, allowScriptInjection: true },
|
|
402
|
+
{ id: 'before-app', content: '<div>Before App</div>', position: 'before-selector', selector: '<div id="app">' },
|
|
403
|
+
{ id: 'prod-only', content: '<meta name="robots" content="noindex">', position: 'head-end', condition: { type: 'env', value: 'PRODUCTION' } }
|
|
364
404
|
]
|
|
365
405
|
})
|
|
366
406
|
```
|
|
@@ -369,15 +409,15 @@ htmlInject({
|
|
|
369
409
|
|
|
370
410
|
### faviconManager
|
|
371
411
|
|
|
372
|
-
|
|
412
|
+
管理网站图标链接注入到 HTML 文件，支持图标文件复制，支持字符串简写配置。
|
|
373
413
|
|
|
374
|
-
| 选项 | 类型
|
|
375
|
-
| ----------- |
|
|
376
|
-
| base | `string`
|
|
377
|
-
| url | `string`
|
|
378
|
-
| link | `string`
|
|
379
|
-
| icons | `Icon[]`
|
|
380
|
-
| copyOptions | `
|
|
414
|
+
| 选项 | 类型 | 默认值 | 描述 |
|
|
415
|
+
| ----------- | ------------- | ------ | ----------------------------------------- |
|
|
416
|
+
| base | `string` | `'/'` | 图标文件的基础路径 |
|
|
417
|
+
| url | `string` | - | 图标完整 URL（优先于 base + favicon.ico） |
|
|
418
|
+
| link | `string` | - | 自定义完整 link 标签 HTML（最高优先级） |
|
|
419
|
+
| icons | `Icon[]` | - | 自定义图标数组，支持多种格式和尺寸 |
|
|
420
|
+
| copyOptions | `CopyOptions` | - | 图标文件复制配置 |
|
|
381
421
|
|
|
382
422
|
**Icon**
|
|
383
423
|
|
|
@@ -388,9 +428,18 @@ htmlInject({
|
|
|
388
428
|
| sizes | `string` | 图标尺寸 |
|
|
389
429
|
| type | `string` | 图标 MIME 类型 |
|
|
390
430
|
|
|
431
|
+
**CopyOptions**
|
|
432
|
+
|
|
433
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
434
|
+
| --------- | --------- | ------ | ---------------------- |
|
|
435
|
+
| sourceDir | `string` | - | 图标源文件目录（必填） |
|
|
436
|
+
| targetDir | `string` | - | 图标目标目录（必填） |
|
|
437
|
+
| overwrite | `boolean` | `true` | 是否覆盖同名文件 |
|
|
438
|
+
| recursive | `boolean` | `true` | 是否递归复制 |
|
|
439
|
+
|
|
391
440
|
```typescript
|
|
392
|
-
faviconManager()
|
|
393
441
|
faviconManager('/assets')
|
|
442
|
+
faviconManager({ base: '/assets', url: '/assets/favicon.ico' })
|
|
394
443
|
faviconManager({
|
|
395
444
|
base: '/assets',
|
|
396
445
|
icons: [
|
|
@@ -398,49 +447,109 @@ faviconManager({
|
|
|
398
447
|
{ rel: 'icon', href: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' }
|
|
399
448
|
]
|
|
400
449
|
})
|
|
401
|
-
faviconManager({
|
|
402
|
-
|
|
450
|
+
faviconManager({
|
|
451
|
+
base: '/assets',
|
|
452
|
+
copyOptions: { sourceDir: 'src/assets/icons', targetDir: 'dist/assets/icons' }
|
|
453
|
+
})
|
|
403
454
|
```
|
|
404
455
|
|
|
405
456
|
---
|
|
406
457
|
|
|
407
458
|
### loadingManager
|
|
408
459
|
|
|
409
|
-
全局 Loading
|
|
410
|
-
|
|
411
|
-
| 选项 | 类型
|
|
412
|
-
| -------------- |
|
|
413
|
-
| position | `
|
|
414
|
-
| defaultText | `string`
|
|
415
|
-
| spinnerType | `
|
|
416
|
-
|
|
|
417
|
-
|
|
|
418
|
-
|
|
|
419
|
-
|
|
|
420
|
-
|
|
|
421
|
-
|
|
|
422
|
-
|
|
|
423
|
-
|
|
|
424
|
-
|
|
|
425
|
-
|
|
|
426
|
-
|
|
|
427
|
-
| callbacks | `LoadingCallbacks`
|
|
460
|
+
全局 Loading 状态管理，支持请求拦截、防抖、过渡动画和白屏 Loading。
|
|
461
|
+
|
|
462
|
+
| 选项 | 类型 | 默认值 | 描述 |
|
|
463
|
+
| -------------- | ------------------ | ----------------------- | ------------------------------------------------ |
|
|
464
|
+
| position | `LoadingPosition` | `'center'` | Loading 显示位置 |
|
|
465
|
+
| defaultText | `string` | `'加载中...'` | 默认显示文本 |
|
|
466
|
+
| spinnerType | `SpinnerType` | `'spinner'` | 旋转图标类型 |
|
|
467
|
+
| style | `LoadingStyle` | - | 自定义样式配置 |
|
|
468
|
+
| transition | `TransitionConfig` | - | 过渡动画配置 |
|
|
469
|
+
| minDisplayTime | `MinDisplayTime` | - | 最小显示时间配置 |
|
|
470
|
+
| delayShow | `DelayShow` | - | 延迟显示配置 |
|
|
471
|
+
| debounceHide | `DebounceHide` | - | 防抖隐藏配置 |
|
|
472
|
+
| autoBind | `AutoBindMode` | `'none'` | 自动绑定请求拦截模式 |
|
|
473
|
+
| requestFilter | `RequestFilter` | - | 请求过滤配置 |
|
|
474
|
+
| globalName | `string` | `'__LOADING_MANAGER__'` | 注入的全局变量名 |
|
|
475
|
+
| customTemplate | `string` | - | 自定义 Loading HTML 模板 |
|
|
476
|
+
| defaultVisible | `boolean` | `false` | Loading DOM 初始可见状态（白屏 Loading） |
|
|
477
|
+
| autoHideOn | `AutoHideOn` | `'DOMContentLoaded'` | 自动隐藏时机（仅 defaultVisible 为 true 时生效） |
|
|
478
|
+
| callbacks | `LoadingCallbacks` | - | 生命周期回调 |
|
|
479
|
+
|
|
480
|
+
**LoadingPosition**：`'center'` | `'top'` | `'bottom'`
|
|
481
|
+
|
|
482
|
+
**SpinnerType**：`'spinner'` | `'dots'` | `'pulse'` | `'bar'`
|
|
483
|
+
|
|
484
|
+
**AutoBindMode**：`'fetch'` | `'xhr'` | `'all'` | `'none'`
|
|
485
|
+
|
|
486
|
+
**AutoHideOn**：`'DOMContentLoaded'` | `'load'` | `'manual'`
|
|
428
487
|
|
|
429
488
|
**LoadingStyle**
|
|
430
489
|
|
|
431
490
|
| 属性 | 类型 | 默认值 | 描述 |
|
|
432
491
|
| ------------------ | --------- | ------------------------- | ---------------------- |
|
|
433
492
|
| overlayColor | `string` | `'rgba(255,255,255,0.7)'` | 遮罩层背景色 |
|
|
434
|
-
| spinnerColor | `string` | `'#4361ee'` | 图标颜色
|
|
435
|
-
| spinnerSize | `string` | `'40px'` | 图标大小
|
|
493
|
+
| spinnerColor | `string` | `'#4361ee'` | Loading 图标颜色 |
|
|
494
|
+
| spinnerSize | `string` | `'40px'` | Loading 图标大小 |
|
|
436
495
|
| textColor | `string` | `'#333'` | 文本颜色 |
|
|
437
496
|
| textSize | `string` | `'14px'` | 文本大小 |
|
|
438
|
-
| zIndex | `number` | `9999` | z-index 值 |
|
|
439
|
-
| pointerEvents | `boolean` | `true` | 是否启用遮罩层指针事件 |
|
|
440
|
-
| backdropBlur | `boolean` | `false` | 是否启用背景模糊 |
|
|
441
|
-
| backdropBlurAmount | `number` | `4` | 背景模糊程度（px） |
|
|
442
497
|
| customClass | `string` | - | 自定义 CSS 类名 |
|
|
443
498
|
| customStyle | `string` | - | 自定义内联样式字符串 |
|
|
499
|
+
| zIndex | `number` | `9999` | 遮罩层 z-index |
|
|
500
|
+
| pointerEvents | `boolean` | `true` | 是否启用遮罩层指针事件 |
|
|
501
|
+
| backdropBlur | `boolean` | `false` | 是否启用背景模糊效果 |
|
|
502
|
+
| backdropBlurAmount | `number` | `4` | 背景模糊程度（px） |
|
|
503
|
+
|
|
504
|
+
**TransitionConfig**
|
|
505
|
+
|
|
506
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
507
|
+
| -------- | --------- | ------------ | ---------------------- |
|
|
508
|
+
| enabled | `boolean` | `true` | 是否启用过渡动画 |
|
|
509
|
+
| duration | `number` | `200` | 过渡动画持续时间（ms） |
|
|
510
|
+
| easing | `string` | `'ease-out'` | CSS 过渡缓动函数 |
|
|
511
|
+
|
|
512
|
+
**MinDisplayTime**
|
|
513
|
+
|
|
514
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
515
|
+
| -------- | --------- | ------ | -------------------- |
|
|
516
|
+
| enabled | `boolean` | `true` | 是否启用最小显示时间 |
|
|
517
|
+
| duration | `number` | `300` | 最小显示时间（ms） |
|
|
518
|
+
|
|
519
|
+
**DelayShow**
|
|
520
|
+
|
|
521
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
522
|
+
| -------- | --------- | ------ | ------------------------------------------ |
|
|
523
|
+
| enabled | `boolean` | `true` | 是否启用延迟显示 |
|
|
524
|
+
| duration | `number` | `200` | 延迟时间（ms），请求在此时间内完成则不显示 |
|
|
525
|
+
|
|
526
|
+
**DebounceHide**
|
|
527
|
+
|
|
528
|
+
| 属性 | 类型 | 默认值 | 描述 |
|
|
529
|
+
| -------- | --------- | ------- | ------------------ |
|
|
530
|
+
| enabled | `boolean` | `false` | 是否启用防抖隐藏 |
|
|
531
|
+
| duration | `number` | `100` | 防抖等待时间（ms） |
|
|
532
|
+
|
|
533
|
+
**RequestFilter**
|
|
534
|
+
|
|
535
|
+
| 属性 | 类型 | 描述 |
|
|
536
|
+
| ------------------ | ---------- | ----------------------------- |
|
|
537
|
+
| excludeUrls | `RegExp[]` | 需要排除的 URL 正则表达式数组 |
|
|
538
|
+
| includeUrls | `RegExp[]` | 需要包含的 URL 正则表达式数组 |
|
|
539
|
+
| excludeMethods | `string[]` | 需要排除的 HTTP 方法数组 |
|
|
540
|
+
| excludeUrlPrefixes | `string[]` | 需要排除的 URL 字符串前缀数组 |
|
|
541
|
+
|
|
542
|
+
**LoadingCallbacks**
|
|
543
|
+
|
|
544
|
+
| 属性 | 类型 | 描述 |
|
|
545
|
+
| ------------ | -------- | --------------------------------------- |
|
|
546
|
+
| onBeforeShow | `string` | 显示前回调（`return false` 可阻止显示） |
|
|
547
|
+
| onShow | `string` | 显示后回调 |
|
|
548
|
+
| onBeforeHide | `string` | 隐藏前回调（`return false` 可阻止隐藏） |
|
|
549
|
+
| onHide | `string` | 隐藏后回调 |
|
|
550
|
+
| onDestroy | `string` | 销毁时回调 |
|
|
551
|
+
|
|
552
|
+
> 回调以函数体字符串形式提供，因为需要注入到客户端代码中。`customTemplate` 中必须包含具有 `data-loading-text` 属性的元素用于文本显示。
|
|
444
553
|
|
|
445
554
|
**运行时 API：**
|
|
446
555
|
|
|
@@ -448,28 +557,27 @@ faviconManager({ base: '/assets', copyOptions: { sourceDir: 'src/assets/icons',
|
|
|
448
557
|
window.__LOADING_MANAGER__.show('加载中...')
|
|
449
558
|
window.__LOADING_MANAGER__.hide()
|
|
450
559
|
window.__LOADING_MANAGER__.forceHide()
|
|
451
|
-
window.__LOADING_MANAGER__.toggle()
|
|
560
|
+
window.__LOADING_MANAGER__.toggle('正在加载...')
|
|
452
561
|
window.__LOADING_MANAGER__.updateText('正在处理...')
|
|
453
562
|
window.__LOADING_MANAGER__.isVisible()
|
|
454
563
|
window.__LOADING_MANAGER__.getPendingCount()
|
|
455
|
-
window.__LOADING_MANAGER__.destroy()
|
|
456
564
|
window.__LOADING_MANAGER__.enablePointerEvents()
|
|
457
565
|
window.__LOADING_MANAGER__.disablePointerEvents()
|
|
458
|
-
window.__LOADING_MANAGER__.
|
|
459
|
-
window.__LOADING_MANAGER__.isPointerEventsEnabled()
|
|
566
|
+
window.__LOADING_MANAGER__.destroy()
|
|
460
567
|
```
|
|
461
568
|
|
|
462
569
|
```typescript
|
|
463
570
|
loadingManager()
|
|
464
|
-
loadingManager({
|
|
465
|
-
loadingManager({ spinnerType: 'dots' })
|
|
466
|
-
loadingManager({ autoBind: 'fetch', requestFilter: { excludeUrls: [/\/api\/health/]
|
|
467
|
-
loadingManager({
|
|
571
|
+
loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
|
|
572
|
+
loadingManager({ position: 'top', defaultText: '请稍候...', spinnerType: 'dots' })
|
|
573
|
+
loadingManager({ autoBind: 'fetch', requestFilter: { excludeUrls: [/\/api\/health/] } })
|
|
574
|
+
loadingManager({
|
|
575
|
+
style: { overlayColor: 'rgba(0,0,0,0.5)', spinnerColor: '#ff6b6b', backdropBlur: true, backdropBlurAmount: 6 }
|
|
576
|
+
})
|
|
468
577
|
loadingManager({ transition: { enabled: true, duration: 300, easing: 'cubic-bezier(0.4,0,0.2,1)' } })
|
|
469
578
|
loadingManager({ debounceHide: { enabled: true, duration: 100 } })
|
|
470
|
-
loadingManager({ callbacks: { onShow: 'console.log("
|
|
579
|
+
loadingManager({ callbacks: { onShow: 'console.log("shown")', onBeforeShow: 'return true' } })
|
|
471
580
|
loadingManager({ customTemplate: '<div class="my-loader"><span data-loading-text></span></div>' })
|
|
472
|
-
loadingManager({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
|
|
473
581
|
loadingManager({ defaultVisible: true, autoHideOn: 'manual' })
|
|
474
582
|
```
|
|
475
583
|
|
|
@@ -477,32 +585,41 @@ loadingManager({ defaultVisible: true, autoHideOn: 'manual' })
|
|
|
477
585
|
|
|
478
586
|
## 插件开发框架
|
|
479
587
|
|
|
588
|
+
本包不仅提供内置插件，还导出完整的插件开发框架，帮助快速构建符合规范的自定义 Vite 插件。
|
|
589
|
+
|
|
480
590
|
### BasePlugin
|
|
481
591
|
|
|
482
|
-
|
|
592
|
+
所有内置插件的基类，提供配置管理、日志记录、错误处理和生命周期管理等核心能力。
|
|
483
593
|
|
|
484
594
|
```typescript
|
|
485
|
-
import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin
|
|
595
|
+
import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin'
|
|
486
596
|
import type { Plugin } from 'vite'
|
|
487
597
|
|
|
488
598
|
interface MyPluginOptions {
|
|
489
|
-
|
|
490
|
-
message?: string
|
|
599
|
+
prefix?: string
|
|
491
600
|
}
|
|
492
601
|
|
|
493
602
|
class MyPlugin extends BasePlugin<MyPluginOptions> {
|
|
494
603
|
protected getPluginName() {
|
|
495
604
|
return 'my-plugin'
|
|
496
605
|
}
|
|
606
|
+
|
|
497
607
|
protected getDefaultOptions() {
|
|
498
|
-
return {
|
|
608
|
+
return { prefix: '[app]' }
|
|
499
609
|
}
|
|
610
|
+
|
|
500
611
|
protected validateOptions() {
|
|
501
|
-
this.validator.field('
|
|
612
|
+
this.validator.field('prefix').string().notEmpty().validate()
|
|
502
613
|
}
|
|
614
|
+
|
|
503
615
|
protected addPluginHooks(plugin: Plugin) {
|
|
504
|
-
plugin.
|
|
505
|
-
|
|
616
|
+
plugin.writeBundle = {
|
|
617
|
+
order: 'post',
|
|
618
|
+
handler: async () => {
|
|
619
|
+
await this.safeExecute(async () => {
|
|
620
|
+
this.logger.info('插件执行中...')
|
|
621
|
+
}, '执行自定义逻辑')
|
|
622
|
+
}
|
|
506
623
|
}
|
|
507
624
|
}
|
|
508
625
|
}
|
|
@@ -510,86 +627,270 @@ class MyPlugin extends BasePlugin<MyPluginOptions> {
|
|
|
510
627
|
export const myPlugin = createPluginFactory(MyPlugin)
|
|
511
628
|
```
|
|
512
629
|
|
|
513
|
-
|
|
630
|
+
**BasePlugin 核心方法：**
|
|
631
|
+
|
|
632
|
+
| 方法 | 描述 |
|
|
633
|
+
| ------------------- | ------------------------------------------ |
|
|
634
|
+
| `getDefaultOptions` | 返回插件默认配置，子类可重写 |
|
|
635
|
+
| `validateOptions` | 校验用户配置，子类可重写 |
|
|
636
|
+
| `getPluginName` | 返回插件名称（抽象方法，必须实现） |
|
|
637
|
+
| `getEnforce` | 返回插件执行时机（pre / post / undefined） |
|
|
638
|
+
| `addPluginHooks` | 注册 Vite 钩子（抽象方法，必须实现） |
|
|
639
|
+
| `onConfigResolved` | 配置解析完成回调 |
|
|
640
|
+
| `destroy` | 插件销毁回调 |
|
|
641
|
+
| `safeExecute` | 安全执行异步函数，自动错误处理 |
|
|
642
|
+
| `safeExecuteSync` | 安全执行同步函数，自动错误处理 |
|
|
643
|
+
| `handleError` | 根据 errorStrategy 处理错误 |
|
|
644
|
+
| `toPlugin` | 转换为 Vite 插件对象 |
|
|
645
|
+
|
|
646
|
+
**BasePluginOptions 基础配置：**
|
|
647
|
+
|
|
648
|
+
| 选项 | 类型 | 默认值 | 描述 |
|
|
649
|
+
| ------------- | ---------------------------------- | --------- | ------------ |
|
|
650
|
+
| enabled | `boolean` | `true` | 是否启用插件 |
|
|
651
|
+
| verbose | `boolean` | `true` | 是否启用日志 |
|
|
652
|
+
| errorStrategy | `'throw'` \| `'log'` \| `'ignore'` | `'throw'` | 错误处理策略 |
|
|
653
|
+
|
|
654
|
+
### createPluginFactory
|
|
655
|
+
|
|
656
|
+
创建插件工厂函数，将 BasePlugin 子类转换为可直接使用的 Vite 插件函数。
|
|
657
|
+
|
|
658
|
+
```typescript
|
|
659
|
+
import { createPluginFactory } from '@meng-xi/vite-plugin'
|
|
660
|
+
|
|
661
|
+
const myPlugin = createPluginFactory(MyPlugin)
|
|
662
|
+
|
|
663
|
+
// 支持选项标准化器（如字符串简写配置）
|
|
664
|
+
const myPluginWithNormalizer = createPluginFactory(MyPlugin, opt => (typeof opt === 'string' ? { prefix: opt } : opt))
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
### Logger
|
|
668
|
+
|
|
669
|
+
全局单例日志管理器，为每个插件提供独立的日志代理。
|
|
670
|
+
|
|
671
|
+
```typescript
|
|
672
|
+
import { Logger } from '@meng-xi/vite-plugin/logger'
|
|
673
|
+
|
|
674
|
+
const logger = Logger.create({ name: 'my-plugin', enabled: true })
|
|
675
|
+
logger.info('信息日志')
|
|
676
|
+
logger.success('成功日志')
|
|
677
|
+
logger.warn('警告日志')
|
|
678
|
+
logger.error('错误日志')
|
|
679
|
+
```
|
|
680
|
+
|
|
681
|
+
### Validator
|
|
514
682
|
|
|
515
|
-
|
|
516
|
-
| --------------------- | ------------------------------ | ---------------------- |
|
|
517
|
-
| `BasePlugin` | `@meng-xi/vite-plugin/factory` | 插件基类 |
|
|
518
|
-
| `createPluginFactory` | `@meng-xi/vite-plugin/factory` | 插件工厂函数创建器 |
|
|
519
|
-
| `PluginWithInstance` | `@meng-xi/vite-plugin/factory` | 带实例引用的插件类型 |
|
|
520
|
-
| `Logger` | `@meng-xi/vite-plugin/logger` | 日志管理器（单例模式） |
|
|
521
|
-
| `Validator` | `@meng-xi/vite-plugin/common` | 流畅 API 配置验证器 |
|
|
683
|
+
链式配置验证器，用于校验插件配置参数。
|
|
522
684
|
|
|
523
|
-
|
|
685
|
+
```typescript
|
|
686
|
+
import { Validator } from '@meng-xi/vite-plugin/common/validation'
|
|
524
687
|
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
| fs | `@meng-xi/vite-plugin/common/fs` | 文件复制、目录遍历、并发控制 |
|
|
529
|
-
| html | `@meng-xi/vite-plugin/common/html` | HTML 注入（injectBeforeTag, injectHeadAndBody 等） |
|
|
530
|
-
| object | `@meng-xi/vite-plugin/common/object` | 深度合并对象 |
|
|
531
|
-
| script | `@meng-xi/vite-plugin/common/script` | 回调包装、script 标签检测、标识符验证 |
|
|
532
|
-
| validation | `@meng-xi/vite-plugin/common/validation` | 全局名校验、XSS 防护、枚举验证等 |
|
|
688
|
+
const validator = new Validator(myOptions)
|
|
689
|
+
validator.field('port').number().minValue(1).maxValue(65535).field('host').string().notEmpty().field('mode').enum(['development', 'production']).validate()
|
|
690
|
+
```
|
|
533
691
|
|
|
534
692
|
---
|
|
535
693
|
|
|
536
|
-
##
|
|
694
|
+
## Common 工具模块
|
|
695
|
+
|
|
696
|
+
内置通用工具函数库，按功能模块组织，支持子路径按需导入。
|
|
537
697
|
|
|
538
|
-
|
|
698
|
+
### 导入方式
|
|
539
699
|
|
|
540
700
|
```typescript
|
|
541
|
-
|
|
701
|
+
// 导入所有工具
|
|
702
|
+
import { formatFileSize, scanDirectory } from '@meng-xi/vite-plugin/common'
|
|
703
|
+
|
|
704
|
+
// 按模块导入
|
|
705
|
+
import { formatFileSize } from '@meng-xi/vite-plugin/common/format'
|
|
706
|
+
import { scanDirectory, writeJsonReport } from '@meng-xi/vite-plugin/common/fs'
|
|
707
|
+
import { calculateGzipSize } from '@meng-xi/vite-plugin/common/compress'
|
|
708
|
+
import { isNodeModule } from '@meng-xi/vite-plugin/common/path'
|
|
709
|
+
```
|
|
542
710
|
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
711
|
+
### 模块列表
|
|
712
|
+
|
|
713
|
+
| 子路径 | 描述 |
|
|
714
|
+
| ---------------------------------------- | ------------- |
|
|
715
|
+
| `@meng-xi/vite-plugin/common/compress` | 压缩算法工具 |
|
|
716
|
+
| `@meng-xi/vite-plugin/common/format` | 格式化工具 |
|
|
717
|
+
| `@meng-xi/vite-plugin/common/fs` | 文件系统工具 |
|
|
718
|
+
| `@meng-xi/vite-plugin/common/html` | HTML 注入工具 |
|
|
719
|
+
| `@meng-xi/vite-plugin/common/object` | 对象操作工具 |
|
|
720
|
+
| `@meng-xi/vite-plugin/common/path` | 路径处理工具 |
|
|
721
|
+
| `@meng-xi/vite-plugin/common/script` | 脚本生成工具 |
|
|
722
|
+
| `@meng-xi/vite-plugin/common/validation` | 参数验证工具 |
|
|
723
|
+
|
|
724
|
+
### compress — 压缩算法
|
|
725
|
+
|
|
726
|
+
| 函数 | 描述 |
|
|
727
|
+
| ------------------- | -------------------------------------- |
|
|
728
|
+
| `calculateGzipSize` | 计算给定数据的 gzip 压缩后大小（字节） |
|
|
729
|
+
|
|
730
|
+
```typescript
|
|
731
|
+
import { calculateGzipSize } from '@meng-xi/vite-plugin/common/compress'
|
|
732
|
+
|
|
733
|
+
const size = await calculateGzipSize(Buffer.from('hello world'))
|
|
734
|
+
```
|
|
735
|
+
|
|
736
|
+
### format — 格式化
|
|
737
|
+
|
|
738
|
+
| 函数 | 描述 |
|
|
739
|
+
| --------------------- | ---------------------------------------- |
|
|
740
|
+
| `formatFileSize` | 将字节数格式化为人类可读的文件大小字符串 |
|
|
741
|
+
| `getExtension` | 获取文件扩展名（小写） |
|
|
742
|
+
| `formatDate` | 格式化日期 |
|
|
743
|
+
| `parseTemplate` | 解析模板字符串，替换占位符 |
|
|
744
|
+
| `toCamelCase` | 字符串转驼峰命名 |
|
|
745
|
+
| `toPascalCase` | 字符串转帕斯卡命名 |
|
|
746
|
+
| `padNumber` | 数字补零格式化 |
|
|
747
|
+
| `generateRandomHash` | 生成随机哈希字符串 |
|
|
748
|
+
| `getDateFormatParams` | 获取日期格式化参数 |
|
|
749
|
+
| `stripJsonComments` | 移除 JSON 字符串中的注释 |
|
|
750
|
+
| `escapeHtmlAttr` | 转义 HTML 属性值中的特殊字符 |
|
|
751
|
+
|
|
752
|
+
```typescript
|
|
753
|
+
import { formatFileSize, formatDate, toCamelCase } from '@meng-xi/vite-plugin/common/format'
|
|
754
|
+
|
|
755
|
+
formatFileSize(2461726) // '2.35MB'
|
|
756
|
+
formatDate(new Date(), '{YYYY}-{MM}-{DD}') // '2026-05-31'
|
|
757
|
+
toCamelCase('pages/user/profile') // 'pagesUserProfile'
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
### fs — 文件系统
|
|
761
|
+
|
|
762
|
+
| 函数 | 描述 |
|
|
763
|
+
| -------------------- | -------------------------- |
|
|
764
|
+
| `scanDirectory` | 递归扫描目录，收集文件信息 |
|
|
765
|
+
| `writeJsonReport` | 将数据写入 JSON 文件 |
|
|
766
|
+
| `writeFileContent` | 写入文件内容 |
|
|
767
|
+
| `readFileContent` | 读取文件内容 |
|
|
768
|
+
| `fileExists` | 检查文件是否存在 |
|
|
769
|
+
| `checkSourceExists` | 检查源文件是否存在 |
|
|
770
|
+
| `ensureTargetDir` | 创建目标目录 |
|
|
771
|
+
| `copySourceToTarget` | 执行文件复制操作 |
|
|
772
|
+
| `runWithConcurrency` | 带并发限制的批量执行 |
|
|
773
|
+
|
|
774
|
+
```typescript
|
|
775
|
+
import { scanDirectory, writeJsonReport } from '@meng-xi/vite-plugin/common/fs'
|
|
776
|
+
|
|
777
|
+
const files = await scanDirectory('dist', {
|
|
778
|
+
includeExtensions: ['.js', '.css'],
|
|
779
|
+
excludePatterns: ['node_modules'],
|
|
780
|
+
filter: (filePath, ext, size) => size > 1024
|
|
781
|
+
})
|
|
782
|
+
|
|
783
|
+
await writeJsonReport('dist/report.json', { timestamp: Date.now(), files })
|
|
553
784
|
```
|
|
554
785
|
|
|
555
|
-
|
|
786
|
+
### html — HTML 注入
|
|
556
787
|
|
|
788
|
+
| 函数 | 描述 |
|
|
789
|
+
| ----------------------------- | ------------------------------- |
|
|
790
|
+
| `injectBeforeTag` | 在指定闭合标签前注入代码 |
|
|
791
|
+
| `injectHtmlByPriority` | 按优先级向 HTML 中注入代码 |
|
|
792
|
+
| `injectBeforeTagWithFallback` | 带回退策略的 HTML 注入 |
|
|
793
|
+
| `injectHeadAndBody` | 双区域 HTML 注入（head + body） |
|
|
794
|
+
|
|
795
|
+
```typescript
|
|
796
|
+
import { injectBeforeTag, injectHeadAndBody } from '@meng-xi/vite-plugin/common/html'
|
|
797
|
+
|
|
798
|
+
const result = injectBeforeTag(html, '</head>', '<style>body{margin:0}</style>')
|
|
799
|
+
const dual = injectHeadAndBody(html, '<style>...</style>', '<script>...</script>')
|
|
557
800
|
```
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
@meng-xi/vite-plugin/
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
@meng-xi/vite-plugin/plugins/loading-manager
|
|
570
|
-
@meng-xi/vite-plugin/plugins/version-update-checker
|
|
571
|
-
@meng-xi/vite-plugin/common
|
|
572
|
-
@meng-xi/vite-plugin/common/format
|
|
573
|
-
@meng-xi/vite-plugin/common/fs
|
|
574
|
-
@meng-xi/vite-plugin/common/html
|
|
575
|
-
@meng-xi/vite-plugin/common/object
|
|
576
|
-
@meng-xi/vite-plugin/common/script
|
|
577
|
-
@meng-xi/vite-plugin/common/validation
|
|
801
|
+
|
|
802
|
+
### object — 对象操作
|
|
803
|
+
|
|
804
|
+
| 函数 | 描述 |
|
|
805
|
+
| ----------- | ------------ |
|
|
806
|
+
| `deepMerge` | 深度合并对象 |
|
|
807
|
+
|
|
808
|
+
```typescript
|
|
809
|
+
import { deepMerge } from '@meng-xi/vite-plugin/common/object'
|
|
810
|
+
|
|
811
|
+
deepMerge({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: 1, c: 2 } }
|
|
578
812
|
```
|
|
579
813
|
|
|
580
|
-
|
|
814
|
+
### path — 路径处理
|
|
581
815
|
|
|
582
|
-
|
|
816
|
+
| 函数 | 描述 |
|
|
817
|
+
| -------------- | --------------------------------- |
|
|
818
|
+
| `isNodeModule` | 判断模块 ID 是否来自 node_modules |
|
|
583
819
|
|
|
584
|
-
|
|
820
|
+
```typescript
|
|
821
|
+
import { isNodeModule } from '@meng-xi/vite-plugin/common/path'
|
|
822
|
+
|
|
823
|
+
isNodeModule('node_modules/lodash/index.js') // true
|
|
824
|
+
isNodeModule('src/utils/helper.ts') // false
|
|
825
|
+
```
|
|
826
|
+
|
|
827
|
+
### script — 脚本生成
|
|
828
|
+
|
|
829
|
+
| 函数 | 描述 |
|
|
830
|
+
| ------------------------ | ---------------------------------------- |
|
|
831
|
+
| `makeCallback` | 将回调函数体字符串包装为安全的函数表达式 |
|
|
832
|
+
| `containsScriptTag` | 检测字符串是否包含 `<script>` 标签 |
|
|
833
|
+
| `validateIdentifierName` | 验证字符串是否为合法的 JS 标识符 |
|
|
834
|
+
|
|
835
|
+
```typescript
|
|
836
|
+
import { makeCallback, validateIdentifierName } from '@meng-xi/vite-plugin/common/script'
|
|
585
837
|
|
|
586
|
-
|
|
838
|
+
makeCallback('console.log("done")')
|
|
839
|
+
// 'function() { try { console.log("done") } catch(e) { console.error("[callback] error:", e); } }'
|
|
587
840
|
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
841
|
+
validateIdentifierName('__APP_VERSION__') // 通过
|
|
842
|
+
```
|
|
843
|
+
|
|
844
|
+
### validation — 参数验证
|
|
845
|
+
|
|
846
|
+
| 函数 | 描述 |
|
|
847
|
+
| ---------------------------- | -------------------------- |
|
|
848
|
+
| `Validator` | 链式配置验证器类 |
|
|
849
|
+
| `validateGlobalName` | 验证全局变量名 |
|
|
850
|
+
| `validateNoScriptInTemplate` | 验证模板中不含 script 标签 |
|
|
851
|
+
| `validateCallbackFields` | 验证回调函数字段 |
|
|
852
|
+
| `validateNonNegativeNumber` | 验证非负数 |
|
|
853
|
+
| `validateNestedDuration` | 验证嵌套的时长配置 |
|
|
854
|
+
| `validateEnumValue` | 验证枚举值 |
|
|
855
|
+
|
|
856
|
+
```typescript
|
|
857
|
+
import { Validator } from '@meng-xi/vite-plugin/common/validation'
|
|
858
|
+
|
|
859
|
+
const validator = new Validator(options)
|
|
860
|
+
validator.field('port').number().minValue(1).maxValue(65535).validate()
|
|
861
|
+
```
|
|
862
|
+
|
|
863
|
+
---
|
|
864
|
+
|
|
865
|
+
## 子路径导出
|
|
866
|
+
|
|
867
|
+
| 子路径 | 描述 |
|
|
868
|
+
| ----------------------------------------------------- | ------------------------- |
|
|
869
|
+
| `@meng-xi/vite-plugin` | 主入口（所有插件+框架） |
|
|
870
|
+
| `@meng-xi/vite-plugin/factory` | 插件开发框架 |
|
|
871
|
+
| `@meng-xi/vite-plugin/logger` | 日志管理器 |
|
|
872
|
+
| `@meng-xi/vite-plugin/plugins` | 所有插件 |
|
|
873
|
+
| `@meng-xi/vite-plugin/common` | 所有工具函数 |
|
|
874
|
+
| `@meng-xi/vite-plugin/common/compress` | 压缩工具 |
|
|
875
|
+
| `@meng-xi/vite-plugin/common/format` | 格式化工具 |
|
|
876
|
+
| `@meng-xi/vite-plugin/common/fs` | 文件系统工具 |
|
|
877
|
+
| `@meng-xi/vite-plugin/common/html` | HTML 注入工具 |
|
|
878
|
+
| `@meng-xi/vite-plugin/common/object` | 对象操作工具 |
|
|
879
|
+
| `@meng-xi/vite-plugin/common/path` | 路径处理工具 |
|
|
880
|
+
| `@meng-xi/vite-plugin/common/script` | 脚本生成工具 |
|
|
881
|
+
| `@meng-xi/vite-plugin/common/validation` | 参数验证工具 |
|
|
882
|
+
| `@meng-xi/vite-plugin/plugins/build-progress` | buildProgress 插件 |
|
|
883
|
+
| `@meng-xi/vite-plugin/plugins/bundle-analyzer` | bundleAnalyzer 插件 |
|
|
884
|
+
| `@meng-xi/vite-plugin/plugins/compress-assets` | compressAssets 插件 |
|
|
885
|
+
| `@meng-xi/vite-plugin/plugins/copy-file` | copyFile 插件 |
|
|
886
|
+
| `@meng-xi/vite-plugin/plugins/favicon-manager` | faviconManager 插件 |
|
|
887
|
+
| `@meng-xi/vite-plugin/plugins/generate-router` | generateRouter 插件 |
|
|
888
|
+
| `@meng-xi/vite-plugin/plugins/generate-version` | generateVersion 插件 |
|
|
889
|
+
| `@meng-xi/vite-plugin/plugins/html-inject` | htmlInject 插件 |
|
|
890
|
+
| `@meng-xi/vite-plugin/plugins/loading-manager` | loadingManager 插件 |
|
|
891
|
+
| `@meng-xi/vite-plugin/plugins/version-update-checker` | versionUpdateChecker 插件 |
|
|
892
|
+
|
|
893
|
+
---
|
|
593
894
|
|
|
594
895
|
## License
|
|
595
896
|
|