# @fast-link/core 中文文档

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

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

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

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

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

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

## 中文简介

指针下同源鼠标导航的 DOM 控制器

## 安装

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

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

## README

# @ @ fast-link/ core

`@fast-link/core` 在主鼠标上启动符合条件的同源链接导航 `pointerdown`。用它来表示简单的 DOM 元素,或者作为一个 框架适配器.

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)。 。 。 .

## 所需资源

支持节点.js 22或后. 导航需要浏览器 DOM.

## 安装软件包

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

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

## 在指向下开始文档导航

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

在最窄的元素上附加一个控制器,其中包含共享的链接 相同的导航行为 :

```ts
import { createFastLink } from '@fast-link/core';

const root = document.querySelector<HTMLElement>('nav');
if (!root) throw new Error('Navigation root not found');

const fastLink = createFastLink(root);
```

主鼠标导航现在开始 `pointerdown`。默认情况下,核心导航 与 `window.location.assign()`调用 `fastLink.destroy()` 当根离开时 文档.

传话员的电话 `navigate` 当客户端路由器拥有此功能时 目标 :

```ts
import { createFastLink } from '@fast-link/core';

export function attachRouterNavigation(
  root: HTMLElement,
  navigate: (destination: URL) => void,
) {
  return createFastLink(root, {
    navigate: ({ url }) => navigate(url),
  });
}
```

Core在调用路由器前验证链接. 适配器还在 负责历史、卷轴、路由状态和过渡.

## 在每个框架内初始化

-   装入快速链接和呼叫 `createFastLink` 在它控制的每个内框. 使用 Iframe 文档中的元素 .
-   例如,从 Iframe 上方运行文档导航快速启动 拥有脚本.
-   父文档控制器不接收子文档事件 .
-   将快速链接装入父目录并将其控制器附加到 iframe 元素不支持.

## 了解哪些互动快链接接受

核心只接受主鼠标 `pointerdown` 在符合资格的同源链接.

接受主播角色:

-   没有 `role` 属性,一个空值,或只有 ASCII 白空格.
-   单人 `link` 符号,大小写不敏感,可选择围绕 ASCII 白空间.

ASCII 白空间指分标签,行种子,形成种子,车厢返回,或空间.

它将这些互动留给了浏览器:

-   触摸和笔接输入
-   中, 右并被修改的点击
-   链接 a `target` 其他 `_self`
-   下载、外部 URL, 和仅散列链接
-   带有其他角色或角色清单的锁定者
-   按下开始 `button`, (中文(简体) ), `input`, (中文(简体) ), `label`, (中文(简体) ), `select`, (中文(简体) ), `summary`, (中文(简体) ), `textarea`,或带有 `button` 角色符号
-   锚或后人 `data-no-fast-link`
-   键盘激活

被接受的本土活动 被声称如此扎根,包括单独 包好芯片 导航一次.

## API 参考

| 导出 | 仁爱 | 目的 |
| --- | --- | --- |
| `createFastLink` | 函数 | 将导航行为附加到锚或区域 |
| `runFastNavigation` | 函数 | 应用路由器或文档导航决定 |
| `FastLinkController` | 类型 | 更新、 压制点击或销毁控制器 |
| `FastLinkOptions` | 类型 | 配置控制器资格和回调 |
| `FastLinkIntent` | 类型 | 描述公认的锚和目的地 |
| `FastNavigationDecision` | 类型 | 选择路由器或文档导航 |
| `FastRouterDecision` | 类型 | 使用可选滚动覆盖的适配器路由 |
| `FastDocumentDecision` | 类型 | 装入已验证的 URL `assign` 或者说 `replace` |

### `createFastLink`

```ts
function createFastLink(
  root: HTMLElement,
  options?: FastLinkOptions,
): FastLinkController;
```

根可以是一个锚地或包含锚地的区域.

| 选项 | 类型 | 默认 | 行为 |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | 控制新的指针是否可启动导航 |
| `navigate` | `(intent) => void` | `window.location.assign(intent.url.href)` | 之后进行导航 `onFastNavigate`; 其返回值被忽略 |
| `onFastNavigate` | `(intent) => void` | 无 | 运行前同步 `navigate`,用于观测,如分析 |

`createFastLink` 复制其选项。 更改原始对象没有 效应.

| 控制器方法 | 行为 |
| --- | --- |
| `update(options)` | 替换每个选项, 不清除等待的后续键 |
| `suppressClick(event)` | 应用来自较早的框架抓取处理器的待压制 |
| `destroy()` | 永久删除两个收听器; 多次调用是安全的 |

禁用新压力的早期导航,同时保持压制 等待后续点击。 当区域不再存在时, 摧毁控制器 已使用 :

```ts
import { createFastLink } from '@fast-link/core';

export function attachNavigation(
  root: HTMLElement,
  navigate: (destination: URL) => void,
) {
  const options = { navigate: ({ url }: { url: URL }) => navigate(url) };
  const controller = createFastLink(root, options);

  return {
    setEnabled(enabled: boolean) {
      controller.update({ ...options, enabled });
    },
    destroy() {
      controller.destroy();
    },
  };
}
```

每次更新都会传递回调; 省略选项重置到默认值 .

