vite-plugin-preloader 1.0.1 → 1.1.0

package/README.md

@@ -4,12 +4,13 @@
 
 ## ✨ 特性
 
-- 🎯 **一行配置** - 在 `vite.config.js` 中配置即可
-- ⚡ **零运行时开销** - 构建时生成，运行时高效
-- 🎨 **自动注入** - 无需手动调用，全自动工作
-- 🛠️ **开发友好** - 提供调试工具和状态显示
+- 🎯 **一行配置** - 在 `vite.config.js` 中配置即可，无需修改任何业务代码
+- ⚡ **零运行时开销** - 构建时生成，运行时高效执行
+- 🎨 **自动注入** - 无需手动调用，插件自动将预加载脚本注入 HTML
+- 🛠️ **开发友好** - 智能默认配置 + 丰富的调试工具
 - 📦 **类型安全** - 完整的 TypeScript 支持
 - 🔥 **热更新支持** - 配置变更时自动更新
+- 🎭 **状态可视化** - 优雅的加载状态显示，支持多种位置
 
 ## 📦 安装
 
@@ -23,9 +24,9 @@ pnpm add vite-plugin-preloader
 bun add vite-plugin-preloader
 ```
 
-## 🚀 使用
+## 🚀 快速开始
 
-### 基础配置
+### 极简配置（推荐）
 
 ```js
 // vite.config.js
@@ -38,178 +39,252 @@ export default defineConfig({
     vue(),
     preloader({
       routes: [
-        { 
-          path: '/calendar', 
-          reason: '日历组件包含大型库',
-          priority: 1 
-        },
-        { 
-          path: '/charts', 
-          component: '@/views/charts/index.vue',
-          reason: '图表页面较重', 
-          priority: 1 
-        }
+        '/dashboard',    // 字符串配置，组件路径自动推断
+        '/calendar',     // 推断为: @/views/calendar/index.vue
+        '/charts',       // 推断为: @/views/charts/index.vue
       ]
     })
   ]
 })
 ```
 
-就这样！无需其他任何代码，插件会自动：
-- 🎯 生成预加载逻辑
-- 📦 注入到应用中
+**就这样！** 插件会自动：
+- 🎯 推断组件路径
+- 📦 注入预加载脚本
 - 🎨 显示加载状态
 - 🛠️ 提供调试工具
+- ⚙️ 应用智能默认配置
 
 ### 完整配置示例
 
 ```js
 preloader({
   routes: [
-    // 🔥 高优先级 - 核心页面
-    { 
-      path: '/dashboard', 
-      component: '@/views/dashboard/index.vue',
-      reason: '主仪表盘，用户访问频率最高',
-      priority: 1 
-    },
+    // 🔥 字符串配置 - 简单直接
+    '/dashboard',
+    '/user-profile',
     
-    // ⚡ 中优先级 - 常用页面
+    // 🎯 对象配置 - 更多控制
     { 
       path: '/calendar', 
+      component: '@/views/calendar/CalendarView.vue', // 自定义组件路径
       reason: '日历组件包含 @fullcalendar 全家桶(~500KB)',
+      priority: 1  // 高优先级，优先加载
+    },
+    { 
+      path: '/charts', 
+      reason: '图表页面包含 echarts、@antv/x6 等重型库',
       priority: 2 
     },
-    
-    // 📊 低优先级 - 重型工具页面
     { 
       path: '/reports', 
-      component: '@/views/reports/index.vue',
-      reason: '报表页面包含 echarts + d3 图表库(~800KB)',
+      reason: '报表页面包含复杂的数据处理逻辑',
       priority: 3 
     }
   ],
-  delay: 2000,                    // 延迟时间
-  showStatus: true,               // 显示状态
-  statusPosition: 'bottom-right', // 状态位置
-  debug: true                     // 开发调试
+  
+  // 🚀 以下所有配置都有智能默认值，可选配置
+  delay: 2000,                    // 页面加载后延迟 2 秒开始预加载
+  showStatus: true,               // 显示 "🔄 正在优化页面..." 状态
+  statusPosition: 'bottom-right', // 状态显示位置
+  debug: true                     // 强制开启调试（默认开发环境自动开启）
 })
 ```
 
 ## 🎯 配置选项
 
+### 插件选项
+
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `routes` | `PreloadRoute[]` | `[]` | 预加载路由配置 |
-| `delay` | `number` | `2000` | 延迟时间(ms) |
-| `showStatus` | `boolean` | `true` | 显示状态 |
-| `statusPosition` | `string` | `'bottom-right'` | 状态位置 |
-| `debug` | `boolean` | `false` | 开发调试 |
+| `routes` | `(string \| PreloadRoute)[]` | `[]` | **必填** 预加载路由配置 |
+| `delay` | `number` | `2000` | 延迟时间(ms)，避免影响首屏加载 |
+| `showStatus` | `boolean` | `true` | 显示加载状态指示器 |
+| `statusPosition` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` | 状态指示器位置 |
+| `debug` | `boolean` | `开发环境: true`<br>`生产环境: false` | 调试模式，控制台输出详细日志 |
 
 ### PreloadRoute 配置
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `path` | `string` | ✅ | 路由路径 |
-| `component` | `string` | ❌ | 组件路径（不填自动推断） |
-| `reason` | `string` | ❌ | 预加载原因说明 |
-| `priority` | `number` | ❌ | 优先级 1-5（数字越小越先加载） |
+| `path` | `string` | ✅ | 路由路径，如 `/dashboard` |
+| `component` | `string` | ❌ | 组件路径，不填则自动推断 |
+| `reason` | `string` | ❌ | 预加载原因说明，便于调试和维护 |
+| `priority` | `number` | ❌ | 优先级 1-5（数字越小越先加载），默认 2 |
 
 ## 🛠️ 开发调试
 
