Vue Router `＜router-link＞` 组件完全指南：Props 详解、激活状态机制与源码实现

Vue Routerrouter-link组件完全指南Props 详解、激活状态机制与源码实现【免费下载链接】vue-router The official router for Vue 2项目地址: https://gitcode.com/gh_mirrors/vu/vue-routerrouter-link是 Vue RouterVue 2 官方路由中用于触发用户导航的核心组件通过toprop 指定目标路由默认渲染为带正确href的a标签并在目标路由激活时自动附加 CSS 激活类。本文以官方文档 docs-gitbook/de/api/router-link.md 为骨架逐项讲解其全部 Props 与使用模式并结合本仓库 src/components/link.js、src/util/route.js 等源码剖析点击拦截、激活类匹配与事件代理的底层实现。读完你将掌握to/replace/append/tag/exact等所有配置项的用法、激活类全局配置方案以及基于v-slot的高阶定制能力。router-link是什么router-link是启用路由的应用中负责用户导航的组件。目标路由通过toprop 指定组件默认渲染为带正确href属性的a元素但可以通过tagprop 改为渲染其他标签。此外当目标路由处于激活状态时链接会自动获得相应的 CSS 激活类active class。其组件定义位于 src/components/link.jsprops 声明与文档一一对应props: { to: { type: [String, Object], required: true }, tag: { type: String, default: a }, custom: Boolean, exact: Boolean, exactPath: Boolean, append: Boolean, replace: Boolean, activeClass: String, exactActiveClass: String, ariaCurrentValue: { type: String, default: page }, event: { type: [String, Array], default: click } }为什么优先使用router-link而不是硬编码a href官方文档明确指出相比硬编码的a href...router-link有以下优势在所有路由模式下表现一致history、hash、abstract 三种模式下行为完全相同。因此无论你日后切换模式还是路由器在 IE9 下自动回退到 hash 模式都不需要改动任何代码。在 HTML5 history 模式下拦截点击事件router-link会拦截click事件并调用preventDefault()浏览器不会尝试重新加载整个页面导航由路由内部驱动完成。自动处理base配置在 HTML5 history 模式下使用base选项时无需在to的 URL 中重复书写 base 前缀href由路由器统一拼接生成。其中第 2 点的底层实现就是 src/components/link.js 中的guardEvent守卫函数。它在真正触发导航前做了一系列判定以下情况不会触发路由导航点击时按下了修饰键metaKey/altKey/ctrlKey/shiftKey——用户可能想在新标签页打开事件已被preventDefault调用defaultPrevented为真非左键点击e.button ! 0即右键等链接设置了target_blank/\b_blank\b/i匹配。只有通过这些检查后才会调用e.preventDefault()并返回true进而执行router.push()或router.replace()。这也解释了文档建议当你给a加上target_blank时应省略clicknavigate处理器因为此时点击会被守卫放行、交给浏览器新开标签页。Props 详解to类型string | Location源码中为[String, Object]必填to标识链接的目标路由。点击组件时to的值会在内部传给router.push()因此既可以是字符串也可以是描述目标位置的 Location 对象。官方文档给出了全部六种写法!-- 字面量字符串 -- router-link tohomeHome/router-link !-- 渲染为 -- a hrefhomeHome/a !-- 使用 v-bind 的 JavaScript 表达式 -- router-link v-bind:tohomeHome/router-link !-- 省略 v-bind 亦可与绑定其他 prop 相同 -- router-link :tohomeHome/router-link !-- 与上面等价的对象写法 -- router-link :to{ path: home }Home/router-link !-- 命名路由携带 params -- router-link :to{ name: user, params: { userId: 123 }}User/router-link !-- 携带 query最终解析为 /register?planprivate -- router-link :to{ path: register, query: { plan: private }}Register/router-link从源码看router-link渲染时src/components/link.js会将to、当前路由current与append一并交给路由器实例的resolve方法const { location, route, href } router.resolve(this.to, current, this.append)而 src/router.js 中的resolve依次完成normalizeLocation规范化目标位置 →this.match匹配出目标路由 → 基于history.base与路由模式调用createHref生成最终href。之后点击触发时link.js只要guardEvent通过就会把解析好的location交给router.push(location, noop)。push的完整签名为push(location, onComplete?, onAbort?)见 src/router.js。replace类型boolean默认值false设置replace后点击将调用router.replace()而非router.push()本次导航不会在浏览器历史中留下记录用户无法通过后退按钮回到此页。router-link :to{ path: /abc} replace/router-link源码中的分流逻辑位于 link.jsthis.replace ? router.replace(location, noop) : router.push(location, noop)。append类型boolean默认值false设置append后相对路径会始终追加到当前路径之后。例如当前位于/a导航到相对路径b不设置append时最终到达/b设置后则到达/a/b。router-link :to{ path: relative/path} append/router-linkappend的值会从组件传入router.resolve(this.to, current, this.append)link.js进而影响normalizeLocation对相对路径的解析。tag类型string默认值a有时希望router-link渲染为其他标签例如li此时用tag指定要渲染的标签。渲染为其他标签时组件仍然监听点击事件以触发导航router-link to/foo taglifoo/router-link !-- 渲染为 -- lifoo/li源码中当tag a时link.js直接在a上绑定事件监听与href、aria-current属性当tag为其他标签时link.js会调用findAnchor递归查找第一个a子元素把href、aria-current以及事件监听一并转移到该a上若内部没有a则事件监听保留在外层标签自身。需要留意的是tag与event两个 prop 在 Vue Router 4 中已被移除开发模式下 link.js 会输出弃用警告官方推荐用下面的v-slotAPI 替代——这是本仓库 3.x 版本向 4.x 迁移时需要关注的点。active-class类型string默认值router-link-active配置链接激活时附加的 CSS 类名。默认值还可以通过路由器构造选项linkActiveClass进行全局配置。全局选项的读取逻辑在 link.js组件优先使用自身的activeClassprop未传时回退到全局router.options.linkActiveClass若全局也未配置最终回退到内置默认值router-link-active。注意全局值支持显式置空 null判断因此可以通过linkActiveClass: 全局关闭激活类。exact类型boolean默认值false激活类的默认匹配方式是包含式匹配inclusive match。例如router-link to/a只要当前路径以/a开头或恰为/a就会获得激活类。由此带来的一个直接后果是router-link to/在每一条路由下都是激活的因为所有路径都以/开头。若要强制进入精确匹配模式使用exactprop!-- 该链接只在 / 时激活 -- router-link to/ exact/router-link这一行为可以直接在 src/util/route.js 的isIncludedRoute中看到它先对当前路径与目标路径做尾部斜杠归一化再判断当前路径是否以目标路径开头同时要求目标无 hash 时当前 hash 为空/相等、目标 query 的所有键都存在于当前 queryqueryIncludes。而精确匹配走的是 isSameRoute去除尾部斜杠后路径完全相等且除非只比较路径hash 与 query 也需逐键相等。两者的选择逻辑在 link.jsclasses[exactActiveClass] isSameRoute(current, compareTarget, this.exactPath) classes[activeClass] this.exact || this.exactPath ? classes[exactActiveClass] : isIncludedRoute(current, compareTarget)即设置exact或exact-path后router-link-active与router-link-exact-active两个类取同一个判定结果。另外compareTarget会优先使用route.redirectedFrom构造的规范化路由保证被重定向的链接激活状态依然正确link.js。仓库中的 examples/active-links/app.js 与对应 e2e 测试 test/e2e/specs/active-links.js 演示了包含式与精确式匹配的实际差异可运行examples/server.js查看。event类型string | Arraystring2.1.0默认值click指定可以触发链接导航的事件可以是单个事件名或事件名数组。源码 link.js 中若传入数组则遍历为每个事件注册handler否则注册单个事件const on { click: guardEvent } if (Array.isArray(this.event)) { this.event.forEach(e { on[e] handler }) } else { on[this.event] handler }handler内部仍会先经过guardEvent守卫因此即使换成mouseover等事件修饰键/右键/_blank等拦截规则依然生效。exact-path与exact-path-active-class3.5.0德文版文档成文较早本仓库主文档 docs/api/README.md 补充了这两个较新的 propexact-path类型boolean默认false。只使用 URL 的path部分进行匹配忽略query与hash!-- 在 /search?page2 或 /search#filters 下同样激活 -- router-link to/search exact-path/router-link其对应的是isSameRoute(current, compareTarget, this.exactPath)中的第三个参数onlyPathsrc/util/route.js为真时仅比较去尾斜杠的路径跳过 hash 与 query 的比对。exact-path-active-class类型string默认router-link-exact-path-active。配置精确路径匹配激活时附加的类默认值可由全局构造选项linkExactPathActiveClass配置。exact-active-class与aria-current-value同样见于 docs/api/README.mdexact-active-class类型string默认router-link-exact-active。配置精确匹配激活时的类名默认值可由全局构造选项linkExactActiveClass配置。aria-current-value类型为page | step | location | date | time | true | false默认page。配置精确匹配激活时aria-current属性的取值须符合 ARIA 规范中aria-current的允许值多数场景下默认值page是最佳选择。源码 link.js 只在精确激活类命中时才写入该属性const ariaCurrentValue classes[exactActiveClass] ? this.ariaCurrentValue : null将 active 类应用到外部元素有时希望激活类加在外层元素而非a上。官方给出的方案是把外层元素渲染为router-link内部再包裹arouter-link tagli to/foo a/foo/a /router-link此时a才是真正的链接获得正确的href属性而激活类被设置在外层的li上。这正是前面tag一节所述findAnchor逻辑的应用场景组件找到内部a后把href、aria-current与导航事件都委托给它同时类名仍挂在外层标签上link.js。基于v-slot的高阶定制3.1.0对于需要完全自定义渲染如实现NavLink类组件的场景router-link通过作用域插槽暴露底层能力。使用v-slotAPI 时router-link必须接收且仅接收一个子节点否则会包一层spanlink.js。其暴露的属性与文档一致href解析后的 URL即a元素的href属性值route解析后的规范化路由对象navigate触发导航的函数会自动像router-link一样在必要时preventDefault事件isActive应否应用 active 类router-link-active可据此挂任意类名isExactActive应否应用 exact active 类router-link-exact-active。官方示例——把激活类应用到外层元素router-link to/foo v-slot{ href, route, navigate, isActive, isExactActive } custom li :class[isActive router-link-active, isExactActive router-link-exact-active] a :hrefhref clicknavigate{{ route.fullPath }}/a /li /router-link注意给a添加target_blank时必须省略clicknavigate。另外如果不传customprop 却使用v-slot开发模式下会收到警告——在 Vue Router 4 中v-slot默认会用a包裹内容link.js。这套 API 在组合式 API 场景下对应 src/composables/useLink.js 导出的useLink(props)它返回同样结构的响应式href、route、isActive、isExactActive与navigate供自定义组件在setup中使用参考 examples/composables/app.js。navigate内部同样复用了guardEvent并依据props.replace决定调用router.replace还是router.push。全局配置与相关参考激活类相关的三个默认值均可通过路由器构造选项全局覆盖组件 prop全局构造选项内置默认值active-classlinkActiveClassrouter-link-activeexact-active-classlinkExactActiveClassrouter-link-exact-activeexact-path-active-classlinkExactPathActiveClassrouter-link-exact-path-active各构造选项的说明可参见 docs-gitbook/de/api/options.mdrouter.push/router.replace/router.resolve等实例方法的完整签名见 docs-gitbook/de/api/router-instance.md。英文主文档 docs/api/README.md 收录了router-link的完整最新 API 与v-slot示例可作为跨版本对照。小结router-link之所以是 Vue 2 应用中声明式导航的标准答案在于它把目标解析 → href 生成 → 点击拦截 → 激活状态判定整条链路封装在了组件内部to经router.resolve得到location/route/hrefguardEvent守卫拦截浏览器默认行为isIncludedRoute/isSameRoute决定激活类归属而tag/v-slot/event又提供了从简单替换标签到完全自定义渲染的完整定制梯度。理解 link.js 与 route.js 中这几处核心逻辑就能在真实项目中准确预判激活类行为并平稳规划向 Vue Router 4v-slotAPI 的迁移。【免费下载链接】vue-router The official router for Vue 2项目地址: https://gitcode.com/gh_mirrors/vu/vue-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考