前端路由【免费下载链接】vue-router The official router for Vue 2项目地址https://gitcode.com/gh_mirrors/vu/vue-router点击查看免费下载客户端路由SPA有一个与原生多页应用不同的体验问题切换路由时页面默认停留在当前滚动位置这往往不符合用户预期。官方路由库vue-router通过scrollBehavior选项让你可以像真实页面刷新那样控制每次导航后的滚动位置——既支持回到顶部也支持按历史记录恢复滚动位置甚至可以完全自定义滚动策略。读完本文你将掌握scrollBehavior的完整配置语法、返回值协议、与路由 meta 字段的配合方式以及它背后在vue-router源码中的完整执行链路。前置条件仅在 HTML5 History 模式下生效scrollBehavior是 vue-router 专为 HTML5 History 模式设计的能力。这一点在原文档中有明确提示该功能只在 history 模式下工作因为它依赖浏览器原生的history.pushStateAPIsrc/util/push-state.js 中的supportsPushState检测。const router new VueRouter({ mode: history, // 必须显式开启 history 模式 routes: [...], scrollBehavior (to, from, savedPosition) { // 返回期望的滚动位置 } })如果你的应用使用默认的 hash 模式mode: hash或 abstract 模式scrollBehavior不会生效。从源码看只有 HTML5History 在setupListeners中判断supportsPushState router.options.scrollBehavior后才会调用setupScroll()注册滚动相关逻辑src/history/html5.js。scrollBehavior的参数to、from 与 savedPositionscrollBehavior接收三个参数参数类型说明toRoute 对象导航目标路由包含path、hash、query、matched、meta等fromRoute 对象当前导航来源路由savedPosition{ x, y }或null仅当本次导航由浏览器的前进/后退按钮即popstate事件触发时才存在值为该历史记录条目标记的滚动位置关于savedPosition的语义原文档强调它只在popstate导航浏览器前进/后退触发时可用。这背后是 vue-router 对每个历史记录条目记住自己的滚动位置的实现——每次通过pushState/replaceState提交新 URL 之前都会先把当前pageXOffset/pageYOffset存入一个以历史状态 key 为索引的内存字典positionStoresrc/util/scroll.jspopstate时再通过getScrollPosition()取回src/util/scroll.js。返回值协议位置描述对象scrollBehavior函数应返回一个描述滚动位置的对象支持两种形态{ x: number, y: number }—— 绝对像素坐标例如{ x: 0, y: 0 }表示页面左上角{ selector: string, offset?: { x: number, y: number } }—— 滚动到匹配该 CSS 选择器的元素处offset用于在目标位置基础上做像素偏移offset需 2.6.0 版本才支持。如果返回 falsy 值如false、null、undefined或空对象{}则不做任何滚动保持当前滚动位置不变。值得注意的是源码对返回值的处理比文档更宽容scrollToPosition会先判断是否带selector字符串用document.querySelector查找元素以数字开头的 hash 如#1number会退化为getElementById找不到元素时再退化为直接使用{ x, y }坐标src/util/scroll.js。典型场景一所有导航都回到顶部最简单的策略无论导航到哪个路由都让页面回到顶部。const router new VueRouter({ mode: history, routes: [...], scrollBehavior (to, from, savedPosition) { return { x: 0, y: 0 } } })典型场景二前进/后退时恢复原滚动位置返回savedPosition本身即可获得原生浏览器般的行为使用前进/后退按钮时恢复该历史条目之前的滚动位置其他导航则回到顶部。scrollBehavior (to, from, savedPosition) { if (savedPosition) { return savedPosition } else { return { x: 0, y: 0 } } }仓库中的官方示例 examples/scroll-behavior/app.js 正是采用这一模式。对应的 e2e 测试 test/e2e/specs/scroll-behavior.js 验证了在/页面滚动到y100后跳转到/foo再history.back()断言window.pageYOffset 100即滚动位置被准确恢复随后 forward 又断言恢复到y200。典型场景三模拟滚动到锚点行为当目标路由带 hash如/bar#anchor时返回selector让页面滚动到对应元素scrollBehavior (to, from, savedPosition) { if (to.hash) { return { selector: to.hash // , offset: { x: 0, y: 10 } // 2.6.0 支持滚动到锚点后再向下偏移 10px } } }结合offset可以精细控制锚点滚动后的最终位置例如固定顶部导航栏遮挡场景可在示例中看到#anchor2使用了position.offset { y: 100 }examples/scroll-behavior/app.js测试断言anchor2的getBoundingClientRect().top 101test/e2e/specs/scroll-behavior.js。另外两个细节值得注意如果返回的selector在页面中匹配不到任何元素vue-router 会退回到position中的{ x, y }坐标执行滚动因此仍可以同时带上坐标作为兜底对同一路由仅 hash 变化的重复导航confirmTransition检测到重复后仍会调用handleScroll以支持再次点击同一锚点的场景src/history/base.jse2e 测试中连续两次点击#anchor均断言滚动成功。进阶一异步滚动Async Scrolling2.8.0scrollBehavior还可以返回一个PromisePromise resolve 出最终的位置描述对象后再执行滚动scrollBehavior (to, from, savedPosition) { return new Promise((resolve, reject) { setTimeout(() { resolve({ x: 0, y: 0 }) }, 500) }) }这一原始能力常与页面级过渡动画配合等出场动画结束后再滚动避免滚动被过渡打断。官方示例正是如此——在transition的after-leave钩子中通过this.$root.$emit(triggerScroll)触发滚动examples/scroll-behavior/app.js。源码中handleScroll通过typeof shouldScroll.then function检测 Promise并在.then中执行实际滚动src/util/scroll.js。进阶二原生平滑滚动Smooth Scrolling对支持ScrollToOptions.behavior的浏览器可直接在返回对象中加behavior: smoothscrollBehavior (to, from, savedPosition) { if (to.hash) { return { selector: to.hash, behavior: smooth, } } }源码在scrollToPosition中检测scrollBehavior in document.documentElement.style支持则调用window.scrollTo({ left, top, behavior })不支持则退化为window.scrollTo(x, y)src/util/scroll.js。结合路由 meta 字段做细粒度控制scrollBehavior可以读取to.matched中每个路由记录的 meta 字段实现某些页面回到顶部、某些页面保持位置的差异化策略。路由 meta 字段的声明方式参见 路由 meta 字段文档在路由配置中用meta: { scrollToTop: true }声明导航时通过to.matched.some(m m.meta.scrollToTop)判断。官方完整示例 examples/scroll-behavior/app.js 综合演示了上述所有能力const scrollBehavior function (to, from, savedPosition) { if (savedPosition) { // 仅 popstate 导航时可用恢复历史滚动位置 return savedPosition } else { const position {} // 目标路由带 hash滚动到锚点 if (to.hash) { position.selector to.hash // 指定锚点元素的偏移量 if (to.hash #anchor2) { position.offset { y: 100 } } // 数字开头的锚点走 getElementById 分支 if (/^#\d/.test(to.hash) || document.querySelector(to.hash)) { return position } // 返回 falsy 值则保持当前滚动位置 return false } return new Promise(resolve { // 匹配的路由记录中任一 meta.scrollToTop 为 true则回到顶部 if (to.matched.some(m m.meta.scrollToTop)) { position.x 0 position.y 0 } // 等待出场过渡动画结束后再滚动 this.app.$root.$once(triggerScroll, () { resolve(position) }) }) } } const router new VueRouter({ mode: history, base: __dirname, scrollBehavior, routes: [ { path: /, component: Home, meta: { scrollToTop: true }}, { path: /foo, component: Foo }, { path: /bar, component: Bar, meta: { scrollToTop: true }} ] })源码级原理一次导航中滚动是如何发生的梳理 vue-router 中滚动能力的完整调用链可以更准确地理解其行为边界注册阶段HTML5History.setupListeners检测到scrollBehavior配置后调用setupScroll()src/history/html5.js。setupScroll会做两件事把window.history.scrollRestoration设为manual以屏蔽浏览器原生滚动恢复避免与 vue-router 冲突并监听popstate事件以便保存/恢复滚动位置src/util/scroll.js。保存阶段每次push/replace提交 URL 前pushState都会先调用saveScrollPosition()把当前位置按历史 key 存入positionStoresrc/util/push-state.js。触发阶段前进/后退popstatehandleScroll(router, route, current, true)第三个参数isPop true因此savedPosition有值src/history/html5.js编程式/链接导航push/replace完成后调用handleScroll(..., false)此时savedPosition为nullsrc/history/html5.js。执行阶段handleScroll先取router.options.scrollBehavior在$nextTick等待组件重渲染完成后调用你的函数再根据返回值执行scrollToPositionsrc/util/scroll.js。注意滚动被刻意推迟到$nextTick确保新页面的 DOM 已渲染、目标元素可被querySelector找到。值得强调的是返回空对象{}时isValidPosition与selector分支都不满足最终不产生任何滚动src/util/scroll.js这与文档返回空对象则不滚动的说明一致。使用建议与限制小结必须使用 history 模式并依赖支持history.pushState的浏览器hash 模式下该功能整体不可用。返回false/空对象可以显式取消滚动保持当前位置——这在带锚点但锚点元素不存在的场景下尤其有用。滚动时机默认在渲染完成后的$nextTick执行若页面有过渡动画建议用 Promise 过渡钩子自行控制时序。锚点选择器推荐使用元素的id如#anchor数字开头的 hash 会被特殊处理走getElementById分支。meta 组合善用to.matched遍历路由记录可实现按路由维度精细定制滚动策略而不必在每个页面组件中手动监听滚动。完整的可运行示例与测试分别位于 examples/scroll-behavior/app.js 和 test/e2e/specs/scroll-behavior.js可以结合本文对照阅读验证回到顶部、恢复历史位置、锚点滚动、带偏移锚点、数字锚点、加载时锚点滚动等全部行为。赞分享前端路由【免费下载链接】vue-router The official router for Vue 2项目地址https://gitcode.com/gh_mirrors/vu/vue-router点击查看免费下载相关推荐Meteor-Files安全最佳实践保护文件上传的7个关键策略Meteor Files安全最佳实践保护文件上传的7个关键策略 Meteor Files是一个稳定、快速且功能强大的Meteor.js文件管理包通过MongVue Router 滚动行为全解析scrollBehavior 配置、锚点定位与异步滚动实战Vue Router 滚动行为全解析scrollBehavior 配置、锚点定位与异步滚动实战 在客户端路由Client side Routing应用里前端路由Ascend C SIMD API UnaryRepeatParams数据结构UnaryRepeatParamsa nameZH CN_TOPIC_0000001487959374 /a UnaryRepeatParams为用于前端路由创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考