[特殊字符] Vue Router 4 插件集合 | 用最小成本扩展路由能力的神器

@vue-spark/router-plugins

轻量级插件集合，通过插件形式扩展 Vue Router 4 的核心功能，解决页面缓存、导航动画、滚动位置保存等高频痛点，开发体验更丝滑！

🌟 为什么你需要这个插件？

在 Vue 项目中，你是否遇到过这些问题？

使用 <KeepAlive> 缓存页面后，如何在浏览器前进/后退时传递和恢复状态数据？
想实现移动端风格的导航动画（如滑动切换页面），但代码复杂度太高？
长页面或列表页需要自动保存滚动位置，但原生 scrollBehavior 功能有限？
需要检测导航状态（如加载提示）或记录上一个路由信息？

@vue-spark/router-plugins 为你提供开箱即用的解决方案！

🛠 核心插件功能一览

1️⃣ HistoryStatePlugin：跨页面数据传递

场景：在缓存页面中，点击按钮跳转到详情页后返回，如何刷新列表数据？
解决方案：

通过 router.historyState.setDeferred() 和 router.historyState.take() 实现导航时的状态传递。
支持内存缓存和延迟设置，兼容浏览器历史栈。

代码示例：

// 列表页：监听返回时是否需要刷新
onActivated(() => {
  const shouldRefresh = router.historyState.take('refreshList')
  if (shouldRefresh) fetchList()
})

// 详情页：返回时设置刷新标志
router.setDeferred({ refreshList: true })
router.back()

2️⃣ NavigationDirectionPlugin：导航动画控制

场景：实现类似小程序的页面切换动画（前进/后退/刷新）。
解决方案：

监听导航方向（forward/backward/unchanged），动态绑定 Transition 动画名称。
结合 KeepAlive 实现页面缓存与动画联动。

代码示例：

router.navigationDirection.listen((direction, to, from) => {
  switch (direction) {
    case 'forward': 
      transitionName.value = 'page-in'
      break
    case 'backward': 
      transitionName.value = 'page-out'
      break
    default:
      transitionName.value = undefined
  }
})

3️⃣ ScrollerPlugin：滚动位置自动还原

场景：长页面滚动后返回时，自动定位到上次浏览的位置。
解决方案：

自动保存和恢复 window、body 或自定义元素的滚动位置。
支持仅在导航后退时还原（适合移动端）。

代码示例：

ScrollerPlugin(router, {
  selectors: { 
    window: true, 
    '.scrollable': true 
  },
  scrollOnlyBackward: true // 仅后退时还原
})

4️⃣ IsNavigatingPlugin：导航状态检测

场景：导航时显示加载提示，动画结束后隐藏。
解决方案：

通过 router.isNavigating.value 实时检测导航状态。

代码示例：

<div :class="{ 'is-navigating': $router.isNavigating.value }">
  <RouterView />
</div>

5️⃣ PreviousRoutePlugin：记录上一个路由

场景：从根路由返回时跳转到指定页面（如 TabBar）。
解决方案：

通过 router.previousRoute.value 获取上一个路由信息。

代码示例：

const originalBack = router.back
router.back = () => {
  if (router.previousRoute.value?.fullPath === '/') {
    router.replace('/tab-bar')
    return
  }
  originalBack()
}

🚀 快速上手

安装

npm i @vue-spark/router-plugins

全局注册

import RouterPlugins from '@vue-spark/router-plugins'
import { createRouter } from 'vue-router'

const router = createRouter({...})
RouterPlugins(router, {
  // 插件配置项
})

单个插件注册

import ScrollerPlugin from '@vue-spark/router-plugins/plugins/scroller'
ScrollerPlugin(router, {
  // 插件配置项
})

🌐 在线示例 & 文档

📌 适用场景

移动端类 App：导航动画、滚动位置还原。
多页缓存场景：跨页面数据传递、页面状态持久化。
复杂路由逻辑：导航方向控制、自定义返回行为。

✅ 总结

@vue-spark/router-plugins 通过插件化设计，以最小成本扩展了 Vue Router 的能力，解决了实际开发中的高频痛点。无论是需要精细控制导航动画，还是实现跨页面状态管理，它都能显著提升开发效率和用户体验。

立即尝试，让你的 Vue 项目更轻量、更强大！ 🚀