导航目的地契约¶
意图¶
用户应从每个接受或派生导航目的地的 Astryx 组件获得同样安全的导航行为。组件的视觉角色、路由集成或放大的点击目标不得决定一个被阻止的目的地是否能够执行。
成员资格规则¶
当 Astryx 接受或派生一个组件可以作为导航渲染、委托或激活的目的地时,该组件即属于此契约。成员资格遵循这种可观察的责任,而不是组件的视觉类别或它当前使用的共享 hook。
仅布局调用方拥有的链接的组件不加入。仅从 Astryx 拥有的 ID 创建固定同文档链接的组件不加入,除非它还接受调用方控制的目的地文本。在 Astryx 移交控制权后,调用方拥有的 JSX、插件渲染器和回调即超出边界。
- 当前成员: Avatar;BreadcrumbItem;Button 链接模式;Citation;ClickableCard;DropdownMenuItem 链接行(以及它们在指针菜单和触摸面板中渲染的 data-mode 项);Item;Link;ListItem;Markdown 链接;NavHeadingMenuItem;Pagination 页面链接;SideNavHeading 和 SideNavItem;navigation-mode Tab;Token 链接模式;TopNavHeading、TopNavItem、TopNavMenu、TopNavMegaMenuItem 和 TopNavMegaMenuFeaturedCard;以及 TreeListItem。
- 协作者:
useLinkComponent、LinkProvider、useClickableContainer、React DOM 的原生锚点消毒器,以及 Markdown 的解析/渲染边界。 - 排除项: Outline 的 Astryx 生成的
#id链接;AppShell 的固定跳转到内容片段;作为 children 提供的任意链接;Markdown 插件输出;图片/媒体/资源 URL,但 Markdown 图片 URL 除外,后者由 Markdown 的解析器依据其链接规则(spec:AST-005/DEC-3)决定;以及仅组合成员而不接受或派生其目的地的组件。
成员资格是开放式的。任何新发布的、符合该规则的 Core 组件都必须加入此处,即使它委托给现有成员或共享 hook。
共享负责人¶
spec:AST-005负责每个导航目的地的规范化阻止协议规则。该系列负责在成员中应用这一规则。useLinkComponent负责将目的地移交给原生和自定义链接组件,包括面向路由器的href和to接缝。被接受的结构化目的地保持对象同一性。被拒绝的目的地惰性渲染,且不会调用自定义组件。useClickableContainer负责来自放大表面的命令式导航,包括同标签页、新标签页、修饰键点击、中键点击和委托激活。每次激活都保留相同的接受/阻止结果。- Markdown 负责将不受信任的源解析为目的地,并在渲染过程中保留相同的导航决策。Markdown 的解析器负责链接和图片的这一决策,使用一条规则:共享导航规则加上每个
data:URL。渲染器只渲染已解析的节点(spec:AST-005/DEC-3)。 - 原生锚点遵循完整的共享导航规则。React DOM 自身的消毒行为不是任何被阻止协议的例外。
规范概念¶
| 概念 | 值或状态 | 默认语义 | 稳定性 |
|---|---|---|---|
| 目的地来源 | 调用方 prop、解析内容、Astryx 派生 | 调用方/解析的值需要检查;固定的 Astryx 片段在构造上是安全的 | 当前 |
| 接收端 | 原生锚点、自定义路由器、命令式浏览器 API | 每个 Astryx 拥有的接收端都强制相同的导航决策 | 当前 |
| 决策 | 接受或阻止 | 被接受的目的地保持现有行为;被阻止的目的地不导航 | 当前 |
| 激活 | 普通、新标签页、修饰、中键、编程式代理 | 激活方式不改变决策 | 当前 |
| 资源种类 | 导航或嵌入/获取的资源 | 该系列仅负责导航 | 当前 |
跨组件不变量¶
- FR1 — 每个由调用方控制的导航目的地都会在到达其接收端之前被决策。 在共享规则运行之前,任何成员都不得渲染原生导航目的地,也不得将其传递给自定义路由器或命令式浏览器 API。
- FR2 — 替代渲染保持该规则。 通过
LinkProvider或as替换原生锚点不会绕过目的地处理。 - FR3 — 替代激活保持该规则。
_blank、Cmd/Ctrl 点击、中键点击、同标签页赋值以及委托的表面点击产生相同的接受/阻止决策。 - FR4 — 被阻止的协议无法执行。 经过与浏览器兼容的协议规范化后,
javascript:、vbscript:和data:text/html不会成为导航,包括通过原生锚点。解析器负责 Markdown 链接和图片 URL 的安全性:它还会阻止链接和图片中任何媒体类型的每个data:URL。渲染器仅在真实绕过路径(如果存在)处保留检查。 - FR5 — 被接受的目的地保留浏览器行为。 相对路径、片段、协议相对目的地、HTTP(S)、mailto、tel 和安全自定义协议保留原生和路由器的导航、目标、下载和浏览器能力。被接受的结构化路由器目的地保留其字段和对象同一性。对于 Markdown,解析器负责决定接受哪些链接和图片 URL;
data:URL 不在其中。 - FR6 — 两个自定义路由器 prop 都是接收端。 提供的
href和显式to会被独立检查,包括支持的结构化形式中携带协议的字段(href、pathname和protocol)以及它们构成的目的地。如果任一提供的目的地被拒绝,结果是惰性的:自定义路由器不会被调用,即使传入undefined,也不会有回退到另一个目的地的情况。当每个提供的目的地都被接受时,被接受的显式to值保持其文档规定的优先级。 - FR7 — 禁用与拒绝是不同的。 成员保留自己的禁用语义。拒绝目的地会阻止导航,但不会制造禁用状态、标签或视觉处理。
- FR8 — 资源处理不继承导航策略。 图片、媒体、CSS URL、fetch 目标和下载的内容使用各自接收端特定的契约。被接受链接的现有下载行为得以保留。同时处理导航和资源的成员仅将本系列应用于其导航路径。Markdown 是例外:其解析器也将链接规则应用于图片 URL(
spec:AST-005/DEC-3)。
允许的组件变体¶
- AV1 — 被拒绝目标的呈现。 Markdown 可以将被拒绝的源渲染为文本; 自定义链接成员渲染惰性内容,而不调用其自定义路由器; 扩展的界面可以简单地省略导航。每个成员保留其自身的非导航结构和无障碍契约。 不提供任何组件级 bypass 属性;异常行为属于调用方拥有的、在本契约之外的自定义渲染。
- AV2 — 原生导航与路由器导航。 当成员的公共契约要求某种模式时,成员可以使用 React DOM 锚点、提供者级路由器组件、每个组件的
as覆盖,或命令式浏览器 API。 - AV3 — 目标词汇表。 公共 API 可以暴露
href、包含href的结构化条目数据、Citation 的url,或解析后的 Markdown 语法。共享行为不要求重命名已发布的 props。 - AV4 — 目标与关系。 在目标被接受后,成员保留其现有的
target、rel、referrer、download 和外部链接呈现行为。 - AV5 — 嵌入资源。 Citation 可以单独拥有图片或资源策略。Markdown 的图片 URL 遵循其解析器的链接规则(
spec:AST-005/DEC-3)。这两者都不会改变该家族中其他成员的导航矩阵。
代表性矩阵¶
| 成员与状态 | 共享不变量 | 有意差异 |
|---|---|---|
component:Link / 原生锚点 |
所有三种被阻止的目标前缀保持惰性 | 被接受的目标保留原生锚点的可供性 |
component:Link / 自定义提供者或 as |
任一被拒绝的 href/to 都会阻止路由器调用 |
路由器负责已接受的客户端导航,并接收未更改的对象 |
component:ClickableCard / 普通或修改后的点击 |
所有命令式或委托的退出路径都使用同一决策 | 可见的 Card 结构和嵌套交互处理保持局部化 |
component:Token / 带移除操作的链接 |
表面激活与隐藏链接保持一致 | 移除操作仍是独立的同级控件 |
component:Markdown / 解析后的链接 |
被阻止的源不会变成导航 | 被拒绝的源可以渲染为文本;解析器决定链接和图片 URL |
| 导航聚合 / 成员项 | 条目目标使用共享所有者 | 树、标签页、面包屑、侧边导航、顶部导航和菜单语义保持局部化 |
component:Citation / 链接的源 |
被阻止的 URL 不会执行 | 原生锚点路径和 Citation 呈现保持局部化 |
采用与例外¶
| 组件或界面 | 必需采用 |
|---|---|
| Markdown 解析并渲染的链接 | 解析器应用共享导航决策,并同时阻止所有 data: URL;渲染器只渲染解析后的节点。图片 URL 遵循相同的解析器规则(AV5)。 |
| 原生 React 锚点,包括 Citation | 完整的阻止协议规则生效;仅靠 React DOM 的 javascript: 保护是不够的。 |
useLinkComponent 自定义提供者和 as 路径 |
所提供的目标和支持的结构化形式(包括 protocol)都遵守该规则;被拒绝时绝不会调用路由器。 |
useClickableContainer 命令式路径 |
同标签页、新标签页、修饰键、中键点击和委托激活行为一致;非导航的使用方回调仍然可用。 |
| 组合这两个共享钩子的组件 | 委托的目标和任何单独渲染的原生锚点都满足完整规则。 |
这些是必需的结果,而非已完成验证的声明。只有当精确头部证据覆盖每一适用行时,采用才算完整。原生锚点的仅 React 检查、未检查的含协议字段,或使用未定义的被拒绝目标调用路由器,均不属于被批准的例外。
验证映射¶
| 契约 | 验证 | 代表性成员与状态 | 变异或失败预期 |
|---|---|---|---|
| FR4, FR5 | safeUrl.test.ts |
字符串和结构化目标;混合大小写;控制字符;相对、片段、协议相对、普通、安全自定义协议以及 data:image/*;单独的 protocol |
共享规则会接受被阻止的目标,或拒绝普通目标,包括当协议与其路径名分离时。 |
| FR1, FR2, FR6 | useLinkComponent.test.tsx 与 apps/docsite/src/__tests__/link-navigation.test.ts |
原生 Link、Button、导航成员;provider 与 as;安全/被拒绝的 href 和 to 的任意组合;结构化目的地与对象同一性 |
被拒绝的目的地会调用路由器(包括使用 undefined 或回退时),接受的对象丢失同一性,或真实路由器在渲染惰性内容时抛出异常。 |
| FR1, FR3, FR4, FR5 | useClickableContainer.test.tsx 与真实 Chromium 导航覆盖 |
ClickableCard 与 Token 形状;原生 Link;普通、_blank、Cmd/Ctrl 点击、中键点击、委托激活;接受的下载 |
被拒绝的目的地仍然可激活;发生被阻止的原生、命令式或委托导航;或接受的目的地失去某种激活模式。 |
| FR4, FR5 | parser.test.ts、urlSchemes.test.ts、Markdown.test.tsx 以及 Markdown.renderBoundary.test.tsx |
解析的、引用式、自动链接和转换后的内置链接;大小写混合;控件;普通协议;链接和图片中的每个 data: URL |
Markdown 接受被阻止的协议或链接中的任意 data: URL,拒绝普通导航目的地,或将已拒绝的节点渲染为导航。 |
| FR1, IR3 | 由 spec:AST-005 要求的 source/member 审计 |
每个由调用方控制的 Core 导航目的地 | 新的 sink 或携带目的地的组件在该成员快照之外发布。 |
| FR7, FR8 | 面向成员的行为和资源套件 | 禁用的链接模式;同一解析器规则下的 Markdown 链接和图片;Citation 链接与图片的处理差异 | 目的地拒绝改变禁用语义,或导航策略悄然变成资源策略。 |
决策链接¶
spec:AST-005/DEC-1— 目的地安全性遵循每个导航 sink。spec:AST-005/DEC-2— 嵌入资源仍作为独立策略。spec:AST-005/DEC-3— Markdown 的解析器负责其 URL 安全,并阻止每一个data:URL。
未决问题¶
无。
内容边界¶
本文件负责导航目的地成员定义、跨组件的接受/阻止结果,以及共享 sink 的采用。它不会重复组件属性表、路由器实现细节、组件局部禁用或渲染行为、嵌入资源策略、当前审计结果或系统规格的理由。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx