# @fast-link/react 中文文档

规范地址：https://npmcn.com/package/%40fast-link/react/

版本：0\.0\.2
npm 元数据更新时间：2026-11-02T16:44:16.393Z
中文译文更新时间：2026-11-14T10:55:05.728Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fast-link/react
原文对照：https://npmcn.com/package/%40fast-link/react/?lang=original
项目主页：https://github.com/vercel-labs/fast-link#readme
源码仓库：https://github.com/vercel-labs/fast-link

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：45.2 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：react \>=19 \<20
- 首次发布：2026-10-06T19:07:28.966Z
- 最新版本发布：2026-11-02T16:44:16.026Z
- 近 30 天下载量：10036（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

为快链接 DOM 控制器装订反应生命周期

## 安装

```sh
npm install @fast-link/react
```

也可以使用：`pnpm add @fast-link/react`、`yarn add @fast-link/react`、`bun add @fast-link/react`

## README

# @ @ fast-link/ react

`@fast-link/react` 绑定 a `@fast-link/core` 对反应拥有的控制器 锚地或导航区域。 当应用程序或框架适配器时使用 需要自己的路线政策.

Next.js App 路由器应用程序,请使用 [`@fast-link/next`](https://github.com/vercel-labs/fast-link/tree/main/packages/next) 换句话说.

关于新闻界的时间安排和选择退出,见 [何时使用快链接](https://github.com/vercel-labs/fast-link#when-to-use-fast-link)。 。 。 .

要求WCAG A级或AA级兼容的站点应当使快链接失效. 见 [无障碍限制](https://github.com/vercel-labs/fast-link#known-limitations)。 。 。 .

## 所需资源

支持Node.js 22 或后期,与 React 19 ()`>=19 <20`) (中文(简体) ).

## 安装软件包

```sh
npm install @fast-link/react
```

这个 [快链接代理技能](https://github.com/vercel-labs/fast-link#agent-skill) 列入 `skills/fast-link/SKILL.md`。 。 。 .

## 绑定导航到反应区域

导航从按下开始,在点击处理器可以取消之前. 保持链接 需要确认、发布时间检查或预期 URL 拖曳本地 通过添加 `data-no-fast-link` 到锚上.

`useFastLink` 返回 。 将两个都分开 锚或含有锚的元素,取自其其他道具:

```tsx
'use client';

import { useFastLink } from '@fast-link/react';
import type { ReactNode } from 'react';

export function AppRegion({
  children,
  route,
}: {
  children: ReactNode;
  route: (destination: URL) => void;
}) {
  const attach = useFastLink<HTMLDivElement>({
    navigate: ({ url }) => route(url),
  });

  return (
    <div {...attach} style={{ display: 'contents' }}>
      {children}
    </div>
  );
}
```

主要鼠标在区域内的导航现在调用 `route` 打开 `pointerdown`。 。 。 . 意图提供了源锚,它的作者 `href`和解决 原产地 `URL`。应用程序处理路由、历史、滚动、路由 状态和过渡.

包件不做包装并导入路由器 。 这个 `display: contents` 示例中的元素属于应用程序.

## `useFastLink` 参考文献

```ts
function useFastLink<T extends HTMLElement = HTMLElement>(
  options: FastLinkOptions & {
    forwardedRef?: ForwardedRef<T>;
    onClickCapture?: MouseEventHandler<T>;
  },
): {
  ref: (element: T | null) => void;
  onClickCapture: MouseEventHandler<T>;
};
```

| 选项 | 类型 | 默认 | 行为 |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | 控制新的指针是否可启动导航 |
| `navigate` | `(intent) => void` | `window.location.assign(intent.url.href)` | 之后进行导航 `onFastNavigate`; 其返回值被忽略 |
| `onFastNavigate` | `(intent) => void` | 无 | 运行前同步 `navigate` |
| `onClickCapture` | `MouseEventHandler<T>` | 无 | 核心压制后运行,包括防止点击 |
| `forwardedRef` | `ForwardedRef<T>` | `null` | 与控制器对调 |

科雷尔 `onFastNavigate` 遵守已接受的意向 `navigate`;无法 通过返回值取消导航或 `preventDefault()`如果它抛出, `navigate` 仍然运行,然后错误会浮出水面。 导航错误优先 如果两个回调都投出。 后续点击仍然被压制.

返回对象, ref, 和捕获处理器是稳定的. 通过呼叫器抓取 处理器通过 `onClickCapture`;钩子在压制后运行,即使当 键。 传播约束物最后保留了这种构成. 仅一个参考者无法压制被后人React捕获所阻止的点击.

DOM子树内的地方区域,包括门户和阴影 树 单是反应祖先并不能扩展一个地区的DOM范围.

## 了解钩子的生命周期

React 管理附在接收返回的 ref 元素上的控制器 :

```text
Attach root
  -> create controller

Commit options
  -> replace every copied option
  -> keep pending click

Remove root or unmount
  -> destroy controller

Replace root
  -> destroy old controller
  -> create new controller
```

-   将控制器清除等待点击状态, 并删除听众 .
-   强制调用器 - ref 更改在指派前运行旧调试器的清理 新书.
-   服务器渲染不附加控制器 .
-   在被接受后, 匹配指针点击被默认防止 继续传播.
-   触摸、笔接、键盘和修改过的点击保持其原生行为 不打电话 `navigate`。 。 。 .

核心拥有 [资格、点击压制和事件排序](https://github.com/vercel-labs/fast-link/tree/main/packages/core#understand-event-ordering)。 。 。 . 添加 `data-no-fast-link` 当浏览器必须保留时, 发送到锚或后人 互动.

## 相关软件包

-   [`@fast-link/core`](https://github.com/vercel-labs/fast-link/tree/main/packages/core) 文档资格、控制器选项和适配器决定.
-   [`@fast-link/next`](https://github.com/vercel-labs/fast-link/tree/main/packages/next) 提供App路由器组件和一个自定义的发车钩.

## 常见问题

### @fast-link/react 是什么？

为快链接 DOM 控制器装订反应生命周期

### 如何安装 @fast-link/react？

在项目目录运行 npm install @fast-link/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19 \<20）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fast-link/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fast-link/react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fast-link/react 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fast-link/react 可以商用吗？

@fast-link/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fast-link/react 的下载量有多少？

根据 npm 官方下载统计，@fast-link/react 在 2026/10/15 – 2026/11/13 这 30 天内被下载 10,036 次，日均约 335 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fast-link/react 还在维护吗？

最新版本 0\.0\.2 发布于 2026/11/03（11 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/10/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。