跳转至

Citation 组件契约

契约概览

领域 契约
公共契约 Citation 从 @astryxdesign/core/Citation 导出;source 和 number 为必填项,variant 默认为 label。
行为 被接受的来源 URL 会在新标签页中渲染为原生锚点。缺失或被拒绝的 URL 会将相同的引用内容渲染为惰性 span。标签和编号变体均保留该导航决策。
对最终用户的影响 读者获得一致的引用标签或编号引用,不会出现被阻止的目标变成导航,或装饰性来源图标被播报两次的情况。
对构建者的影响 构建者显式设置的 role 或 aria-label 本应到达根元素;但目前组件的 role 和翻译后的名称会替换它们(FR5 差距)。
兼容性/就绪状态 已发布行为记录为当前状态;无 API、默认值或输出变更。一个实现差距列于“当前状态影响”下。
审查检查 拒绝以下情况:被阻止的 URL 变成导航;被接受的 URL 失去原生锚点能力;Citation 为惰性引用添加交互式或引用角色;调用方未提供名称时惰性引用缺少可访问名称;装饰性图标被播报;透传或 ref 行为被丢弃;或未经授权新增公共主题目标。
治理规则 family:navigation-destinations/FR1,FR3–FR5,FR7–FR8;architecture:public-component-api/INV1,INV5,INV6,INV8,INV9;architecture:component-theming-surface/INV3–INV6;architecture:component-test-sufficiency/INV1–INV7,INV10–INV11。

此表为审查摘要;下文正文具有权威性。

意图

以可读的标签或紧凑编号呈现对来源的内联引用,并在任何目标到达原生锚点之前应用共享导航决策。

兼容性与迁移

  • 已发布默认值保留:yes — variant="label"。
  • 兼容性类别:记录已发布的行为;无公共 prop、默认值、DOM、目标或样式输出变更。
  • 受控/非受控行为:不适用;Citation 不拥有任何状态。
  • 迁移决策:无

消费者迁移说明应放在消费者文档和发布说明中。

当前状态影响

  • 调用方的 role 和 aria-label 被替换(FR5)。 调用方的 props 在组件的 role 和 aria-label 之前展开,因此调用方显式设置的值永远无法到达根元素;而在根元素处,architecture:public-component-api INV5 允许调用方的显式输入到达元素。根契约测试目前固定了这一替换行为。

所有权边界

拥有

  • 标签和编号的呈现、已接受链接与惰性 span 的渲染、可访问的引用命名、装饰性图标的处理,以及 citation 根目标。
  • 支持的中性 DOM 与样式透传,包括对渲染后锚点或 span 的 ref。

不拥有 / 非目标

  • 接受或阻止哪些导航方案——由 family:navigation-destinations 和 spec:AST-005 拥有。
  • 通用的图片或资源 URL 策略——来源图片仍不属于导航目标契约的范畴。
  • 在 Citation 装饰性包装之外,调用方提供的图标节点的语义或可访问性。
  • Citation 排序、参考文献管理、内容来源或周围正文——由产品调用点拥有。

公共概念

概念 封闭值或状态 含义 可用性 默认值 所有者 稳定性 无效值行为
变体 label、number 选择可见的源标题或编号引用呈现方式。 每次渲染时。 label component:Citation 稳定 被公共类型拒绝
目标 接受、缺失、拒绝 在共享导航决策之后选择原生锚点或惰性 span 根元素。 所有变体。 当 source.url 不存在时为缺失 family:navigation-destinations 当前系列契约 被拒绝的目标渲染为惰性元素
来源图标 节点、src、旧版字符串图标、缺失 在标签变体中提供可选的装饰性来源图标。非字符串节点优先于 src;否则 src 优先于旧版字符串图标 URL。 仅标签变体。 缺失 component:Citation 已发布的兼容性行为 常规 React 渲染行为
编号 数值 提供引用索引,并参与翻译后的无障碍名称。 所有变体。 必需 component:Citation 稳定 被公共类型拒绝

行为和布局契约

