React Router NavLink 组件全解析：active/pending 状态、匹配算法与源码实现

本篇基于 react-router 官方 API 文档，完整讲解 NavLink 组件的全部 props（end、caseSensitive、prefetch、discover、viewTransition 等）、三种 render props 的用法，并结合仓库源码 packages/react-router/lib/dom/lib.tsx 中的实现，剖析 active/pending/transitioning 状态的计算逻辑与尾斜杠（trailing slash）匹配细节，帮助你在使用、定制和调试导航高亮时做到知其然也知其所以然。

NavLink 是什么：在 <Link> 之上叠加状态感知

NavLink 是对 <Link> 的包装组件，额外提供用于样式化 active（激活） 和 pending（导航进行中） 两种状态的 props。它的三大核心能力：

1. 自动应用 class：根据链接的 active 和 pending 状态自动附加 CSS 类名（pending 仅在 Framework 和 Data 模式下可用）；
2. 无障碍支持：当链接处于激活态时自动应用 aria-current="page" 属性（可通过 aria-current prop 自定义取值）；
3. 状态 render props：className、style、children 三个 prop 都可以传入函数，接收一个包含完整状态的对象（NavLinkRenderProps），实现完全自定义的渲染逻辑。

<NavLink to="/message">Messages</NavLink>

// Using render props
<NavLink
  to="/messages"
  className={({ isActive, isPending }) =>
    isPending ? "pending" : isActive ? "active" : ""
  }
>
  Messages
</NavLink>

Props 完整参考

to：目标地址

可以是字符串，也可以是部分 Path 对象（含 pathname、search、hash）：

<Link to="/some/path" />

<Link
  to={{
    pathname: "/some/path",
    search: "?query=string",
    hash: "#hash",
  }}
/>

children：普通子节点或状态函数

可以传入普通 React 子节点，也可以传入一个接收 { isActive, isPending, isTransitioning } 的函数：

<NavLink to="/tasks">
  {({ isActive }) => (
    <span className={isActive ? "active" : ""}>Tasks</span>
  )}
</NavLink>

className：默认类名或函数形式

不传函数时，NavLink 会自动附加与状态对应的类名——激活时加 active，导航进行中加 pending，视图过渡进行中加 transitioning：

a.active {
  color: red;
}
a.pending {
  color: blue;
}
a.transitioning {
  view-transition-name: my-transition;
}

也可以传入一个接收 NavLinkRenderProps 并返回类名的函数，此时类名完全由你控制：

<NavLink
  to="/messages"
  className={({ isActive, isPending }) =>
    isPending ? "pending" : isActive ? "active" : ""
  }
/>

源码中保留默认 active 类名是有意为之的兼容设计：注释明确说明 “In v5 active was the default value for activeClassName, but we are removing that API and can still use the old default behavior for a cleaner upgrade path”（见 lib.tsx），从 v5 升级的项目无需修改样式规则。

style：静态样式或状态函数

<NavLink to="/tasks" style={{ color: "red" }} />
<NavLink to="/tasks" style={({ isActive, isPending }) => ({
  color:
    isActive ? "red" :
    isPending ? "blue" : "black"
})} />

end：只匹配到路径“末尾”

改变 active 与 pending 的匹配逻辑——只有 URL 恰好匹配到 to 的末尾才算激活；URL 更长时不再视为激活：

Link	URL	isActive
<NavLink to="/tasks" />	/tasks	true
<NavLink to="/tasks" />	/tasks/123	true
<NavLink to="/tasks" end />	/tasks	true
<NavLink to="/tasks" end />	/tasks/123	false

to="/" 的特殊情况：由于任何 URL 都匹配 /，<NavLink to="/"> 默认会命中所有路由。为避免这种“全亮”行为，它对 end prop 采取了变通处理——实际上忽略 end，只在你确实位于根路径时才匹配。测试用例覆盖了该行为（见 nav-link-active-test.tsx 中 “matches the root route with or without the end prop” 等用例）。

caseSensitive：大小写敏感匹配

默认匹配是大小写不敏感的，caseSensitive 可将其改为敏感匹配：

Link	URL	isActive
<NavLink to="/SpOnGe-bOB" />	/sponge-bob	true
<NavLink to="/SpOnGe-bOB" caseSensitive />	/sponge-bob	false

从源码看，实现方式很直接：当 caseSensitive 为 false 时，当前路径、to 解析后的路径以及 pending 目标路径三者都会统一 toLowerCase() 后再比较（见 lib.tsx）。

relative：相对路径解析基准

定义相对路径链接的解析行为（作用于 to 的解析，进而影响匹配）：

<Link to=".." /> // default: "route"
<Link relative="route" />
<Link relative="path" />

假设父路由 pattern 为 "blog"、子路由 pattern 为 "blog/:slug/edit"：

• route（默认）——相对于路由 pattern 解析。示例中 "..." 会同时去掉 :slug/edit 两个 segment，回到 "/blog"；
• path ——相对于实际 URL path，"..." 只会去掉一个 segment，到 "/blog/:slug" 为止。

注意：index 路由和 layout 路由没有 path 段，不参与相对路径计算。

prefetch：数据与模块预取（Framework 模式）

<Link /> // default
<Link prefetch="none" />
<Link prefetch="intent" />
<Link prefetch="render" />
<Link prefetch="viewport" />

• none — 默认值，不预取；
• intent — 用户 hover 或 focus 链接时预取；
• render — 链接渲染时即预取；
• viewport — 链接进入视口时预取，对移动端非常有用。

预取通过插入 HTML <link rel="prefetch"> 标签实现，且插入位置在链接之后。因此若你的样式依赖 nav :last-child 选择器，需改用 nav :last-of-type，否则最后一个链接的样式会因 prefetch 标签的存在而“随机”失效。