-开发环境下，浏览器控制台可用：
+开发环境下，插件自动在浏览器控制台提供调试工具：
 
 ```js
-// 查看预加载统计
+// 查看预加载统计信息
 window.preloaderDebug.stats()
+// 返回: { total: 3, completed: 2, failed: 0, startTime: 1234567890, ... }
 
-// 检查指定路由状态  
+// 检查指定路由是否已预加载  
 window.preloaderDebug.check('/calendar')
+// 返回: true
 
-// 重新开始预加载
+// 手动重新开始预加载（用于测试）
 window.preloaderDebug.restart()
 
-// 显示帮助信息
+// 显示所有可用的调试命令
 window.preloaderDebug.help()
 ```
 
 ## 📊 控制台输出示例
 
+### 插件启动日志
+```
+🚀 [预加载插件] 已启用，配置了 3 个路由
+📋 [预加载插件] 路由列表: ["/dashboard", "/calendar", "/charts"]
+⚙️ [预加载插件] 配置选项: { delay: 2000, showStatus: true, statusPosition: "bottom-right", debug: true }
+🎨 [预加载插件] 注入预加载脚本到 HTML
+```
+
+### 预加载执行日志
 ```
-🚀 预加载插件已启用，配置了 3 个路由
 🚀 [预加载] 开始预加载 3 个页面
-✅ [预加载] /calendar (234ms) - 日历组件包含 @fullcalendar 全家桶
-✅ [预加载] /charts (456ms) - 图表页面包含 echarts、@antv/x6
-✅ [预加载] /reports (678ms) - 报表页面包含 echarts + d3 图表库
+✅ [预加载] /dashboard (156ms) - 自动推断的预加载页面
+✅ [预加载] /calendar (234ms) - 日历组件包含 @fullcalendar 全家桶(~500KB)
+✅ [预加载] /charts (456ms) - 图表页面包含 echarts、@antv/x6 等重型库
 🎉 [预加载] 完成! 耗时 1234ms
+🛠️ 预加载调试工具: window.preloaderDebug
 ```
 
-## 🎨 状态显示
+## 🎨 状态显示效果
 
-插件会在页面右下角显示预加载状态：
+插件会在页面显示优雅的加载状态：
 
 ```
 🔄 正在优化页面... 2/3
 ```
 