ID 不变量 依据
FR1 被接受的 source.url 渲染一个原生锚点,使用原样的目标地址、target="_blank"、rel="noopener noreferrer"、role="doc-noteref"(除非调用方提供了显式 role),以及翻译后的无障碍名称(除非调用方提供了显式 aria-label)(FR5);其 title 为来源标题,若没有标题则为编号。 已发布源码和测试;family:navigation-destinations/FR1,FR3–FR5
FR2 缺失或被拒绝的目标会在非交互 span 中渲染所选的引用呈现;Citation 不会为其添加导航或引用角色。除非调用方提供显式 role,该 span 使用受支持的命名角色,因此其翻译后的标签或调用方的 aria-label 可到达辅助技术(FR5)。拒绝不会从 source.url 派生任何导航属性,不会发明禁用语义,也不会隐藏引用。 已发布源码和测试;family:navigation-destinations/FR4,FR7;WAI-ARIA 命名规则
FR3 标签变体展示来源标题、可选的装饰性来源图标和截断;编号变体将提供的编号展示为紧凑的可视引用。 已发布源码、文档、测试和 stories
FR4 节点图标优先于 src,而 src 优先于旧版字符串 icon。每个图标路径都保持在 aria-hidden 包装器内作为装饰。 已发布的兼容性行为和测试
FR5 两个根分支都保留受支持的 DOM 属性、className、style、xstyle、data-* 属性以及声明的 HTMLElement ref,并且调用方的显式 role 或 aria-label 会到达根元素(architecture:public-component-api INV5)。实现缺口:组件的角色和翻译后的名称会替换调用方的值(当前状态影响)。 architecture:public-component-api/INV5,INV6,INV8;回归测试
FR6 Citation 在渲染根节点上保留一个公共的 citation 目标,反映 variant,并且未经批准的主题契约变更,不暴露任何内部图标或文本目标。 随附文档/源码;architecture:component-theming-surface/INV3–INV6
FR7 组件自有的无障碍文本来自翻译目录;可见的源文本和数字内容仍为调用方提供的数据。 随附源码和 i18n 基础设施

允许的变体

  • AV1 — 主题绘制。 citation 根目标可以更改支持的视觉绘制,而不改变 variant、目的地、角色或无障碍名称行为。
  • AV2 — 调用方内容。 源标题、数字值、图片 URL 和节点图标可在已发布的公共类型范围内变化。
  • AV3 — 原生目的地行为。 接受的相对路径、片段、协议相对、HTTP(S)、mailto、tel 及安全自定义目的地保留原生浏览器处理方式和组件现有的新标签页关系。

代表性状态

状态 必需不变量 允许的变体
链接标签 原生锚点、源标题、可选装饰性图标,以及在调用方未提供 aria-label 时的翻译后无障碍名称。 源内容和根主题绘制。
链接数字 原生锚点、数字可见引用,以及在调用方未提供 aria-label 时的翻译后无障碍名称。 数字和根主题绘制。
缺失或被拒绝的 URL 具有相同选中呈现的惰性 span;在调用方未提供 role 时,使用受支持的命名角色;Citation 不添加任何导航或引用角色或属性。 源内容和根主题绘制。
节点或图片图标 图标保持装饰性,且仅出现在标签变体中。 调用方自有的图稿或源图片。

转换与优先级顺序

  • ORD1 — 目的地。 source.url → 共享安全 URL 决策 → 原生锚点或惰性 span。
  • ORD2 — 图标。 非字符串 source.icon → source.src → 旧版字符串 source.icon → 无图标。
  • ORD3 — 根属性。 调用方透传 → 组件自有的测试 id 和导航属性,以及组件的角色和名称(除非调用方提供自己的;FR5;目前组件会替换调用方的,即 FR5 差距)→ 主题和样式组合。

性能与资源

  • PR1 — 纯渲染。 Citation 不拥有任何状态、Effect、监听器、观察器、计时器或外部资源生命周期。
  • PR2 — 图片。 Citation 可能输出一张调用方提供的源图片;获取、验证和资源策略不由导航契约决定。

无障碍契约

  • AR1 — 链接引用。 接受的目的地暴露一个带有 doc-noteref 的原生链接(调用方未提供 role 时),以及翻译后的 Citation {number}: {title} 无障碍名称(调用方未提供 aria-label 时,FR5)。
  • AR2 — 惰性引用。 对于缺失或被拒绝的目的地,Citation 不添加任何交互式或导航角色或属性;调用方的显式 role 会到达 span(FR5)。在调用方未提供 role 时(FR5),惰性 span 使用 role="group",使其翻译后的引文标签仍作为无障碍名称,包括可见数字没有源文本的情况。
  • AR3 — 装饰性来源标记。 源图片和节点图标绘制对无障碍树保持隐藏,以免与引文名称重复。
  • AR4 — 焦点所有权。 原生锚点仍是语义焦点的所有者。Citation 不会向惰性 span 添加焦点所有者。

设计关系

