编程 Vue Router 5.5.0 滚动恢复:位置改存 sessionStorage,默认 key 不带 query 会漏掉搜索翻页

2026-11-19 21:31:34

Vue Router 5.5.0 滚动恢复:位置改存 sessionStorage,默认 key 不带 query 会漏掉搜索翻页

Vue Router v5.5.0 于 2026-11-10 发布,5.5.1 在 2026-11-13 跟进。这一版滚动相关的改动集中在两处:位置不再写进 history.state,改存 sessionStorage;采集触发条件变成插件选项,可以替换。

发布说明里的条目:

  • scroll:滚动位置存入 sessionStorage 而非 history.state;sessionStorage 写入失败时保留在内存;忽略 sessionStorage 中的非法位置。
  • scroll-restoration:capture 触发条件可配置;实验性支持自定义 capture 监听器;导出默认的 scroll capture listener setup;scrollRestoration 为 manual 时,pagehide 不再调 replaceState(#2631)。
  • matcher:避免 .* 可重复参数引起的指数回溯(#2819);query 与 params 冲突时告警;definePage props 类型安全(实验性);router-view 的 useRoute 返回 route prop;为待处理的异步页面保留 key;原生 hash 链接后恢复。

项目信息:

  • 仓库:https://github.com/vuejs/router
  • 文档:https://router.vuejs.org/experimental/scroll-restoration
  • 版本:https://github.com/vuejs/router/releases

安装顺序与存储

文档里的 Scroll Restoration 是 experimental,用来替代已弃用的 scrollBehavior。安装必须在 app.use(router) 之前:

app.use(ScrollRestoration, {
  router,
  capture: SCROLL_RESTORATION_CAPTURE_DEFAULT,
  restore: SCROLL_RESTORATION_RESTORE_DEFAULT,
  key: to => to.path + to.hash,
  storageKeyPrefix: 'vue:scroll:',
})

位置存在带前缀的 sessionStorage 里,同一标签页刷新后仍在;sessionStorage 不可用时退回内存;读到的非法值直接忽略。插件本身不采集也不恢复,必须有组件调用 useScrollRestoration()。

安装插件会把 history.scrollRestoration 设为 manual。改成 auto 会与滚动恢复冲突,锚点场景尤其明显;非 manual 时默认 capture 什么都不存。

默认 capture / restore 与 key

默认行为:离开页面时记录 window 位置;有值就恢复;没有值就滚到 hash 元素;再没有就回顶。

默认 key 是 to.path + to.hash。所以 /search?q=shoes → /search?q=shoes&p=2 这种只改 query 的翻页不会回顶,位置会沿用上一页。要按页码区分:

useScrollRestoration({
  key: to => to.path + `?p=${to.query.p ?? ''}` + to.hash,
})

也可以直接用 to.fullPath,或返回一个固定字符串。

useScrollRestoration 与 onRouteRendered

useScrollRestoration() 内部用 onRouteRendered():在最接近的 RouterView 渲染新路由后恢复,时机在 mount/update 之后、Suspense resolve 之后、out-in Transition 进入之后。不要在根 App.vue 或 RouterView 之外调用——那里的 onRouteRendered() 跑在 router.afterEach() 里,早于渲染,会恢复成旧页面。layout 调一次即可覆盖子页面;页面里再调一次且 key 相同,会替换 layout 的设置。

采集触发与 setupListeners

默认采集时机:每次成功导航后、pagehide、document hidden。

setupListeners 是 app.use(ScrollRestoration, {...}) 的插件选项,用来替换全部默认触发(含导航),签名是 (capture, signal, router):

app.use(ScrollRestoration, {
  router,
  capture: SCROLL_RESTORATION_CAPTURE_DEFAULT,
  restore: SCROLL_RESTORATION_RESTORE_DEFAULT,
  setupListeners(capture, signal, router) {
    window.addEventListener('scroll', () => capture(), { signal })
  },
})

传 signal 是为了卸载时统一移除;包成 () => capture() 是避免事件对象被当成 route 传入。

保留默认触发再加自己的,在同一个 setupListeners 里调用 SCROLL_RESTORATION_SETUP_LISTENERS_DEFAULT(capture, signal, router):

setupListeners(capture, signal, router) {
  SCROLL_RESTORATION_SETUP_LISTENERS_DEFAULT(capture, signal, router)
  window.addEventListener('scroll', () => capture(), { signal })
}

全部关掉用 setupListeners: () => {}。

scroll 事件不可取消,加 passive 没有收益;每次 capture 会同步写 sessionStorage,高频触发要自己节流。

多容器与 manual

多容器场景下,capture 返回 { default: {...}, sidebar: {...} },restore 分别恢复;两者必须同步,可以用 scrollIntoView;偏移用 CSS scroll-margin;capture 返回 null 会删除对应条目。

manual: true 用于动画或虚拟列表,之后自行调用 scroll();默认 setupListeners 仍然会采集。

迁移

  1. 移除 scrollBehavior;
  2. 在 app.use(router) 之前安装插件;
  3. 在 layout 或每个页面组件里调用 useScrollRestoration();
  4. 按需改 capture / restore / key,需要自定义触发时写 setupListeners。
复制全文 生成海报 Vue Router 前端 滚动恢复

推荐文章

程序员茄子在线接单