框架适配器可以调用 `suppressClick(event)` 在俘虏后代之前 操作员运行。 通过框架活动本身,使用 `target`, (中文(简体) ), `detail`,以及 `preventDefault`,因此其预防旗被更新. 包含控制器 可以压制一个被管理的后人等待点击,即使包含 控制器对另一个主锚有等待点击. 只有目标 已接受主锚,其控制器根将使用该主锚,等待点击。 无关 点击和细节-零点击仍为原生,破坏后的呼叫无所作为. 使用 `@fast-link/react` 提供此抓取绑定在 React 而不是 在应用程序中执行.

### `FastLinkIntent`

| 外地 | 类型 | 数值 |
| --- | --- | --- |
| `anchor` | `HTMLAnchorElement` | 源链接 |
| `href` | `string` | 原始的,非正常的 `href` 属性 |
| `url` | `URL` | 同一原产地的目的地根据文件基础URI解决 |

核心解决和验证 `url` 对文档来源。 带有路由器 基础路径可能需要从 `href` 或应用程序元数据 `anchor`。 。 。 .

## 了解事件顺序

核心检查资格,并声称在接受之前有一台鼠标主机 调用导航回调。 它记得锚 这样它就可以防止 后指针点击默认导航 :

```text
Ready
  |
  | Accept press; claim event
  | Remember anchor
  v
Pending click
  | Call onFastNavigate, then navigate
  | Options update: stay here
  |
  | Matching pointer click:
  | clear pending; prevent default
  v
Ready
```

-   匹配的点击目标必须同时位于已接受的主播和 控制器根 .
-   核心防止点击的默认动作而不停止传播. 点击 处理器如果元素仍然挂载, 仍然可以运行, 但不能取消 已经启动的导航 .
-   后续点击可能永远不会到来 。 每个新 `pointerdown` 已清理待处理 在资格检查前说明.
-   破坏控制器清除待处理状态,并删除其听众.

科雷尔 `onFastNavigate` 遵守公认的意图。 它不会被取消 ,则其返回值被忽略。 如果它抛出, `navigate` 仍然运行,然后 错误表面。 如果导航也抛出, 导航错误会发生 优先级。 后续点击仍然被压制.

下一个 `onNavigate` 接收可删除的事件。 导航员的 `observe` 在政策选择之后,回调会收到冻结决定。 导航 如果 `observe` 掷出.

点击方式 `detail: 0`,包括键盘活化,即使在 指针交互,其点击已丢失。 如果后续没有到达, 在同一主机上点击后脚本正则- 细节仍然可以 被压制;它的事件字段并不区分它和缺失的后继.

## 在适配器中共享导航决定

使用 `runFastNavigation(intent, options)` 当适配器必须在其 路由器和文档导航:

```ts
import {
  createFastLink,
  runFastNavigation,
  type FastLinkIntent,
  type FastNavigationDecision,
  type FastRouterDecision,
} from '@fast-link/core';

type Adapter = {
  owns(intent: FastLinkIntent): boolean;
  observe?(decision: FastNavigationDecision): void;
  route(intent: FastLinkIntent, decision: FastRouterDecision): void;
};

export function attachAdapter(root: HTMLElement, adapter: Adapter) {
  return createFastLink(root, {
    navigate: (intent) =>
      runFastNavigation(intent, {
        defaultRouterDecision: { kind: 'router' },
        policy: () =>
          adapter.owns(intent)
            ? { kind: 'router' }
            : { kind: 'document', method: 'assign' },
        observe: (decision) => adapter.observe?.(decision),
        route: (decision) => adapter.route(intent, decision),
      }),
  });
}
```

呼叫器提供路由器执行. 核心进口没有框架和 没有路由器所有权假设.

| 决定 | 行动 |
| --- | --- |
| `{ kind: 'router' }` | 使用适配器路由及其拟议的滚动行为 |
| `{ kind: 'router', scroll: false }` | 使用适配器路由并保存滚动位置 |
| `{ kind: 'document', method: 'assign' }` | 用新历史条目装入已验证的 URL |
| `{ kind: 'document', method: 'replace' }` | 装入已验证的 URL并替换当前历史记录条目 |

`runFastNavigation` 用途 `defaultRouterDecision` 仅在 `policy` 缺席。 A 类 政策运行一次并同步。 额外决定属性被忽略 .

跑者在政策评价前抓取URL,验证决定, 电话 `observe` 用被冻结的快照,并尝试一个选定的动作。 一个 观察者错误并不妨碍导航。 不显示路由器出错 文档倒置。 丢弃政策或无效的决定尝试文件 在显示策略错误前指定。 如果导航也投出于 策略或观察错误,导航错误优先.

## 了解控制器所有权

直接附属于主播的活控制器在任何主机出现之前拥有其媒体 包含控制器,即使已禁用。 摧毁锁定控制器 返回包含控制器的所有权。 多个控制器和 单独捆绑的复制件共享所有权注册, 并且只清除 被摧毁的控制器。 巢穴区域保留了先捕后捕的命令.

## 相关软件包

-   [`@fast-link/react`](https://github.com/vercel-labs/fast-link/tree/main/packages/react) 将核心控制器绑定在反应拥有的元素上.
-   [`@fast-link/next`](https://github.com/vercel-labs/fast-link/tree/main/packages/next) 提供App路由器链接和导航区域.

## 常见问题

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

指针下同源鼠标导航的 DOM 控制器

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

在项目目录运行 npm install @fast-link/core，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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

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

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