LinkProvider 组件契约¶
契约一览¶
| 方面 | 契约 |
|---|---|
| 公共契约 | 无变更。LinkProvider 接受必需的 component 和 children。 |
| 行为 | 子树中通过共享链接边界解析的每个 Astryx 链接均使用 component 渲染,除非组件自身的 as 覆盖了 component。以最近的 provider 为准。 |
| 最终用户影响 | 在应用路由器支持的情况下,用户可以通过 Astryx 链接获得应用的客户端路由(不会整页刷新)。不安全的链接目标仍然绝不会导航。 |
| 构建者影响 | 无。 |
| 兼容性/就绪度 | 记录已发布行为;无 API、默认值或 DOM 变更。 |
| 评审检查 | 应拒绝以下 provider:渲染自身元素、覆盖显式 as、越过更近的 provider 继续生效、或让被拒绝的链接目标到达 component。 |
| 适用规则 | family:navigation-destinations FR1、FR2、FR5、FR6、AV2;spec:AST-005。 |
此表是评审投影;下文正文为权威依据。
目的¶
LinkProvider 让应用可以在子树中一次性为每个 Astryx 链接将原生锚点替换为其路由器的链接组件。它是 family:navigation-destinations 的协作者。消费方用法见 LinkProvider.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes;没有 provider 时,链接渲染为原生锚点 - 兼容性类别:记录已发布行为;无公开 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:不适用
- 迁移决策:无
消费方迁移说明应写入消费方文档和发布说明。
所有权边界¶
拥有
- 向子树提供
component及其作用域。
不拥有 / 非目标
- 面向路由器的
href和to交接,包括 FR3 中的默认to——由family:navigation-destinations中的共享链接边界(useLinkComponent)负责;在没有 provider 时,相同的默认to也会到达as组件。 - 链接目标检查与被拒绝链接目标的非交互渲染——由
family:navigation-destinationsFR6 和spec:AST-005FR7 负责;FR4 指向它们。 - 组件究竟在何时渲染链接——由各组件负责(例如
component:LinkFR1 和component:ButtonFR11)。 - 来自扩大表面的命令式导航——由
family:navigation-destinations通过自身的 hook 负责。 - 路由器组件自身的行为。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 归属方 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 链接组件 | 任意元素类型 | 在作用域内渲染被接受的链接目标。 | 仅在 provider 内部。 | 原生锚点 | component:LinkProvider |
稳定 | 忽略 href 和 to 的组件无法导航。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | LinkProvider 仅渲染其 children,不添加任何元素。 | 当前源码 |
| FR2 | 在 provider 内部,通过共享链接边界渲染的链接使用 component。组件自身的 as 优先于 provider;两者都未提供时,渲染为原生锚点。以最近的 provider 为准。 |
family:navigation-destinations FR2、AV2;当前测试 |
| FR3 | 通过共享链接边界时,component 接收被接受的 href 以及一个等于 href 的 to;除非提供了被接受的显式 to,此时显式 to 优先生效;原生锚点不接收 to。LinkProvider 仅选择 component。 |
family:navigation-destinations FR6;当前测试 |
| FR4 | 被拒绝的链接目标绝不会到达 component;非交互渲染和链接目标检查遵循 family:navigation-destinations FR6 和 spec:AST-005 FR7。 |
family:navigation-destinations FR6;spec:AST-005 FR7 |
| FR5 | 在给定状态下不渲染链接的组件不使用 provider:禁用的 component:Link 永远不会渲染 provider 的组件;它转而渲染哪个元素遵循 component:Link 的 FR1 和 FR5。 |
当前源代码与测试 |
允许的变体¶
- AV1 — 路由器形态。
component可以是基于 href 的,也可以是基于 to 的;两者都接收 FR3 的 props。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变体 |
|---|---|---|
| 无 provider | 原生锚点。 | — |
| 有 provider | component 渲染带有 href 和 to 的可接受链接。 |
路由器。 |
| 嵌套 providers | 内层 provider 优先。 | — |
provider 内的 as |
对于该链接,as 优先。 |
— |
| 被拒绝的目的地 | 惰性原生锚点;不渲染 component。 |
— |
转换与优先级顺序¶
- ORD1 — 链接组件。 先按组件自身的
as,然后是最接近的 LinkProvider,最后是原生锚点。 - ORD2 — 路由器目的地。 先是被接受的显式
to,然后是href。
性能与资源¶
- PR1 — 稳定值。 提供的值仅在
component改变时才改变,因此当 provider 未改变时,消费者不会重新渲染。
可访问性契约¶
- AR1 — 自身不添加语义。 LinkProvider 不添加 role、名称或焦点行为;它提供的链接组件负责根据收到的 props 渲染出可访问的链接。
设计关系¶
LinkProvider 没有视觉输出。没有设计记录约束它。
家族与系统关系¶
family:navigation-destinations将 LinkProvider 列为协作者;共享链接边界会在component看到目的地之前应用该家族的目的地规则。- 每个通过共享链接边界渲染链接的组件都会使用它,例如
component:Link和component:Button的链接模式。如该家族的采用表所列,直接渲染原生锚点的组件则不会。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR2, ORD1 | useLinkComponent.test.tsx 的 provider 用例;Link.test.tsx 的 provider 和 as 用例 |
Provider、嵌套 providers、as 覆盖 |
错误的组件,或外层 provider 胜出,则失败。 | audit:LinkProvider/behavior |
| FR3, ORD2 | useLinkComponent.test.tsx 的 to 套件 |
Provider 和 as;基于 href 和基于 to 的路由器 |
缺少或错误的 to,或原生锚点上的 to,则失败。 |
audit:LinkProvider/behavior |
| FR4 | useLinkComponent.test.tsx 的 scheme、结构化与惰性套件 |
被拒绝的 href 或 to;结构化目的地 |
被拒绝的目的地到达 component,或身份丢失,则失败。 |
audit:LinkProvider/behavior |
| FR5 | Link.test.tsx 的禁用自定义组件用例 |
provider 下的禁用 Link | 通过 component 渲染禁用的 Link 则失败。 |
audit:LinkProvider/behavior |
| AR1 | Link.a11y.chromium.spec.ts 的 provider-路由器状态 |
provider 下的 Link | 失去链接 role 或名称的路由器链接则失败。 | audit:LinkProvider/accessibility |
| FR1, PR1 | 证据缺口:没有测试断言 provider 不添加元素或保持稳定的值 | — | — | audit:LinkProvider/behavior |
决策日志¶
没有组件局部的决策。LinkProvider 应用
family:navigation-destinations。
开放问题¶
无。
内容边界¶
本文件不重复使用方 props 表格/示例、当前审计结果、实现步骤或家族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx