跳转至

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