# @fast-link/next 中文文档规范地址：https://npmcn.com/package/%40fast-link/next/ 版本：0\.0\.2 npm 元数据更新时间：2026-11-02T16:44:27.392Z 中文译文更新时间：2026-11-14T10:54:31.661Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/%40fast-link/next 原文对照：https://npmcn.com/package/%40fast-link/next/?lang=original 项目主页：https://github.com/vercel-labs/fast-link#readme 源码仓库：https://github.com/vercel-labs/fast-link ## 关键信息（来自 npm 元数据） - 包体积（解压后）：66.8 kB，13 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：2 个 - peer 依赖：next \>=16 \<17，react \>=19 \<20 - 首次发布：2026-10-06T19:07:29.556Z - 最新版本发布：2026-11-02T16:44:27.088Z - 近 30 天下载量：10238（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：4（近 12 个月 4 个） ## 中文简介 Next.js App路由器链接的早期鼠标导航 ## 安装 ```sh npm install @fast-link/next ``` 也可以使用：`pnpm add @fast-link/next`、`yarn add @fast-link/next`、`bun add @fast-link/next` ## README # @ fast-link/ next `@fast-link/next` 启动符合条件的一次机动导航 `pointerdown` 内 a Next.js App路由器应用程序。它为现有的链接提供组件区域和个人链接,外加自定义渲染器的钩. 关于新闻界的时间安排和选择退出,见 [何时使用快链接](https://github.com/vercel-labs/fast-link#when-to-use-fast-link)。。。 . [安装](https://npmcn.com/package/%40fast-link/next/#readme-install-the-package) • 妇女 [选择接口](https://npmcn.com/package/%40fast-link/next/#readme-choose-an-interface) • 妇女 [一个链接](https://npmcn.com/package/%40fast-link/next/#readme-configure-one-link) • 妇女 [区域和基本路径](https://npmcn.com/package/%40fast-link/next/#readme-add-fast-link-to-a-navigation-region) • 妇女 [导航和待决状态](https://npmcn.com/package/%40fast-link/next/#readme-understand-navigation-and-click-behavior) • 妇女 [规则政策](https://npmcn.com/package/%40fast-link/next/#readme-route-links-across-application-boundaries) • 妇女 [自定义渲染器](https://npmcn.com/package/%40fast-link/next/#readme-build-a-custom-renderer) • 妇女 [API 参考](https://npmcn.com/package/%40fast-link/next/#readme-api-reference) 要求WCAG A级或AA级兼容的站点应当使快链接失效. 见 [无障碍限制](https://github.com/vercel-labs/fast-link#known-limitations)。。。 . ## 所需资源支持Node.js 22 或后期,与 Next.js 16 (`>=16 <17`)和反应19(`>=19 <20`) (中文(简体) ). 需要 Next.js App路由器 . ## 安装软件包 ```sh npm install @fast-link/next ``` 这个 [快链接代理技能](https://github.com/vercel-labs/fast-link#agent-skill) 列入 `skills/fast-link/SKILL.md`。。。 . ## 选择接口 | 接口 | 用它来 | | --- | --- | | `FastLink` | 一个 App 路由器链接及其自己的链接选项 | | `FastLinkRegion` | 共享一个导航政策的现有链接 | | `useFastLink` | 使主锚成为自定义组件 | ## 配置一个链接使用 `FastLink` 当一个链接需要它自己的Next.js行为时: ```tsx import { FastLink } from '@fast-link/next'; export function AccountLink() { return ( Account ); } ``` - 支助 [下一个链接选项](https://npmcn.com/package/%40fast-link/next/#readme-fastlink),包括对象 `href`。。。 . - 保存下个链接预取和本地激活 . - 将自己的选择和政策保留在 `FastLinkRegion`,即使残疾. ## 向导航区域添加快链接环绕已有 `next/link` 或锚定元素,具有一种导航政策: ```tsx import { FastLinkRegion } from '@fast-link/next'; import Link from 'next/link'; export default function Navigation() { return ( ); } ``` - 使用 `FastLink` 每个链接选项。它把自己的选择和政策放在里面 a 区域. - 区域无法从普通已实现的锚读取 Next Link 选项 . - 服务器组件可以作为孩子通过链接子树. - 包装是 `display: contents` div,没有布局框. 保留语义元素,例如 `nav` 内在的. ### 配置 Next.js 基础路径符合 `basePath` 配置于 `next.config`数字 : ```tsx import { FastLinkRegion } from '@fast-link/next'; import Link from 'next/link'; export function DocsNavigation() { return ( ); } ``` - 下一个链接 `/docs/overview`。。。 . - 区域经过 `/overview` 添加的 App 路由器 `/docs` 回来. - 选择区域配置的基础路径可以产生 `/docs/docs/overview`。。。 . - 一个精确的前缀被删除. `/docs` 变成 `/`· ; `/docs-extra` 保持不变. - 平地锚需要他们的底道 `href` 用于本土导航. - 无应用程序基础路径: 省略道具( 默认) `''`) (中文(简体) ). - `FastLink` 使用它的作者目的地; 它没有 `basePath` 道具 (英语). ### 在正常路径上留下一个区域链接添加 `data-no-fast-link` 当普通链接的点击时间行为或链接选项必须运行 : ```tsx import Link from 'next/link'; export function AccountLink() { return ( Account ); } ``` - 选择退出点击时间守护器或链接选项 . - 后裔 `onPointerDownCapture` 可在区域听众。泡泡处理器运行为时已晚,无法取消早期导航. - 在客户端组件中定义回调 . ## 理解导航和单击行为 - 点击时守护符:如果必须在导航前运行,则选择退出. - API 路由或其他应用程序的页面:选择明确的路由政策或选择退出。见 [应用程序边界](https://npmcn.com/package/%40fast-link/next/#readme-route-links-across-application-boundaries)。。。 . 对于一个被接受的主鼠标新闻,一个管理下的链接呼叫Next.js Link's `onNavigate` 选择导航前的道具。普通区域链接跳过调用. | 条件 | 导航 | | --- | --- | | 管理 `onNavigate` 电话 `preventDefault()` | 取消早期导航; 跳过策略并 `onFastNavigate`。。。 . | | 没有 `navigationPolicy` | 使用当前 App 路由器 . | | 策略选择 `{ kind: 'router' }` | 使用 Next 的目的地和历史方法, 并带有可选的卷轴覆盖 . | | 策略选择 `{ kind: 'document', method }` | 使用文档装入已验证的 URL `assign` 或者说 `replace`。。。 . | - 对于无缘导航, `onFastNavigate(intent, decision)` 观察在尝试导航前选中的决定 . - 策略不能取消导航或重写路由器目的或历史方法. - 匹配的后继指针点击被默认防止, 甚至在管理后 `onNavigate` 取消。它不能触发默认导航,但仍传播给挂载的链接和祖先处理器. - 路径可能在发布前卸载处理器. 拖着走可能会导航不产生点击. - 一个 `onPointerDown` 气泡护卫在早期导航后运行. 使用同步 `onNavigate` 取消新闻时间验证; 选择退出发布时间审定. 原生行为仍为: - 触摸,笔接,键盘,被修改和非主点击. - 下载、外部或散列 URL, 非`_self` 目标,嵌入式控制器, 财务报告和审定财务报表 `data-no-fast-link` 选择退出. 见核心 [资格规则](https://github.com/vercel-labs/fast-link/tree/main/packages/core#know-which-interactions-fast-link-accepts)。。。 . 使用 `enabled={false}` 以禁用组件的早期导航. 其他一体化规则: - 键盘和触摸激活跳过 `navigationPolicy`; 维护应用程序对这些输入的正常路由. - 与 `as` 或者说 `legacyBehavior`, (中文(简体) ), `FastLink` 保留在正常的链接路径上. 后遗症行为不将控制器附加到锚上; 添加 `data-no-fast-link` 当锚需要本地处理在一个区域. - 承诺选项更新保留待点击压制。删除或替换根会破坏旧控制器并清除待压制. ### 待处理状态 - `useLinkStatus().pending` 不更新。无法设置公共 App 路由器呼叫 Next Link的待决状态. - 使用路由级别加载 UI, 或在您的应用程序中管理待处理状态 . - 开始应用状态 `onFastNavigate`它报告有一次尝试,而不是完成. - 竣工后清除. 在失败、取消和卸载时重置. ## 跨应用程序边界的路由链接当当前 App 路由器不拥有每个相同来源时, 提供策略目标。将策略装入可重复使用的客户端组件包装中 : `navigationPolicy` 手柄接受鼠标早期导航。保护用于键盘和触摸激活也一样. ```tsx 'use client'; import { FastLink, FastLinkRegion, type FastLinkProps, type FastLinkRegionProps, type FastNavigationPolicy, } from '@fast-link/next'; import { forwardRef } from 'react'; const ownedPaths = new Set(['/overview', '/pricing']); const navigationPolicy: FastNavigationPolicy = (intent, proposed) => { const route = new URL(proposed.destination, intent.url); return ownedPaths.has(route.pathname) ? { kind: 'router' } : { kind: 'document', method: 'assign' }; }; export const AppLink = forwardRef< HTMLAnchorElement, Omit >(function AppLink(props, ref) { return ; }); export function AppRegion( props: Omit, ) { return ; } ``` 两种包装都采用相同的导航政策. `AppLink` 转发调用者的参考文献和链接选项. `AppRegion` 区域道具,包括 `basePath`, (中文(简体) ), `enabled`,以及 `onFastNavigate`。。。 . Fast Link 不从路径或元数据推断所有权. 外国或作为文档导航的未知所有权。内部的普通链接 `AppRegion` 使用区域政策,同时 `AppLink` 使用自己的政策和链接选项. 链接 `onNavigate` 在保险之前运行。取消跳过策略, 观察, 导航需要点击时间守护的链接必须先选择退出 `pointerdown`; 策略不能将控件返回原点击. 丢弃策略或无效的决定尝试文件指定给抓取者 URL,然后显示策略错误. 额外决定属性被忽略 . 观察错误仍然允许导航. 没有文档的路由器出错倒计时。如果导航在策略或观察者出错后也投出,则导航错误优先. ## 构建自定义渲染器偏爱 `FastLink` 用于可重复使用的包装器,用于前置还原和链接道具。使用 `useFastLink` 当一个已有的造物主控制锚地的时候, 点击处理器, 或待处理状态 : ```tsx 'use client'; import { useFastLink, type UseFastLinkOptions } from '@fast-link/next'; import Link from 'next/link'; import { forwardRef, type ComponentPropsWithoutRef } from 'react'; type AppLinkProps = ComponentPropsWithoutRef & Pick; export const AppLink = forwardRef( function AppLink({ enabled, ...props }, forwardedRef) { const attach = useFastLink({ ...props, enabled, forwardedRef, }); return ; }, ); ``` 渲染器必须同时向锚或倒置元件上转发绑定物. 把它的抓取处理器传入钩子,然后将绑定物延伸到最后,这样它就可以运行压制后。渲染器保留了正常的Link道具并转发回放. 添加 `onFastNavigate` 以保留应用程序,等待路由级别时的状态装入UI还不够 . ## API 参考 ### 链接、区域和钩子共享的选项 | 选项 | 类型 | 默认 | 行为 | | --- | --- | --- | --- | | `enabled` | `boolean` | `true` | 控制新的指针是否可启动导航 | | `navigationPolicy` | `FastNavigationPolicy` | 无 | 选择 App 路由器或文档导航 | | `onFastNavigate` | `(intent, decision) => void` | 无 | 在导航前遵守被冻结的决定 | `onFastNavigate` 无法更改选定的动作。它的返回值被忽略了, 如果发射的话,仍然试图导航. ### `FastLink` `FastLinkProps` 包括 `next/link` 加上共享选项. `href` 仍然需要. 快导航保存 `replace`, (中文(简体) ), `scroll`,以及 `transitionTypes` 选项. `transitionTypes` 跟踪已安装的 `next/link` 类型; 省略在不声明的下个版本上勾选选项. `onNavigate` 在政策评价、观察或导航. ### `FastLinkRegion` | Prop | 类型 | 默认 | 行为 | | --- | --- | --- | --- | | `children` | `ReactNode` | 需求 | 提供现有链接子树 | | `basePath` | `string` | `''` | 删除前一个匹配的前缀 `router.push` | | `enabled` | `boolean` | `true` | 控制区域内普通链接的早期导航 | | `navigationPolicy` | `FastNavigationPolicy` | 无 | 选择 App 路由器或文档导航 | | `onFastNavigate` | `(intent, decision) => void` | 无 | 在导航前观察所选决定 | 巢穴区域保留了先捕后捕的命令。管理 `FastLink` 或者说 `useFastLink` 主播在每一个包含区域之前拥有自己的新闻. ### `useFastLink` `useFastLink(options)` 返回稳定 `{ ref, onClickCapture }` 约束应用程序主锚或可选水深元素。在同一DOM上展开两个元素后其他道具。它接受: - `href`, (中文(简体) ), `as`, (中文(简体) ), `legacyBehavior`, (中文(简体) ), `replace`, (中文(简体) ), `scroll`, (中文(简体) ), `onNavigate`,以及 `transitionTypes` 从 `next/link` - 共享 `enabled`, (中文(简体) ), `navigationPolicy`,以及 `onFastNavigate` 选项 - `forwardedRef` 来电员的裁判 - `onClickCapture`后调用,即使点击被阻止一个不见了 `href`, 提供 `as`, (中文(简体) ), `legacyBehavior={true}`,或非锁定根离开导航在它的正常路径。选项更新保留待决后继点击. 替换根或卸载会破坏控制器清理由法官组成的裁判. ### 导航政策类型 `FastNavigationPolicy(intent, proposed)` 同步运行并返回 a `FastNavigationDecision`。。。 . `FastRouterProposal` 描述适配器的路由将采取无政策: | 建议领域 | 类型 | 数值 | | --- | --- | --- | | `destination` | `string` | 计算 App 路由器目的地 | | `method` | `'push' | 'replace'` | 拟议的历史方法 | | `scroll` | `boolean | undefined` | 拟议滚动行为 | | 决定 | 行动 | | --- | --- | | `{ kind: 'router' }` | 使用拟议路由和滚动行为 | | `{ kind: 'router', scroll: false }` | 使用拟议路线并保存滚动位置 | | `{ kind: 'document', method: 'assign' }` | 用新历史条目装入已验证的 URL | | `{ kind: 'document', method: 'replace' }` | 装入已验证的 URL并替换当前历史记录条目 | 策略只能超越路由器滚动行为。无法替换目标、历史方法或过渡设置. ### 出口 `@fast-link/next` 出口 `FastLink`, (中文(简体) ), `FastLinkRegion`, (中文(简体) ), `useFastLink`, (中文(简体) ), `FastLinkProps`, (中文(简体) ), `FastLinkRegionProps`, (中文(简体) ), `UseFastLinkOptions`, (中文(简体) ), `FastRouterProposal`, (中文(简体) ), `FastNavigationPolicy`, (中文(简体) ), `FastNavigationDecision`,以及 `FastLinkIntent`。。。 . ## 常见问题 ### @fast-link/next 是什么？ Next\.js App路由器链接的早期鼠标导航 ### 如何安装 @fast-link/next？在项目目录运行 npm install @fast-link/next，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（\>=16 \<17）、react（\>=19 \<20）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @fast-link/next 支持 TypeScript 吗？支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fast-link/next 支持 ESM 还是 CommonJS？以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @fast-link/next 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @fast-link/next 可以商用吗？ @fast-link/next 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fast-link/next 的下载量有多少？根据 npm 官方下载统计，@fast-link/next 在 2026/10/15 – 2026/11/13 这 30 天内被下载 10,238 次，日均约 341 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fast-link/next 还在维护吗？最新版本 0\.0\.2 发布于 2026/11/03（11 天前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/10/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。