| 解剖结构或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 | | Root | 绘制标签胶囊或编号徽章,并拥有 citation 目标。 | 已发布实现的实际呈现及公开文档 | 辅助参考 | FR1–FR3, FR5–FR6 | | Source icon | 呈现调用方可选提供的来源标识,且不附带无障碍语义。 | 已发布实现的实际呈现 | 装饰性 | FR3–FR4, AR3 | | Label or number | 呈现来源标题或紧凑索引。 | 已发布实现的实际呈现及公开文档 | 主要引用内容 | FR3, FR7 |

Citation 仅暴露文档化的 citation 根目标。内部图标与文本部分没有公共目标。

家族与系统关系

  • family:navigation-destinations 负责 source.url 的接受/阻止结果,包括原生锚点汇点以及保留已接受的浏览器行为。
  • spec:AST-005 拥有规范化的阻止协议规则,该家族将其投射到 Citation 上。
  • architecture:public-component-api 负责导出稳定性、透传、样式组合、ref 可达性以及组件自有 prop 的优先级。
  • architecture:component-theming-surface 负责公共目标的资格限定与放置。
  • architecture:component-test-sufficiency 负责每个关键分支和公共承诺的变异敏感证据。
  • architecture:interaction-modality 负责共享的模态行为,而 Citation 的原生锚点仍是其自身的语义焦点所有者。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
FR1–FR2, AR1–AR2 Citation.test.tsx 目标套件和 safeUrl.test.ts 矩阵 已接受、缺失、阻止协议、规范化阻止文本 被阻止的 URL 会产生导航,已接受的 URL 会丢失其目标或原生交互能力,或者当调用方未提供 role 时,惰性引用丢失其受支持的命名角色。 audit:Citation/navigation
FR3–FR4, AR3 Citation.test.tsx 变体与图标套件 标签、编号、无图标、节点图标、src、旧版字符串 icon 错误可见变体会渲染、图标优先级发生改变,或装饰性来源绘制进入无障碍树。缺口:没有测试覆盖标签的截断。缺口:没有测试覆盖 src 优先于旧版字符串 icon 的情况。 audit:Citation/behavior
FR5 Citation.test.tsx 根契约套件与严格类型/lint 校验 带 ref、DOM props、class、内联样式和 xstyle 的 anchor 和 span 根 任一根目标丢失受支持的透传或 ref 行为。缺口:根契约测试断言组件的 role 和 name 会替换调用方的 role 和 aria-label,这固定了 FR5 缺口。 audit:Citation/api
FR6 Citation.test.tsx 类名测试;themingTargets.test.ts 链接根与惰性根;两种变体 根目标从类名测试中消失会导致测试失败。themingTargets.test.ts 只能捕获重命名或未文档化的目标。缺口:没有测试断言 variant 在目标上的反映。 audit:Citation/theming
FR7 Citation.test.tsx 无障碍名称断言 链接标签与编号 名称丢失来源或编号上下文则失败。缺口:没有测试运行非英语目录,因此绕过翻译的文本会通过。 audit:Citation/i18n
RTL N/A verified-not-applicable.json 源哈希记录 标签与编号 stories;链接/惰性来源路径;图标/无图标 出现方向敏感字形、物理内联位置、排序、滚动、覆盖层或水平键盘行为,且没有 RTL 证据。 audit:Citation/rtl
All Citation.stories.tsx;稳定视觉基线 core-citation--label 已记录的变体与来源状态 变更后的标签引用会以已变更状态返回,供审查。 audit:Citation/testing

决策日志

DEC-1 — 惰性引用使用非交互式命名角色

参考: component:Citation/DEC-1 决策者: cixzhang, 2026-10-01

现有的惰性 span 使用 role="group",因此其翻译后的 aria-label 有效,且不会产生导航、焦点或视觉/DOM 子元素。无角色的通用 span 无法被命名;group 是一种非交互式、支持命名的角色,是保留当前根节点和呈现的最小恢复方案。

如果有受支持的平台原语能够在不产生分组边界播报的情况下命名惰性内联内容,或者有证据表明分组语义会影响文献引用的大规模阅读,则应重新考虑该机制。

未决问题

无。

内容边界

本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤、导航系统原理或资源策略。它链接到这些内容的所属方。

契约 验证 代表性状态 变异或失败预期 审计部分
AR4, PR1, PR2 源码审查 链接且惰性的根;图像图标 缺口:没有任何自动化检查会在 Citation 为惰性 span、状态、副作用或监听器添加焦点所有者,或产生多个来源图像时失败。 audit:Citation/behavior

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx