跳转至

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-destinations FR6 和 spec:AST-005 FR7 负责;FR4 指向它们。
  • 组件究竟在何时渲染链接——由各组件负责(例如 component:Link FR1 和 component:Button FR11)。
  • 来自扩大表面的命令式导航——由 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