React Router 自定义链接组件指南：深入理解 useLinkClickHandler Hook

useLinkClickHandler 是 React Router 用于接管 <a> 元素点击行为的底层 Hook，官方导出的 <Link> 组件内部正是基于它构建的。当你需要打造自定义链接组件、且希望完整复刻 <Link> 的 SPA 导航行为（拦截左键点击、处理 replace/state/mask/viewTransition、阻止滚动重置等）时，它就是标准答案。读完本文，你将掌握该 Hook 的完整签名与每个参数的含义、其底层点击判定逻辑（shouldProcessLinkClick），并能直接写出带有完整 React Router 导航行为的自定义 <Link> 组件。

功能概览

useLinkClickHandler 返回一个点击处理函数，把它绑定到原生 <a> 元素（或其它任何元素）的 onClick 上，即可获得与官方 <Link> 完全一致的点击导航行为。因此，它最典型的应用场景是：

• 封装自己的 <Link> 组件，在保留完整路由行为的同时注入自定义样式、前缀逻辑、子元素结构或其它修饰；
• 让非 <a> 元素（如 <button>、卡片、图标容器）具备与链接一致的导航语义。

该 Hook 对所有三种路由模式均可用（文档头部标注 [MODES: framework, data, declarative]），即无论你使用 React Router 的框架模式、数据路由还是传统声明式路由，都可以安全调用。

函数签名与类型

function useLinkClickHandler<E extends Element = HTMLAnchorElement>(
  to: To,
  {
    target,
    replace: replaceProp,
    mask,
    state,
    preventScrollReset,
    relative,
    viewTransition,
    defaultShouldRevalidate,
    useTransitions,
  }: {
    target?: React.HTMLAttributeAnchorTarget;
    replace?: boolean;
    mask?: To;
    state?: any;
    preventScrollReset?: boolean;
    relative?: RelativeRoutingType;
    viewTransition?: boolean;
    defaultShouldRevalidate?: boolean;
    useTransitions?: boolean;
  } = {},
): (event: React.MouseEvent<E, MouseEvent>) => void

关键点说明：

• 泛型参数 E extends Element = HTMLAnchorElement 用于约束事件类型，默认锚点元素；若将返回值绑定到 <button> 等其它元素，可显式传入对应元素类型，以获得更精确的事件类型推断。
• 第一个参数 to 为导航目标，可以是字符串，也可以是部分 Path 对象（含 pathname/search/hash）。
• 第二个参数是一个可完全省略的选项对象（默认值 {}），选项均非必填。
• 返回值是一个接收 React.MouseEvent<E, MouseEvent> 的点击处理函数，可直接作为 onClick 使用。

从源码看，该 Hook 的实现位于 packages/react-router/lib/dom/lib.tsx，其内部组合了三个基础 Hook：useNavigate() 获取导航函数、useLocation() 获取当前位置、useResolvedPath(to, { relative }) 解析目标路径，最后通过 React.useCallback 结合十余项依赖（location、navigate、path、to 及各选项）缓存点击处理函数，避免每次渲染重建引用。

核心机制：什么点击会被拦截（shouldProcessLinkClick）

这是理解该 Hook 行为边界的核心。在返回的处理器内部，首先调用 shouldProcessLinkClick(event, target) 判定本次点击是否应交给 React Router 处理，判定逻辑位于 packages/react-router/lib/dom/dom.ts：

function isModifiedEvent(event: LimitedMouseEvent) {
  return !!(event.metaKey || event.altKey || event.ctrlKey || event.shiftKey);
}

export function shouldProcessLinkClick(
  event: LimitedMouseEvent,
  target?: string,
) {
  return (
    event.button === 0 && // Ignore everything but left clicks
    (!target || target === "_self") && // Let browser handle "target=_blank" etc.
    !isModifiedEvent(event) // Ignore clicks with modifier keys
  );
}

翻译成通俗规则，只有同时满足以下三个条件的点击才会被 preventDefault() 并触发客户端导航：

1. 鼠标左键（event.button === 0）：右键、中键点击交由浏览器默认处理；
2. 未指定 target 或 target 为 "_self"：如果设置了 target="_blank" 等属性，说明你期望浏览器在新窗口打开，Hook 不会干预；
3. 未按住修饰键：metaKey（Cmd/Win）、altKey、ctrlKey、shiftKey 任一被按下（即“在新标签页打开”“在新窗口打开”等浏览器原生手势）都不会被拦截，保证用户始终保有浏览器级控制权。

这些行为都有对应的测试用例作为佐证，例如 packages/react-router/tests/dom/useLinkClickHandler-test.tsx 中验证了普通点击会导航到新页面，而右键点击（button: 2）时页面保持不变。

参数详解

to（导航目标）

要导航到的 URL，可为字符串（如 "/about"、"../about"）或部分 Path 对象。它决定了 useResolvedPath 的解析基准与 <a> 元素上的 href。

options.target（锚点 target 属性）

链接的 target 属性，默认 undefined。如前所述，一旦设置为 _blank 等非 _self 值，shouldProcessLinkClick 将判定为“不由路由处理”，从而保留浏览器默认打开行为。注意：该选项不仅用于渲染，更参与点击判定，二者需保持一致。

options.replace（是否替换历史记录）

是否替换当前 History 条目而非新压入一条，默认 false。

源码中有个值得注意的智能细节（见 lib.tsx）：若未显式传入 replace，Hook 会将当前位置路径与目标路径比较，二者相同时自动退化为 replace 而不是 push，这与普通 <a> 点击同 URL 时的行为一致——避免为“原地导航”制造无用的历史记录堆叠。

options.state（历史条目状态）

要附加到本次导航 History entry 上的任意状态数据，默认 undefined。导航到达后可通过 location.state 或 useLocation() 读取。

options.mask（遮罩地址）

浏览器地址栏显示为目标之外地址的能力：导航实际发生在 to，但浏览器地址显示 mask。默认 undefined。此选项属于 framework / data 模式专属能力（在 <Link> 属性声明 中标注了 [modes: framework, data]）。

同样地，<Link> 源码 中会基于“遮罩后的位置”重新解析出 maskedHref，渲染为 <a> 的 href，使悬停状态、复制链接地址等体验也与遮罩一致。

options.preventScrollReset（阻止滚动重置）

当页面使用 ScrollRestoration 组件时，导航完成默认会把滚动位置重置到视口顶部；设为 true 可阻止该行为，默认 false。

options.relative（相对路由解析类型）

相对路径的解析基准类型，取值为 "route" | "path"，默认 "route"（按路由层级解析，如父路由下用 ".." 可回到上一级路由）。它直接透传给 useResolvedPath(to, { relative })，改变 to 中相对段（如 ../）的解析语义。

options.viewTransition（视图过渡）

为本次导航启用 View Transition API，默认 false。此选项同样属于 framework / data 模式专属能力（参见 lib.tsx#L1311 的属性标注）。若需要在过渡期间应用特定样式，请结合 useViewTransitionState 使用。

options.defaultShouldRevalidate（导航默认重校验行为）

指定本次导航的默认重校验行为，此选项属于 framework / data 模式下的 loader 重校验扩展。当传入 false 时可整体跳过本次导航触发的 loader 重校验；不指定时，loader 按照路由器的标准重校验规则（如 POST 提交后、URL 变化、shouldRevalidate 返回值等）执行。该选项同样被 <Link> 与 <Form> 接受，属于一套统一的重校验控制机制。

options.useTransitions（并发渲染过渡）

为 true 时，把整个导航调用包进 React.startTransition 中执行，以支持 React 的并发渲染（将导航标记为非紧急更新，UI 可保持响应）。默认 false。在 源码 中可以看到实现确实做了条件分支：

if (useTransitions) {
  React.startTransition(() => doNavigate());
} else {
  doNavigate();
}

注意：<Link> 自身在数据/框架模式下会自动从 NavigationContext 中取出 useTransitions 使用（见 lib.tsx#L1335-L1336）；而在自定义组件直接调用本 Hook 时，你需要按需显式传入该选项。

完整示例：构建自定义 Link 组件

下面是一个最小但完整可运行的自定义链接组件，它把 useLinkClickHandler 与 useHref 组合起来，行为与仓库 测试用例 中的 CustomLink 一致：

import * as React from "react";
import type { LinkProps } from "react-router";
import { useHref, useLinkClickHandler } from "react-router";

function CustomLink({ to, replace, state, target, ...rest }: LinkProps) {
  let href = useHref(to);
  let handleClick = useLinkClickHandler(to, { target, replace, state });
  return (
    // eslint-disable-next-line jsx-a11y/anchor-has-content
    <a {...rest} href={href} onClick={handleClick} target={target} />
  );
}

再来看一个覆盖全部可选参数、适合在框架/数据模式（使用 RouterProvider 环境）下使用的“完整版”自定义链接：

import * as React from "react";
import type { LinkProps } from "react-router";
import { useHref, useLinkClickHandler } from "react-router";

export const CustomLink = React.forwardRef<HTMLAnchorElement, LinkProps>(
  function CustomLinkWithRef(
    {
      onClick,
      replace,
      mask,
      state,
      target,
      to,
      preventScrollReset,
      relative,
      viewTransition,
      defaultShouldRevalidate,
      ...rest
    },
    forwardedRef,
  ) {
    let href = useHref(to, { relative });

    let internalOnClick = useLinkClickHandler(to, {
      replace,
      mask,
      state,
      target,
      preventScrollReset,
      relative,
      viewTransition,
      defaultShouldRevalidate,
    });

    function handleClick(
      event: React.MouseEvent<HTMLAnchorElement, MouseEvent>,
    ) {
      // 先执行外部传入的 onClick，若其调用了 preventDefault
      // 则说明调用方希望完全接管本次点击，路由处理不再介入
      if (onClick) onClick(event);
      if (!event.defaultPrevented) {
        internalOnClick(event);
      }
    }

    return (
      <a
        {...rest}
        href={href}
        onClick={handleClick}
        ref={forwardedRef}
        target={target}
      />
    );
  },
);

其中“先执行自定义 onClick、再依据 event.defaultPrevented 决定是否执行内部路由处理”的写法，正是官方 <Link> 的 handleClick 组合模式——这样既允许外部监听/劫持点击，又不破坏默认的路由行为。官方 <Link> 正是用这同一套模式把 onClick、useLinkClickHandler 和 <a> 渲染串接起来的（见 lib.tsx#L1377-L1395），你可以直接对照阅读以获得组合灵感。

使用示例

function App() {
  return (
    <div>
      {/* 完全等价于内置 <Link> 的导航行为 */}
      <CustomLink to="/about">关于我们</CustomLink>
      {/* 相对路由跳转 */}
      <CustomLink to="../settings" relative="route">设置</CustomLink>
      {/* 替换历史条目，不新增记录 */}
      <CustomLink to="/" replace>返回首页</CustomLink>
      {/* 新标签页打开：此时 Hook 不会拦截，交由浏览器处理 */}
      <CustomLink to="https://example.com" target="_blank">外部链接</CustomLink>
    </div>
  );
}

需要提醒的是：对于 target="_blank" 这类点击，shouldProcessLinkClick 会返回 false，Hook 不调用 preventDefault，导航完全交由浏览器原生行为完成——这与 SPA 内路由的语义是一致的，因为新标签页中的“页面”并不共享当前的内存路由状态。

与其它 API 的关系

API	关系
<Link>	官方链接组件，其点击导航逻辑就是 useLinkClickHandler 与 useHref 的封装，自定义组件可视为 <Link> 的可编程底座
<NavLink>	在 <Link> 基础上增加“当前激活状态”渲染能力，同样依赖点击处理机制
useHref	生成 <a href> 所需字符串的 Hook，与点击 Hook 配套使用完成“地址展示 + 点击导航”的闭环
ScrollRestoration	配合 preventScrollReset 参数实现精细的滚动位置控制
useViewTransitionState	结合 viewTransition 参数对过渡过程施加特定样式
LinkProps	类型来源，与本文示例的泛型约束一致

小结

useLinkClickHandler 把 <Link> 的整套点击导航语义抽象成一个可复用的点击处理器：左键且无修饰键且非新窗口目标时，自动 preventDefault 并驱动路由器完成导航，同时完整支持 replace 自动降级、state、mask、滚动重置控制、相对路由解析、View Transition、导航级重校验控制与 startTransition 并发渲染。只要在自定义组件中配合 useHref 生成 href、遵循“外部 onClick 未 preventDefault 才执行内部导航”的组合模式，就能在任意元素上获得与官方 <Link> 零差异的导航体验。

• 入口实现：packages/react-router/lib/dom/lib.tsx#L2211-L2285
• 点击判定逻辑：packages/react-router/lib/dom/dom.ts#L30-L43
• <Link> 的整合调用：packages/react-router/lib/dom/lib.tsx#L1377-L1395
• 行为测试：packages/react-router/tests/dom/useLinkClickHandler-test.tsx