@ fast-link/ next

@fast-link/next 启动符合条件的一次机动导航 pointerdown 内 a Next.js App路由器应用程序。 它为现有的链接提供组件 区域和个人链接,外加自定义渲染器的钩.

关于新闻界的时间安排和选择退出,见 何时使用快链接。 。 。 .

安装 • 妇女 选择接口 • 妇女 一个链接 • 妇女 区域和基本路径 • 妇女 导航和待决状态 • 妇女 规则政策 • 妇女 自定义渲染器 • 妇女 API 参考

要求WCAG A级或AA级兼容的站点应当使快链接失效. 见 无障碍限制。 。 。 .

所需资源

支持Node.js 22 或 后期,与 Next.js 16 (>=16 <17)和反应19(>=19 <20) (中文(简体) ). 需要 Next.js App路由器 .

安装软件包

npm install @fast-link/next

这个 快链接代理技能 列入 skills/fast-link/SKILL.md。 。 。 .

选择接口

配置一个链接

使用 FastLink 当一个链接需要它自己的Next.js行为时:

import { FastLink } from '@fast-link/next';

export function AccountLink() {
  return (
    <FastLink href="/account" replace scroll={false}>
      Account
    </FastLink>
  );
}

• 支助 下一个链接选项,包括对象 href。 。 。 .
• 保存下个链接预取和本地激活 .
• 将自己的选择和政策保留在 FastLinkRegion,即使残疾.

向导航区域添加快链接

环绕已有 next/link 或锚定元素,具有一种导航政策:

import { FastLinkRegion } from '@fast-link/next';
import Link from 'next/link';

export default function Navigation() {
  return (
    <FastLinkRegion>
      <nav>
        <Link href="/overview">Overview</Link>
        <Link href="/pricing">Pricing</Link>
      </nav>
    </FastLinkRegion>
  );
}

• 使用 FastLink 每个链接选项。 它把自己的选择和政策放在里面 a 区域.

• 区域无法从普通已实现的锚读取 Next Link 选项 .

• 服务器组件可以作为孩子通过链接子树.

• 包装是 display: contents div,没有布局框. 保留语义元素,例如 nav 内在的.

配置 Next.js 基础路径

符合 basePath 配置于 next.config数字 :

import { FastLinkRegion } from '@fast-link/next';
import Link from 'next/link';

export function DocsNavigation() {
  return (
    <FastLinkRegion basePath="/docs">
      <nav>
        <Link href="/overview">Overview</Link>
      </nav>
    </FastLinkRegion>
  );
}

• 下一个链接 /docs/overview。 。 。 .
• 区域经过 /overview 添加的 App 路由器 /docs 回来.
• 选择区域配置的基础路径可以产生 /docs/docs/overview。 。 。 .
• 一个精确的前缀被删除. /docs 变成 /· ; /docs-extra 保持不变.
• 平地锚需要他们的底道 href 用于本土导航.
• 无应用程序基础路径: 省略道具( 默认) '') (中文(简体) ).
• FastLink 使用它的作者目的地; 它没有 basePath 道具 (英语).

在正常路径上留下一个区域链接

添加 data-no-fast-link 当普通链接的点击时间行为或链接 选项必须运行 :

import Link from 'next/link';

export function AccountLink() {
  return (
    <Link href="/account" data-no-fast-link replace scroll={false}>
      Account
    </Link>
  );
}

• 选择退出点击时间守护器或链接选项 .
• 后裔 onPointerDownCapture 可在 区域听众。 泡泡处理器运行为时已晚,无法取消早期导航.
• 在客户端组件中定义回调 .

理解导航和单击行为

• 点击时守护符:如果必须在导航前运行,则选择退出.
• API 路由或其他应用程序的页面:选择明确的路由政策 或选择退出。 见 应用程序边界。 。 。 .

对于一个被接受的主鼠标新闻,一个管理下的链接呼叫Next.js Link's onNavigate 选择导航前的道具 。 普通区域链接跳过 调用.

• 对于无缘导航, onFastNavigate(intent, decision) 观察 在尝试导航前选中的决定 .
• 策略不能取消导航或重写路由器目的或历史 方法.
• 匹配的后继指针点击被默认防止, 甚至在管理后 onNavigate 取消 。 它不能触发默认导航,但仍 传播给挂载的链接和祖先处理器.
• 路径可能在发布前卸载处理器. 拖着走可能会导航 不产生点击.
• 一个 onPointerDown 气泡护卫在早期导航后运行. 使用同步 onNavigate 取消新闻时间验证; 选择退出发布时间 审定.

原生行为仍为:

• 触摸,笔接,键盘,被修改和非主点击.
• 下载、 外部或散列 URL, 非_self 目标,嵌入式控制器, 财务报告和审定财务报表 data-no-fast-link 选择退出.