-状态位置可通过 `statusPosition` 配置：
-- `'top-left'` - 左上角
-- `'top-right'` - 右上角  
-- `'bottom-left'` - 左下角
-- `'bottom-right'` - 右下角（默认）
+- **位置可配置**：四个角落任选
+- **自动隐藏**：预加载完成后淡出消失
+- **不干扰用户**：`pointer-events: none`，不阻挡交互
 
 ## 🔧 最佳实践
 
-### 1. 优先级设置建议
+### 1. 路由配置策略
 
 ```js
-// 优先级 1: 核心业务页面（高频访问 + 大体积）
-{ path: '/dashboard', priority: 1 }
-
-// 优先级 2: 常用功能页面（中频访问 + 中体积）
-{ path: '/calendar', priority: 2 }
-
-// 优先级 3: 专业工具页面（低频访问 + 大体积）
-{ path: '/reports', priority: 3 }
+routes: [
+  // 🔥 核心页面 - 用户必访，优先级最高
+  { path: '/dashboard', priority: 1, reason: '用户首页，访问频率最高' },
+  
+  // ⚡ 常用页面 - 功能页面，中等优先级
+  { path: '/calendar', priority: 2, reason: '日历功能，包含大型日期库' },
+  { path: '/contacts', priority: 2, reason: '联系人管理，数据量大' },
+  
+  // 📊 专业工具 - 低频但重型，最后加载
+  { path: '/reports', priority: 3, reason: '报表页面，包含复杂图表库' },
+  { path: '/admin', priority: 3, reason: '管理后台，权限要求高' }
+]
 ```
 
-### 2. 组件路径自动推断
+### 2. 智能路径推断
 
-如果不指定 `component`，插件会自动推断：
+插件自动将路由路径转换为组件路径：
 
 ```js
-{ path: '/user-profile' }
-// 自动推断为: @/views/user-profile/index.vue
-
-{ path: '/admin/users' }  
-// 自动推断为: @/views/admin-users/index.vue
+// 路径推断规则
+'/dashboard'           → '@/views/dashboard/index.vue'
+'/user-profile'        → '@/views/user-profile/index.vue'
+'/admin/users'         → '@/views/admin/users/index.vue'
+'/demo/13-calendar'    → '@/views/demo/13-calendar/index.vue'
 ```
 
-### 3. 预加载原因说明
-
-建议在 `reason` 中说明预加载的具体原因：
+### 3. 性能优化建议
 
 ```js
 {
+  // ✅ 推荐：给出明确的预加载原因
   path: '/calendar',
-  reason: '日历组件包含 @fullcalendar 全家桶(~500KB)',
+  reason: '日历组件包含 @fullcalendar(~400KB) + moment.js(~60KB)',
   priority: 2
+},
+
+{
+  // ✅ 推荐：重型页面单独配置优先级
+  path: '/data-visualization', 
+  reason: '数据可视化包含 d3.js + echarts + three.js (~1.2MB)',
+  priority: 3  // 低优先级，避免影响关键页面
 }
 ```
 
+### 4. 开发环境优化
+
+```js
+// vite.config.js
+preloader({
+  routes: [/* ... */],
+  
+  // 开发环境配置
+  ...(process.env.NODE_ENV === 'development' ? {
+    debug: true,        // 开发环境显示详细日志
+    delay: 1000,        // 开发环境快速启动
+    showStatus: true    // 显示状态便于调试
+  } : {
+    debug: false,       // 生产环境静默运行
+    delay: 3000,        // 生产环境延迟更久，确保首屏稳定
+    showStatus: false   // 生产环境不显示状态
+  })
+})
+```
+
 ## 🚀 工作原理
 
-1. **构建时分析** - 插件在构建时解析配置
-2. **代码生成** - 自动生成预加载逻辑代码
-3. **虚拟模块** - 创建 `virtual:preloader` 模块
-4. **自动注入** - 将预加载代码注入到应用中
-5. **智能调度** - 按优先级串行预加载，避免阻塞
+### 构建时
+1. **配置解析** - 解析用户配置，应用智能默认值
+2. **路径推断** - 自动推断未指定的组件路径
+3. **代码生成** - 生成优化的预加载脚本
+4. **HTML注入** - 将脚本直接注入到 HTML `<head>` 中
+
+### 运行时
+1. **DOM就绪检测** - 等待页面 DOM 加载完成
+2. **延迟启动** - 根据配置延迟指定时间后启动
+3. **优先级排序** - 按 priority 值从小到大排序
+4. **串行加载** - 顺序预加载，避免并发阻塞
+5. **状态反馈** - 实时更新加载状态和统计信息
+
+## 🎯 适用场景
+
+- ✅ **Vue SPA 应用** - 单页应用路由预加载
+- ✅ **后台管理系统** - 管理页面通常较重，预加载效果明显
+- ✅ **数据可视化应用** - 图表库体积大，预加载能显著提升体验
+- ✅ **工具型应用** - 功能页面复杂，用户操作流程相对固定
+
+## ❓ 常见问题
+
+### Q: 预加载会影响首屏性能吗？
+A: 不会。插件默认延迟 2 秒启动，确保首屏渲染完成后才开始预加载。
+
+### Q: 如何判断哪些页面需要预加载？
+A: 建议预加载：1) 用户高频访问的页面 2) 包含大型第三方库的页面 3) 数据处理复杂的页面。
+
+### Q: 开发环境下看不到预加载效果？
+A: 开发环境下模块已经在内存中，预加载效果不明显。可以通过控制台日志确认插件正常工作。
+
+### Q: 可以配置生产环境不预加载吗？
+A: 可以。在配置中添加环境判断即可：
+```js
+preloader({
+  routes: process.env.NODE_ENV === 'production' ? [] : ['/dashboard', '/calendar']
+})
+```
 
 ## 🤝 贡献
 
 欢迎提交 Issue 和 Pull Request！
 
-## 📄 License
+1. Fork 本仓库
+2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交你的修改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启一个 Pull Request
+
+## 📄 许可证
 
 MIT © ChenYu
 

package/dist/index.d.mts

@@ -1,33 +1,17 @@
 import { Plugin } from 'vite';
 
 interface PreloadRoute {
-    /** 路由路径 */
     path: string;
-    /** 组件导入路径，不填则自动推断 */
     component?: string;
-    /** 预加载原因说明 */
     reason?: string;
-    /** 优先级 1-5，数字越小优先级越高 */
     priority?: number;
 }
 interface PreloaderOptions {
-    /** 预加载路由配置 - 支持字符串数组或对象数组 */
     routes: (string | PreloadRoute)[];
-    /** 延迟时间（毫秒），默认 2000 */
     delay?: number;
-    /** 是否显示预加载状态，默认 true */
     showStatus?: boolean;
-    /** 状态显示位置，默认 'bottom-right' */
     statusPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    /** 是否启用开发时调试，默认 false */
     debug?: boolean;
-    /** 自动检测大文件并预加载（未来功能） */
-    autoDetect?: {
-        /** 最小文件大小阈值 */
-        minSize?: string;
-        /** 排除的路径模式 */
-        exclude?: string[];
-    };
 }
 
 declare function preloaderPlugin(options: PreloaderOptions): Plugin;

package/dist/index.d.ts

@@ -1,33 +1,17 @@
 import { Plugin } from 'vite';
 
 interface PreloadRoute {
-    /** 路由路径 */
     path: string;
-    /** 组件导入路径，不填则自动推断 */
     component?: string;
-    /** 预加载原因说明 */
     reason?: string;
-    /** 优先级 1-5，数字越小优先级越高 */
     priority?: number;
 }
 interface PreloaderOptions {
-    /** 预加载路由配置 - 支持字符串数组或对象数组 */
     routes: (string | PreloadRoute)[];
-    /** 延迟时间（毫秒），默认 2000 */
     delay?: number;
-    /** 是否显示预加载状态，默认 true */
     showStatus?: boolean;
-    /** 状态显示位置，默认 'bottom-right' */
     statusPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    /** 是否启用开发时调试，默认 false */
     debug?: boolean;
-    /** 自动检测大文件并预加载（未来功能） */
-    autoDetect?: {
-        /** 最小文件大小阈值 */
-        minSize?: string;
-        /** 排除的路径模式 */
-        exclude?: string[];
-    };
 }
 
 declare function preloaderPlugin(options: PreloaderOptions): Plugin;