Vue Router Cache Plugin

一个用于 Vue 3 和 Vue Router 4 的智能路由缓存插件，提供灵活的页面缓存管理功能。

✨ 特性

• 🚀 零依赖: 不依赖 Vuex，使用 Vue 3 原生响应式系统
• 📦 轻量级: 核心代码小于 5KB
• 🎯 智能缓存: 基于路由关系的智能缓存策略
• 🔧 灵活配置: 支持多种配置方式和自定义策略
• 💪 TypeScript: 完整的 TypeScript 支持
• 🎨 组合式API: 提供 useCacheRouter 组合函数
• 🔍 调试友好: 内置调试模式和状态可视化

📦 安装

npm install vue-router-cache-plugin
# 或
yarn add vue-router-cache-plugin
# 或
pnpm add vue-router-cache-plugin

🚀 快速开始

1. 基本用法（推荐）

import { createRouter, createWebHistory } from 'vue-router'
import { createRouterCachePlugin } from 'vue-router-cache-plugin'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    {
      path: '/products',
      name: 'ProductList',
      component: () => import('./views/ProductList.vue')
    },
    {
      path: '/products/:id',
      name: 'ProductDetail',
      component: () => import('./views/ProductDetail.vue')
    }
  ]
})

// 创建并安装缓存插件
const cachePlugin = createRouterCachePlugin({
  cacheMap: {
    'ProductList': ['ProductDetail'] // 从商品列表进入详情时缓存列表页
  },
  debug: true, // 开发模式下启用调试
  maxCacheSize: 10 // 最大缓存页面数
})

// 安装插件到路由实例
cachePlugin(router)

export default router

2. 在模板中使用

<template>
  <div id="app">
    <!-- 使用缓存路由视图 -->
    <CacheRouterView />
  </div>
</template>

<script setup>
import { CacheRouterView } from 'vue-router-cache-plugin'
</script>

3. 使用组合函数

<script setup>
import { useCacheRouter } from 'vue-router-cache-plugin'

const {
  cacheList,      // 当前缓存列表
  isCached,       // 当前页面是否被缓存
  addCache,       // 添加缓存
  removeCache,    // 移除缓存
  clearCache      // 清空缓存
} = useCacheRouter()

// 手动缓存当前页面
const handleCacheCurrentPage = () => {
  addCache()
}

// 清空所有缓存
const handleClearAll = () => {
  clearCache()
}
</script>

<template>
  <div>
    <p>当前页面缓存状态: {{ isCached ? '已缓存' : '未缓存' }}</p>
    <p>缓存列表: {{ cacheList.join(', ') }}</p>
    
    <button @click="handleCacheCurrentPage">缓存当前页面</button>
    <button @click="handleClearAll">清空所有缓存</button>
  </div>
</template>

📖 详细配置

插件选项

interface RouterCachePluginOptions {
  /** 缓存映射关系 */
  cacheMap?: Record<string, string[]>
  
  /** 是否开启调试模式 */
  debug?: boolean
  
  /** 最大缓存数量 */
  maxCacheSize?: number
  
  /** 自定义缓存策略 */
  customStrategy?: (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean
}

路由元信息配置

const routes = [
  {
    path: '/products',
    name: 'ProductList',
    component: ProductList,
    meta: {
      cache: true,                    // 启用缓存
      cacheTargets: ['ProductDetail'] // 缓存目标路由
    }
  },
  {
    path: '/settings',
    name: 'Settings',
    component: Settings,
    meta: {
      noCache: true // 禁用缓存
    }
  }
]

组件配置

<template>
  <!-- 基本用法 -->
  <CacheRouterView />
  
  <!-- 高级配置 -->
  <CacheRouterView 
    :max="5"
    :include="['CustomPage']"
    :exclude="['NoCache']"
  />
  
  <!-- 简化版本 -->
  <SimpleCacheRouterView />
</template>

🎯 使用场景

1. 列表-详情页缓存

// 配置：从列表进入详情时缓存列表页
cacheMap: {
  'ProductList': ['ProductDetail'],
  'UserList': ['UserDetail', 'UserEdit']
}

2. 表单页面缓存

// 配置：编辑页面返回时保持表单状态
cacheMap: {
  'UserEdit': ['UserProfile']
}

3. 自定义缓存策略

createRouterCachePlugin({
  customStrategy: (to, from) => {
    // 自定义逻辑：只有在特定条件下才缓存
    return from.query.cache === 'true'
  }
})

🔧 API 参考

useCacheRouter()

const {
  // 状态
  cacheList,          // 当前缓存列表（只读）
  isCached,           // 当前页面是否被缓存
  cacheStats,         // 缓存统计信息
  
  // 基本操作
  addCache,           // 添加缓存
  removeCache,        // 移除缓存
  clearCache,         // 清空所有缓存
  hasCache,           // 检查是否缓存
  
  // 便捷操作
  cacheCurrentPage,   // 缓存当前页面
  removeCacheCurrentPage, // 移除当前页面缓存
  
  // 批量操作
  batchAddCache,      // 批量添加缓存
  batchRemoveCache,   // 批量移除缓存
  
  // 高级用法
  getCacheStore       // 获取缓存存储实例
} = useCacheRouter()

Router 扩展方法

// 插件会为 router 实例添加以下方法
router.addCache('PageName')     // 添加缓存
router.removeCache('PageName')  // 移除缓存
router.clearCache()             // 清空缓存
router.getCacheList()           // 获取缓存列表

🐛 调试

启用调试模式：

createRouterCachePlugin({
  debug: true
})

调试模式下会：

• 在控制台输出详细的缓存操作日志
• 将缓存存储实例暴露到 window.__ROUTER_CACHE_STORE__
• 提供缓存统计信息

🔄 迁移指南

从 Vue 2 版本迁移

// Vue 2 版本
Vue.use(DynamicRouterView, { router, cacheMap })

// Vue 3 版本（正确方式）
const cachePlugin = createRouterCachePlugin({ cacheMap })
cachePlugin(router)

// 在 main.js 中
import { createApp } from 'vue'
import router from './router'

const app = createApp(App)
app.use(router) // 这里使用 app.use()
app.mount('#app')

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📚 更多示例

查看 examples 目录获取更多使用示例。