前端路由【免费下载链接】vue-router The official router for Vue 2项目地址https://gitcode.com/gh_mirrors/vu/vue-router点击查看免费下载导读new VueRouter(options)是 Vue 2 应用接入路由的唯一入口其构造选项直接决定了路由表如何构建、URL 以何种形态呈现、导航失败时如何降级、以及滚动位置如何恢复。本文以 vue-router 官方文档《Opciones del constructor de Router》Router 构造选项为核心骨架逐项拆解routes、mode、base、linkActiveClass、linkExactActiveClass、scrollBehavior、parseQuery/stringifyQuery、fallback等全部构造选项的类型、默认值与使用场景并结合本仓库的源码实现src/router.js、src/history/base.js、src/util/query.js、src/util/scroll.js 等讲解每个选项背后的真实执行逻辑。读完后你将能够精确配置一个符合项目部署形态的 vue-router 实例并理解各选项在运行时如何影响路由匹配、URL 生成与导航行为。一、routes路由配置表的唯一入口类型ArrayRouteConfigroutes是构造选项中唯一一个数据性质的选项它声明了应用的全部路由。vue-router 在构造阶段会立即把它交给createMatcher处理见 src/router.js从而生成用于路径匹配的pathList、pathMap与nameMap三张表见 src/create-route-map.js。官方文档给出的RouteConfig类型声明如下字段注释已补充declare type RouteConfig { path: string; component?: Component; name?: string; // 命名路由 components?: { [name: string]: Component }; // 命名视图 redirect?: string | Location | Function; props?: boolean | string | Function; alias?: string | Arraystring; children?: ArrayRouteConfig; // 嵌套路由 beforeEnter?: (to: Route, from: Route, next: Function) void; meta?: any; // 2.6.0 新增 caseSensitive?: boolean; // 是否大小写敏感匹配默认: false pathToRegexpOptions?: Object; // 传给 path-to-regexp 的编译选项 }path是唯一必填字段。在开发环境下如果缺少pathaddRouteRecord会直接抛出断言错误path is required in a route configuration.见 src/create-route-map.js同时开发模式还会警告非嵌套路由必须以/开头、路径不应包含未编码字符、同一路径下不应出现重复的命名路由。component不能是字符串组件 id必须是实际组件对象components用于命名视图场景源码在构建RouteRecord时会做归一化components: route.components || { default: route.component }见 src/create-route-map.js。children会以父路由的path为前缀递归展开子路由记录并在开发环境下对带 name 且有默认子路由的配置给出告警对应 GH Issue #629。alias支持字符串或数组源码会为每个别名生成一条独立的匹配记录并共享原路径的组件与children见 src/create-route-map.js。redirect在导航匹配阶段被捕获处理beforeEnter作为配置内进入守卫进入导航守卫队列见 src/history/base.js。caseSensitive 与 pathToRegexpOptions如何影响匹配这两个选项在 2.6.0 引入直接作用于 vue-router 依赖的path-to-regexp正则编译环节。源码中的处理非常直观见 src/create-route-map.jsconst pathToRegexpOptions: PathToRegexpOptions route.pathToRegexpOptions || {} const normalizedPath normalizePath(path, parent, pathToRegexpOptions.strict) if (typeof route.caseSensitive boolean) { pathToRegexpOptions.sensitive route.caseSensitive }也就是说caseSensitive: true会被透传为path-to-regexp的sensitive选项使/foo不再匹配/FoopathToRegexpOptions.strict影响路径归一化非 strict默认时normalizePath会先去除末尾的/见 src/create-route-map.js其余pathToRegexpOptions字段如end、delimiter等会原样传入Regexp(path, [], pathToRegexpOptions)参与正则编译见 src/create-route-map.js。完整的类型声明可参考 types/router.d.ts 与 flow/declarations.js。二、mode三种路由模式的抉择类型string默认值hash浏览器中|abstractNode.js 中可选值hash | history | abstractmode决定路由以何种方式驱动 URL 变化hash使用 URL 中的#hash进行路由。它在所有 Vue 支持的浏览器中都能工作包括不支持 HTML5 History API 的旧浏览器。hash 变化不会触发页面刷新服务端无需任何额外配置。history使用 HTML5 History API。URL 形态更美观无#但必须配合服务端配置将所有路径回退到应用入口否则直接访问深层链接会 404。详见官方文档 Modo historial HTML5。abstract在任何 JavaScript 环境都能工作例如 Node.js 服务端渲染场景。当检测不到浏览器 API 时路由会被强制切换为abstract模式。源码视角mode 的真实决策链构造函数的决策逻辑非常清晰见 src/router.jslet mode options.mode || hash this.fallback mode history !supportsPushState options.fallback ! false if (this.fallback) { mode hash } if (!inBrowser) { mode abstract } this.mode mode switch (mode) { case history: this.history new HTML5History(this, options.base) break case hash: this.history new HashHistory(this, options.base, this.fallback) break case abstract: this.history new AbstractHistory(this, options.base) break default: // 非生产环境断言invalid mode }几个容易被忽略的细节mode缺省时取hash但如果你在 Node.js 环境下构造路由inBrowser为假最终this.mode仍会是abstract——这就是文档中自动强制的含义。三种模式分别对应 src/history/hash.js、src/history/html5.js、src/history/abstract.js 三个历史实现类它们共享 src/history/base.js 中的History基类导航队列、守卫执行、错误处理都在基类中完成。hash 模式下如果浏览器支持pushStatepushHash/replaceHash内部其实走的是pushState见 src/history/hash.js监听的事件也相应从hashchange升级为popstate见 src/history/hash.js。三、base应用的基础路径类型string默认值/base声明整个单页应用被部署在哪个 URL 前缀之下。例如应用整体位于/app/下则base应设为/app/此时所有路由解析出来的链接都会带上该前缀。源码视角base 的归一化处理base最终在History基类构造函数中被normalizeBase归一化见 src/history/base.js处理规则如下未提供base时在浏览器中会读取页面base标签的href属性作为兜底并剥离协议与域名部分否则取/在 Node.js 环境直接取/。确保以/开头缺失时自动补上。去除末尾的/如/app/会被归一化为/app。此外router.resolve()在生成href时会组合base与fullPathhash 模式拼成base /# fullPathhistory 模式拼成base / fullPath再经cleanPath清理见 src/router.js。这也是文档中整个应用位于 /app/ 下时 base 应设为 /app/的底层由来。四、linkActiveClass 与 linkExactActiveClass全局活动链接类名类型string默认值linkActiveClass为router-link-activelinkExactActiveClass为router-link-exact-active这两个选项用于全局配置router-link渲染出的链接在处于活动状态与精确匹配状态时的 CSS 类名属于router-link组件active-class与exact-active-class属性在构造阶段的全局默认值。相关选项的类型声明见 types/router.d.ts组件侧的完整用法见 router-link 文档。需要理解两者的匹配语义差异linkActiveClass对应包含匹配inclusive match只要当前路径以目标路径开头或等于目标路径链接即为 active。典型副作用是router-link to/在几乎所有路由下都处于 active 状态。linkExactActiveClass对应精确匹配exact match仅当路径完全一致时才激活。若需要仅在首页激活应依赖精确匹配语义。在类型定义中还提到了该族的扩展选项linkExactPathActiveClass默认router-link-exact-path-active它只比较 URL 的path部分、忽略query与hash这属于 Vue Router 3.5.0 之后的能力本仓库对应文档见 docs/api/README.md。五、scrollBehavior自定义滚动行为类型Function当浏览器支持history.pushState时该选项允许你在路由切换后控制页面的滚动位置。官方签名如下( to: Route, from: Route, savedPosition?: { x: number, y: number } ) { x: number, y: number } | { selector: string } | ?{}返回值可以是{ x, y }坐标、{ selector }选择器滚动到指定元素或返回空值/undefined以保持当前滚动位置在 Vue Router 3 的类型声明中还支持返回 Promise见 types/router.d.ts。完整实战讲解见 comportamiento del scroll。源码视角handleScroll 的执行细节滚动逻辑集中在 src/util/scroll.js 的handleScroll中关键行为如下延迟执行滚动发生在router.app.$nextTick回调中确保 DOM 完成重渲染后再滚动避免滚动到错误位置。savedPosition的来源浏览器前进/后退pop 导航时savedPosition是之前通过saveScrollPosition记录在positionStore中的坐标见 src/util/scroll.js普通导航则传入null。这就是返回列表页时恢复原滚动位置类需求的标准做法。支持 Promise若scrollBehavior返回一个 thenable会等待其 resolve 后再执行scrollToPosition期间异常会被断言输出见 src/util/scroll.js。selector 与 offset返回{ selector, offset }时会通过document.querySelector选择器以#数字开头时改用getElementById计算元素位置并扣除 offset见 src/util/scroll.js。平滑滚动若浏览器支持scrollBehaviorCSS 属性会透传shouldScroll.behavior调用window.scrollTo({ behavior })见 src/util/scroll.js。六、parseQuery / stringifyQuery自定义查询串解析类型Function引入版本2.4.0默认情况下vue-router 使用内置的parseQuery与stringifyQuery处理 URL 查询串。这两个构造选项允许你提供自定义实现来覆盖默认行为——典型场景是项目需要特殊的参数编码规则或非标准的分隔符。源码视角默认实现与覆盖机制默认解析逻辑在 src/util/query.js按拆分、转空格、分隔键值重复键自动聚合为数组并做严格的 RFC3986 兼容编码额外转义[!()*]、保留逗号见 src/util/query.js。覆盖机制在resolveQuery中见 src/util/query.jsconst parse _parseQuery || parseQuery try { parsedQuery parse(query || ) } catch (e) { // 非生产环境输出告警回退为空对象 }自定义解析函数抛错时会回退为空对象并给出告警自定义 stringify 函数的约定是不要输出前导?类型注释中明确说明见 types/router.d.ts因为默认stringifyQuery返回的字符串以?开头见 src/util/query.js。仓库中还提供了custom-query的单元测试用例 test/unit/specs/custom-query.spec.js 可供参考。七、fallback不支持 History API 时的降级开关类型boolean默认值true引入版本2.6.0fallback控制当mode设为history但浏览器不支持history.pushState典型如 IE9时路由是否自动降级为hash模式。默认true表示自动降级应用无需任何改动即可在旧浏览器工作。将fallback设为false后行为截然不同在 IE9 中每一次通过router-link的导航都会变成整页刷新。这看似退步却是服务端渲染SSR场景的刻意设计——因为 hash 形态的 URL 无法与 SSR 配合服务端拿不到 hash 中的路由信息此时宁可牺牲 SPA 体验也要保证 URL 形态正确。源码视角fallback 如何进入决策链回到 src/router.jsfallback 的实际判定条件比文档描述更精确let mode options.mode || hash this.fallback mode history !supportsPushState options.fallback ! false if (this.fallback) { mode hash }即只有显式指定了mode: history、浏览器不支持 pushState、且未把fallback显式设为false时才会触发降级。降级后的HashHistory还会额外接收this.fallback参数用于在构造时执行深链接的checkFallback重定向见 src/history/hash.js 与 src/history/hash.js若当前 URL 不是/#形态会先把base拼入路径并执行window.location.replace把旧地址规范化为 hash 形态。八、构造选项速查表与组合实践选项类型默认值核心作用关键源码位置routesArrayRouteConfig—声明路由表构建匹配索引src/create-route-map.jsmodestringhash/abstract选择 hash / history / abstract 模式src/router.jsbasestring/设置应用基础路径src/history/base.jslinkActiveClassstringrouter-link-active全局包含匹配活动类名types/router.d.tslinkExactActiveClassstringrouter-link-exact-active全局精确匹配活动类名types/router.d.tsscrollBehaviorFunction—导航后自定义滚动位置src/util/scroll.jsparseQueryFunction内置解析器覆盖查询串解析src/util/query.jsstringifyQueryFunction内置序列化器覆盖查询串序列化src/util/query.jsfallbackbooleantruehistory 不可用时降级为 hashsrc/router.js综合实践建议纯前端部署、无需 SEO使用默认hash模式即可无需服务端配置需要干净 URL 或 SEO使用mode: history 配置base如部署在/app/下同时务必在服务端做好 history 回退详见 Modo historial HTML5SSR / 测试环境依赖abstract模式的自动强制无需显式配置但也可显式声明以表明意图需要滚动恢复配置scrollBehavior(to, from, savedPosition)返回savedPosition以恢复前进/后退时的位置返回{ selector }滚动到锚点元素自定义查询参数编码通过parseQuery/stringifyQuery成对覆盖注意自定义 stringify 不要输出前导?。以上所有选项的完整类型声明均可直接查阅 types/router.d.ts运行时可观察的实例属性如router.mode、router.currentRoute与方法的进一步说明可参考 API 参考文档。赞分享前端路由【免费下载链接】vue-router The official router for Vue 2项目地址https://gitcode.com/gh_mirrors/vu/vue-router点击查看免费下载相关推荐Vue Router 嵌套路由Nested Routes完全指南children 配置、绝对路径与 router-view 渲染层级Vue Router 嵌套路由Nested Routes完全指南children 配置、绝对路径与 router view 渲染层级 嵌套路由是 vue前端路由OneUptime DNSSEC 监控实战从配置选项到 dig 底层实现的完整指南OneUptime DNSSEC 监控实战从配置选项到 dig 底层实现的完整指南 DNSSECDomain Name System Security Ex可观测性后端运维前端云原生微服务AI AgentX6 画布Graph配置完全指南从构造选项到源码级实现解析X6 画布Graph配置完全指南从构造选项到源码级实现解析 本篇指南以 X6 官方 API 文档 site/docs/api/graph/graph.zh前端图形学创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
