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