见核心 资格规则。 。 。 . 使用 enabled={false} 以禁用组件的早期导航.

其他一体化规则:

• 键盘和触摸激活跳过 navigationPolicy; 维护 应用程序对这些输入的正常路由.
• 与 as 或者说 legacyBehavior, (中文(简体) ), FastLink 保留在正常的链接路径上. 后遗症行为不将控制器附加到锚上; 添加 data-no-fast-link 当锚需要本地处理 在一个区域.
• 承诺选项更新保留待点击压制 。 删除或 替换根会破坏旧控制器 并清除待压制.

待处理状态

• useLinkStatus().pending 不更新。 无法设置公共 App 路由器呼叫 Next Link的待决状态.
• 使用路由级别加载 UI, 或在您的应用程序中管理待处理状态 .
• 开始应用状态 onFastNavigate它报告有一次尝试,而不是完成.
• 竣工后清除. 在失败、取消和卸载时重置.

跨应用程序边界的路由链接

当当前 App 路由器不拥有每个相同来源时, 提供策略 目标。 将策略装入可重复使用的客户端组件包装中 :

navigationPolicy 手柄接受鼠标早期导航。 保护 用于键盘和 触摸激活也一样.

'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<FastLinkProps, 'navigationPolicy'>
>(function AppLink(props, ref) {
  return <FastLink {...props} ref={ref} navigationPolicy={navigationPolicy} />;
});

export function AppRegion(
  props: Omit<FastLinkRegionProps, 'navigationPolicy'>,
) {
  return <FastLinkRegion {...props} navigationPolicy={navigationPolicy} />;
}

两种包装都采用相同的导航政策. AppLink 转发调用者的参考文献 和链接选项. AppRegion 区域道具,包括 basePath, (中文(简体) ), enabled,以及 onFastNavigate。 。 。 .

Fast Link 不从路径或元数据推断所有权. 外国或 作为文档导航的未知所有权 。 内部的普通链接 AppRegion 使用区域政策,同时 AppLink 使用自己的政策和链接选项.

链接 onNavigate 在保险之前运行。 取消跳过策略, 观察, 导航 需要点击时间守护的链接必须先选择退出 pointerdown; 策略不能将控件返回原点击.

丢弃策略或无效的决定尝试文件指定给抓取者 URL,然后显示策略错误. 额外决定属性被忽略 . 观察错误仍然允许导航. 没有文档的路由器出错 倒计时。 如果导航在策略或观察者出错后也投出,则 导航错误优先.

构建自定义渲染器

偏爱 FastLink 用于可重复使用的包装器,用于前置还原和链接道具。 使用 useFastLink 当一个已有的造物主控制锚地的时候, 点击处理器, 或待处理状态 :

'use client';

import { useFastLink, type UseFastLinkOptions } from '@fast-link/next';
import Link from 'next/link';
import { forwardRef, type ComponentPropsWithoutRef } from 'react';

type AppLinkProps = ComponentPropsWithoutRef<typeof Link> &
  Pick<UseFastLinkOptions, 'enabled'>;

export const AppLink = forwardRef<HTMLAnchorElement, AppLinkProps>(
  function AppLink({ enabled, ...props }, forwardedRef) {
    const attach = useFastLink({
      ...props,
      enabled,
      forwardedRef,
    });

    return <Link {...props} {...attach} />;
  },
);

渲染器必须同时向锚或倒置元件上转发绑定物. 把它的抓取处理器传入钩子,然后将绑定物延伸到最后,这样它就可以运行 压制后。 渲染器保留了正常的Link道具并转发回放. 添加 onFastNavigate 以保留应用程序,等待路由级别时的状态 装入UI还不够 .

API 参考

链接、区域和钩子共享的选项

onFastNavigate 无法更改选定的动作。 它的返回值被忽略了, 如果发射的话,仍然试图导航.

FastLink

FastLinkProps 包括 next/link 加上共享 选项. href 仍然需要.

快导航保存 replace, (中文(简体) ), scroll,以及 transitionTypes 选项. transitionTypes 跟踪已安装的 next/link 类型; 省略 在不声明的下个版本上勾选选项. onNavigate 在政策评价、观察或 导航.

FastLinkRegion

巢穴区域保留了先捕后捕的命令。 管理 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 描述适配器的路由 将采取无政策:

策略只能超越路由器滚动行为 。 无法替换 目标、历史方法或过渡设置.

出口

@fast-link/next 出口 FastLink, (中文(简体) ), FastLinkRegion, (中文(简体) ), useFastLink, (中文(简体) ), FastLinkProps, (中文(简体) ), FastLinkRegionProps, (中文(简体) ), UseFastLinkOptions, (中文(简体) ), FastRouterProposal, (中文(简体) ), FastNavigationPolicy, (中文(简体) ), FastNavigationDecision,以及 FastLinkIntent。 。 。 .