跳转至

MetadataListItem 组件契约

契约概览

区域 契约
公共契约 label(字符串)、children(值)、可选的 icon、根级 BaseProps 和 ref。
行为 一个标签和值对,在列表的网格中并排渲染为 dt 和 dd,或在包装器内堆叠渲染。
终端用户影响 人们会在每个值的旁边或上方阅读每条事实的标签,辅助技术会将它们配对。
构建方影响 无;本记录描述的是已发布的行为。
兼容性/就绪状态 已发布的行为记录为当前状态;无 API、默认值或输出变更。
审查检查 拒绝不是 dt 和 dd 的配对、在并排布局中使用包装器,或使调用方 props 脱离承载 ref 的元素的用法。
约束规则 architecture:public-component-api INV5–INV8;architecture:component-theming-surface;WCAG 2.2 SC 1.3.1。

此表是审查投影;以下正文为权威内容。

意图

MetadataListItem 是 MetadataList 内部的一个键值条目。它拥有该条目的术语和定义标记及其类型;调用方拥有标签、图标和值。

使用方语法和示例属于 MetadataListItem.doc.mjs。

兼容性与迁移

  • 已发布的默认行为保持不变:yes — 在堆叠列表之外时为并排布局。
  • 兼容性类别:记录已发布的行为;无公共 prop、默认值、DOM、目标或样式输出变更。
  • 受控/非受控行为:不适用
  • 迁移决策:无

使用方迁移说明属于使用方文档和发布说明。

所有权边界

拥有

  • 该条目的 dt 和 dd、堆叠包装器,以及 component:MetadataList 映射的 metadata-list-item 目标。
  • 标签和值的类型、图标槽位,以及调用方输入所落定的位置。

不拥有 / 非目标

  • 标签位置、列数和方向 — 由 component:MetadataList 拥有。
  • 标签、图标和值的内容 — 由调用方拥有。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 拥有者 稳定性 无效值行为
标签 string 该条目的键。 始终 — 调用方 稳定 —
值 ReactNode(children) 该条目的值。 始终 — 调用方 稳定 —
图标 ReactNode;未设置 显示在标签之前的内容。 始终 未设置 调用方 稳定 —
布局 并排;堆叠 由父列表设置,而非由条目自身设置。 始终 并排 component:MetadataList 稳定 —

行为与布局契约

ID 不变式 依据
FR1 在并排布局中(标签位于起始位置,或在 MetadataList 外部),该条目渲染一个包含图标和标签的 dt,然后是一个包含值的 dd,作为列表网格的直接子元素。dt 承载 metadata-list-item 目标、ref 以及调用方的 props 和样式输入;data-testid 在 dt 上变为 <id>-label,在 dd 上变为 <id>-value。两个单元格至少 24px 高,并能断开长单词。 当前源码和测试
FR2 在堆叠布局中(标签在顶部,或水平列表),该条目渲染一个 div 包装器,承载 metadata-list-item 目标、ref、data-testid 以及调用方的 props 和样式输入,将 dt 置于 dd 之上,间距为 --spacing-0-5。 当前源码和测试
FR3 标签使用中等字重的正文字体,颜色为次要文本色;值使用正文字体,颜色为主要文本色。图标位于标签之前,间距为 --spacing-2。 当前源码和文档
FR4 xstyle、className 和 style 在承载 target 的元素上于组件样式之后组合,且调用方 props 在组件自身属性之后到达该元素。 当前源码和测试;architecture:public-component-api INV5–INV8

允许的变体

  • AV1 — 内容。 任何字符串都可以作为标签;任何 ReactNode 都可以作为图标或值。

代表性状态

状态 必需的不变量 允许的变体
并排 dt 和 dd 作为网格兄弟元素;target、ref 和 props 位于 dt 上。 内容。
堆叠 一个包装器承载 target、ref 和 props,将 dt 置于 dd 之上。 内容。
带图标 图标在 dt 内部位于标签之前。 图标。

转换与优先级顺序

  • ORD1 — 布局。 父列表的水平方向或 top 标签位置 → 堆叠;否则并排。

性能与资源

  • PR1 — 无资源。 MetadataListItem 读取其父列表的标签位置和方向,并且不持有任何状态。

无障碍契约

  • AR1 — 术语与定义。 标签是 dt,值是其 dd,因此辅助技术会将它们配对(WCAG 2.2 SC 1.3.1)。图标本身不添加任何语义。

设计关系

结构或状态 设计要求 呈现权威 层级角色 组件契约
标签 次要颜色中等键。 当前源码和文档 辅助 FR1–FR3
元数据 主要颜色值。 当前源码和文档 突出 FR1–FR3

主题化:dt(并排)或包装器(堆叠)承载 metadata-list-item target,该 target 由 MetadataList.doc.mjs 声明并由 component:MetadataList 映射。MetadataListItem.doc.mjs 未声明自身的结构,因此此处不声明结构主题化块。

家族与系统关系

  • component:MetadataList 负责布局、标签位置和目标映射。
  • architecture:public-component-api 负责调用方输入的路由;FR4 应用它。
  • spec:AST-009 负责可访问性树证据;验证映射指出了其缺口。

验证映射

契约 验证 代表性状态 变异或失败预期 审计部分
FR1 MetadataList.test.tsx 的 item、label-width 和 pass-through-target 测试 并排 缺少标签或值、dt 或 dd 不是 dl 的直接子元素、-label 和 -value 测试 id 错误,或 props 或点击处理不再作用于 dt,则失败。缺口:没有测试附加 ref,且 24px 最小高度没有检查。如果并排的 dt 丢失 metadata-list-item target,则没有任何检查会失败。 audit:MetadataListItem/layout
FR2 MetadataList.test.tsx 的 stacked 和 stacked pass-through 测试 堆叠 缺少包装器、dt 或 dd,或 props 不再作用于包装器,则失败。缺口:堆叠间距没有检查。没有测试将 ref 附加到堆叠包装器上。 audit:MetadataListItem/layout
FR3 MetadataList.test.tsx 的 icon 测试 带图标 缺少图标则失败。缺口:标签和值的类型与颜色以及图标间距没有自动化检查。 audit:MetadataListItem/design
FR4 MetadataList.test.tsx 透传测试 aria-label、id、data;click 属性或处理程序缺失会导致失败。差距:没有测试覆盖 className、style 或 xstyle 合并顺序。 audit:MetadataListItem/api
AR1 MetadataList.test.tsx 角色查询 术语和定义 DOM 中缺少 term 或 definition 角色会导致失败。差距:没有可访问性树检查来证明配对关系(spec:AST-009 FR3)。 audit:MetadataListItem/a11y
PR1 源代码审查 每个状态 差距:如果 MetadataListItem 添加状态,没有自动化检查会失败。 audit:MetadataListItem/behavior
RTL 关系 RTL 审计精选 MetadataList / Basic 上的 D2 目标(apps/storybook/rtl-audit/targets.json) 侧边标签和值;LTR 和 RTL 标签不在其值的内联起始位置会导致 D2 失败。 audit:MetadataListItem/i18n-rtl

决策日志

无记录。该记录描述的是已交付的行为。

未决问题

无。

内容边界

本文件不重复消费方属性表/示例、当前审计结果、实施步骤或列表布局规则。它链接到相应的负责人。

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