discover：懒路由发现时机（Framework 模式）

定义链接的 lazy route discovery 行为：

• render（默认）——链接渲染时就发现对应路由；
• none ——不主动发现，仅当链接被点击时才发现。

preventScrollReset：禁止滚动重置（framework, data 模式）

当应用使用了 ScrollRestoration 时，防止点击该链接后滚动位置被重置到窗口顶部。它只阻止新位置导航时的滚动重置，前进/后退按钮导航的滚动位置恢复仍然生效：

<Link to="?tab=one" preventScrollReset />

replace：替换而非压栈

用新条目替换 History 栈中的当前条目，而不是压入新条目：

# with a history stack like this
A -> B

# normal link click pushes a new entry
A -> B -> C

# but with `replace`, B is replaced by C
A -> C

state：客户端路由状态

为下一个 location 附加持久化的客户端状态。该状态基于 history.state 实现，因此在服务端不可访问：

<Link to="/somewhere/else" state={{ some: "value" }} />

function SomeComp() {
  const location = useLocation();
  location.state; // { some: "value" }
}

reloadDocument：整页刷新导航

点击链接时改用 document 导航（等同于普通 <a href> 的行为），浏览器正常处理页面跳转，而非走客户端路由：

<Link to="/logout" reloadDocument />

viewTransition：启用视图过渡（framework, data 模式）

为该次导航启用 View Transition 动画。若需为过渡应用特定样式，可配合 useViewTransitionState 使用：

<Link to={to} viewTransition>
  Click me
</Link>

源码深潜：active 与 pending 是怎么算出来的

文档描述的行为在 packages/react-router/lib/dom/lib.tsx 中有对应实现，其核心匹配算法值得细看。

状态对象。NavLink 是 React.forwardRef<HTMLAnchorElement, NavLinkProps> 组件，内部计算出一个 NavLinkRenderProps 对象（类型定义）：

• isActive：链接 URL 是否与当前 location 匹配；
• isPending：pending 的 location 是否与链接 URL 匹配（仅 Framework/Data 模式下有意义）；
• isTransitioning：是否有指向该链接的 view transition 正在进行中，依赖 useViewTransitionState(path) 的返回值，且只有 viewTransition === true 时才生效。

大小写与 basename 预处理。比较前，非 caseSensitive 场景下三个路径统一转小写；若数据路由存在 pending 导航（routerState.navigation.location），会提取其 pathname 作为 nextLocationPathname，并在存在 basename 时用 stripBasename 剥离前缀，保证 end 匹配不受部署子路径影响。

尾斜杠处理（endSlashPosition）。这是匹配逻辑中最容易踩坑的部分：

// If the `to` has a trailing slash, look at that exact spot.  Otherwise,
// we're looking for a slash _after_ what's in `to`.
const endSlashPosition =
  toPathname !== "/" && toPathname.endsWith("/")
    ? toPathname.length - 1
    : toPathname.length;
let isActive =
  locationPathname === toPathname ||
  (!end &&
    locationPathname.startsWith(toPathname) &&
    locationPathname.charAt(endSlashPosition) === "/");

含义是：<NavLink to="/users"> 与 <NavLink to="/users/"> 判断“下一个字符是否为 /”的位置不同——前者看 index 6 之后，后者看 index 5 本身。这样 /users/matt 对两者都能正确判定为前缀匹配，而 /usersextra 则不会误判。isPending 使用完全相同的逻辑，只是作用于 pending 目标路径。

类名组装。若 className 是函数，直接取函数返回值；否则按 [classNameProp, isActive ? "active", isPending ? "pending", isTransitioning ? "transitioning"] 过滤空值后拼接。aria-current 默认值为 "page"，仅在 isActive 时渲染到 DOM 上。

渲染层。最终 NavLink 把计算好的 aria-current、className、style 传给内层 <Link>，children 为函数时调用 children(renderProps)——所以 render props 与内层 Link 的所有 props（prefetch、discover、replace 等）天然共存。

测试用例佐证：边界行为都有回归覆盖

nav-link-active-test.tsx 对文档中描述的每种行为都有针对性回归测试，可作为“文档承诺 vs 实际行为”的核对清单：

• 不匹配时：<a> 不附加 active 类；函数形式 children 正确渲染非激活分支；函数形式 className 返回 undefined 时 className prop 为 undefined；
• 匹配到末尾时：默认 active 类生效，包含“当前 URL 带尾斜杠”的用例；
• 部分 segment 匹配：/usersextra 之于 /users 不误匹配，根路由 segment 的特殊处理；
• 大小写：默认 /HoMe 与 /home 匹配，caseSensitive=true 时不匹配；
• data router 场景：active/pending 双类名在导航中的流转、pending 目标带尾斜杠、encoded 字符路径、basename 下的匹配。

适用模式与使用要点小结

Prop	Framework	Data	Declarative
to / end / caseSensitive / relative / replace / state / children / className / style	✅	✅	✅
preventScrollReset / viewTransition	✅	✅	❌
prefetch / discover	✅	❌	❌

三点实战建议：

1. 导航栏列表类组件优先使用函数形式 className，避免默认类名与项目设计系统冲突，并保证 pending 状态（仅 data/framework 模式）样式生效；
2. 根路径链接 <NavLink to="/"> 天然独占匹配规则，无需手动加 end；列表页/详情页层级导航则默认“前缀即激活”通常更符合预期；
3. 使用 prefetch 时检查 :last-child 类 CSS 选择器，这是预取标签插入位置带来的已知坑点（文档已明确提示）。