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 冲突时告警;definePageprops 类型安全(实验性);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 仍然会采集。
迁移
- 移除
scrollBehavior; - 在
app.use(router)之前安装插件; - 在 layout 或每个页面组件里调用
useScrollRestoration(); - 按需改
capture/restore/key,需要自定义触发时写setupListeners。