MetadataList 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | children(MetadataListItem 条目)、columns、label(position、width)、maxNumOfItems、orientation、title、根 BaseProps、ref。 |
| 行为 | 一个描述列表,以单列、多列或换行排列的形式展示标签和值对,并带有可选的“显示更多/显示更少”切换控件。 |
| 终端用户影响 | 用户在可预测的网格中快速浏览带标签的事实,辅助技术将每个标签与其值一起朗读。 |
| 构建者影响 | 无;该记录描述的是已发布行为。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出更改。 |
| 审查检查项 | 拒绝不是 dl 的列表、缺少展开状态或受控列表的切换控件、未本地化的切换标签,或可被覆盖的反射。 |
| 治理规则 | architecture:public-component-api INV5–INV8;architecture:component-theming-surface;WCAG 2.2 SC 1.3.1 和 4.1.2。 |
此表是审查视图;以下正文具有权威性。
设计意图¶
MetadataList 将只读的键值事实以描述列表的形式呈现。它负责其条目的排列、传递给条目的标签位置,以及可选的、用于折叠长列表的展开控件;调用方拥有事实数据。
使用方语法和示例见 MetadataList.doc.mjs。
兼容性与迁移¶
- 已发布默认值保留:
yes— 单列、纵向、标签位于起始位置、无折叠。 - 兼容性类别:记录已发布行为;不改变任何公共 prop、默认值、DOM、目标或样式输出。
- 受控/非受控行为:展开控件的展开状态为非受控。
- 迁移决策:无
使用方迁移说明应写入使用方文档和发布说明。
所有权边界¶
拥有
- 根元素、其
metadata-list目标、可选标题、dl以及“显示更多”和“显示更少”切换控件。 - 列布局、方向,以及其条目所读取的标签位置和宽度。
不拥有 / 非目标
- 每个条目的标签和值标记 — 由
component:MetadataListItem所有。 - 展示的事实及其格式 — 由调用方所有。
- 可编辑字段 — 由表单组件所有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 列 | single;multi;正数 |
单列、自动填充列或恰好 N 列。 | 仅纵向 | single |
component:MetadataList |
稳定 | 1 视为 single;小于 1 的数字回退至 multi 模板。 |
| 方向 | vertical;horizontal |
条目网格,或一排换行的堆叠条目。 | 始终 | vertical |
component:MetadataList |
稳定 | 封闭联合类型;被类型系统拒绝。 |
| 标签位置 | start;top |
标签位于其值旁边,或堆叠在其上方。 | 仅纵向 | multi 或大于 1 的数字时为 top,否则为 start |
component:MetadataList |
稳定 | 横向始终堆叠。 |
| 标签宽度 | number (px);CSS 长度字符串 | 标签轨道的宽度;在 multi 下,它会将自动填充网格替换为每行一个标签和值对。 |
纵向、标签位于起始位置、单列或 multi |
内容宽度 | component:MetadataList |
稳定 | — |
| 折叠 | 正数;未设置 | 在“显示更多”切换控件之前展示的条目数。 | 仅纵向 | 未设置 | component:MetadataList |
稳定 | 横向时忽略。 |
| 标题 | ReactNode;未设置 | 显示在列表上方的内容。 | 始终 | 未设置 | component:MetadataList |
稳定 | — |
行为和布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | MetadataList 渲染一个根 div,承载 metadata-list 目标,该目标反映 columns 和 orientation,包含可选的标题、一个条目 dl,以及当列表折叠时的切换按钮。标题以纯内容形式渲染在列表上方,间距为 --spacing-3;它不是标题元素,也不为列表命名。 |
当前源码和测试 |
| FR2 | 垂直方向、单列且标签位于开头时,是双轨道网格(标签 auto,值 minmax(0, 1fr)),行间距为 --spacing-2、列间距为 --spacing-4,并采用基线对齐;标签的 width 会替换标签轨道,而在 multi 且标签位于开头时,width 会用相同的双轨道替换自动填充网格。单列且标签位于顶部时,是单一轨道,间距为 --spacing-3。multi 自动填充最小宽度为 280px 的列,列间距为 --spacing-4。大于 1 的数字 N 会精确生成 N 列;当标签位于顶部时每列为 1fr,当标签位于开头时每列为标签 auto 与值 minmax(0, 1fr) 的配对,并忽略标签的 width;小于 1 的数字则回退到 multi 模板。 |
当前源码和测试 |
| FR3 | 标签位置默认为 top(适用于 multi 或大于 1 的数字),否则(包括小于 1 的数字)默认为 start,调用方传入的 position 优先。水平方向将条目排列在一行可换行的行中,间距为 --spacing-4,将每个标签堆叠在其值上方,并忽略 columns 和 maxNumOfItems。 |
当前源码和测试 |
| FR4 | 当处于垂直方向且条目数超过 maxNumOfItems 时,仅渲染前 maxNumOfItems 个条目,随后是一个原生的“显示更多”按钮,带 aria-expanded="false",并用 aria-controls 指向 dl。激活该按钮会渲染所有条目,并切换为“显示更少”,aria-expanded="true";再次激活则折叠。焦点保持在按钮上。 |
当前源码和测试;architecture:public-component-api |
| FR5 | ref、DOM、数据、ARIA 和事件属性以及 xstyle、className、style 都会到达根元素或在根元素上组合;反映出的 data-columns 和 data-orientation 会替换调用方的值。 |
当前源码和测试;architecture:public-component-api INV5–INV8 |
允许的变体¶
- AV1 — 事实。 任何
MetadataListItem内容都可以填充该列表。 - AV2 — 标题。 任何
ReactNode(包括调用方的标题)都可以作为标题。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 单列 | 标签与取值轨道;标签位于起始位置。 | 标签宽度。 |
| N 列 | 恰好 N 列;默认标签在顶部。 | N。 |
| 水平 | 一个可换行的行;标签堆叠;无切换控件。 | — |
| 折叠 | 前 maxNumOfItems 个条目;“显示更多”;aria-expanded="false"。 |
区域设置。 |
| 展开 | 每个条目;“显示更少”;aria-expanded="true"。 |
区域设置。 |
转换与优先级顺序¶
- ORD1 — 标签位置。 水平 → 顶部;否则,当
multi或数值大于 1 时,调用方的position→top;否则 →start。 - ORD2 — 列数。 水平 → 无网格;N 大于 1 → 恰好 N 列(顶部标签对应 N 条轨道,起始标签对应 N 个标签与取值对);起始标签的
width→ 对应的标签轨道;否则为静态模板。
性能与资源¶
- PR1 — 仅本地状态。
MetadataList持有一个展开标志和一个生成的 id,并且不添加任何监听器、观察器、定时器或测量。
无障碍契约¶
- AR1 — 描述列表语义。 条目是同一个
dl内的dt和dd配对,因此辅助技术会将每个标签与其取值一起读出(WCAG 2.2 SC 1.3.1)。 - AR2 — 展开状态。 切换控件是一个原生按钮,暴露其展开状态及所控制的列表(WCAG 2.2 SC 4.1.2)。
- AR3 — 本地化标签。 切换控件的文本来自翻译目录,绝不在组件内拼装。
设计关系¶
| 结构或状态 | 设计要求 | 权威来源 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 标题 | 列表上方的可选内容。 | 当前源码和文档 | 辅助 | FR1 |
| 标签 | 每个条目的键。 | component:MetadataListItem |
辅助 | FR2, FR3 |
| 元数据 | 每个条目的值。 | component:MetadataListItem |
主要 | FR2, FR3 |
| 展开控件 | 以强调色显示“显示更多”或“显示更少”。 | 当前源码和文档 | 辅助 | FR4 |
主题化:根元素带有 metadata-list 目标,该目标反映 columns 和 orientation;每个条目带有 metadata-list-item 目标(component:MetadataListItem)。MetadataList.doc.mjs 没有为 metadata-list 目标命名任何根结构部分,因此此处不声明结构主题化块;标题、值单元格和展开控件均不携带目标。
家族与系统关系¶
component:MetadataListItem负责条目标记,并读取本记录解析出的标签位置。architecture:component-theming-surface负责目标与结构映射。architecture:public-component-api负责调用方输入路由;FR5 应用该路由。spec:AST-009负责无障碍树证据;验证映射指出了其缺口。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1 | MetadataList.test.tsx 描述列表、dl 和标题测试;稳定视觉基线 core-metadatalist--basic(中性主题与探针主题) |
条目;标题 | 缺少 dl、dt 或 dd,或缺少标题,则失败;默认布局发生更改时会以更改后的状态返回以供审查。缺口:没有无障碍树检查来证明术语与定义的配对(spec:AST-009 FR3)。 |
audit:MetadataList/a11y |
| FR2, ORD2 | MetadataList.test.tsx 数字列和标签宽度测试 |
N 列,带顶部标签和起始标签;multi;自定义宽度 |
N 列或标签宽度的内联网格模板错误,或 multi 的 repeat( 内联模板错误,则失败。缺口:静态单列和 multi 模板及间距除了默认基线外没有单元检查。没有测试覆盖 N 列带起始标签时的宽度、multi 上的宽度,或小于 1 的数字。 |
audit:MetadataList/layout |
| FR3, ORD1 | MetadataList.test.tsx 方向和默认位置测试 |
水平;省略位置;columns={2} |
没有堆叠标签或带有切换开关的水平列表,或默认位置错误,则失败。没有测试覆盖 multi 的顶部标签默认值,或小于 1 的数字的起始标签默认值。 |
audit:MetadataList/layout |
| FR4, AR2, AR3 | MetadataList.test.tsx 显示更多、切换和本地化测试 |
折叠;展开;法语目录 | 缺少切换开关、隐藏条目被渲染、切换开关不能展开和折叠,或法语目录下出现英文文本,则失败。缺口:没有测试断言 aria-expanded、aria-controls,或焦点停留在按钮上。 |
audit:MetadataList/behavior |
| FR5 | MetadataList.test.tsx 根节点透传、事件和自有元数据测试 |
aria-label、id、数据;点击;冲突反射 |
属性或处理程序被丢弃,或调用方的 data-columns 或 data-orientation 优先,则失败。缺口:没有测试覆盖 ref、className、style 或 xstyle 合并顺序。 |
audit:MetadataList/api |
| PR1 | 源码审查 | 所有状态 | 缺口:如果 MetadataList 添加监听器、计时器或测量,没有任何自动化检查会失败。 | audit:MetadataList/behavior |
| 主题目标 | themingTargets.test.ts |
根目标和条目目标 | 重命名或未记录的目标会失败。缺口:如果并排的 dt 失去 metadata-list-item 目标,没有任何检查会失败。 |
audit:MetadataList/theming |
| RTL 关系 | RTL 审计精选的 D2 目标(apps/storybook/rtl-audit/targets.json,针对 MetadataList / Basic) |
侧边标签;LTR 和 RTL | 如果标签列不在值列的内联起始位置,则 D2 失败。 | audit:MetadataList/i18n-rtl |
决策日志¶
无记录。该记录描述的是已发布行为。
未决问题¶
无。
内容边界¶
本文件不会重复使用方 prop 表/示例、当前审计结果、实现步骤或入口标记。它链接到这些内容的所属文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx