@ @ fast-link/ core

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

Next.js App 路由器应用程序,请使用 @fast-link/next 换句话说.

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

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

所需资源

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

安装软件包

npm install @fast-link/core

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

在指向下开始文档导航

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

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

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 当客户端路由器拥有此功能时 目标 :

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

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

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

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

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

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

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

了解事件顺序

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

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) 当适配器必须在其 路由器和文档导航:

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),
      }),
  });
}

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

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

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

了解控制器所有权

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

相关软件包

• @fast-link/react 将核心控制器绑定在反应拥有的元素上.
• @fast-link/next 提供App路由器链接和导航区域.