跳转至

EmptyState 组件合约

合约一览

领域 合约
公共合约 EmptyState 渲染一个必填标题,外加可选的描述、装饰性图标和调用方拥有的操作,且位于单个根节点中,不带 live 角色;调用方可选择标题级别和紧凑布局。
行为 Null、undefined、布尔值和空字符串等可选值不会创建插槽包装器。渲染内容按图标、文本、操作的顺序排列;紧凑布局会减少间距并垂直堆叠操作。
终端用户影响 用户能够看到有名称的空内容消息和任何后续操作,而不会因浅层为空的可选值产生空白间隙;标题能融入周围的文档大纲。
构建者影响 无;该记录描述的是已发布的行为。
兼容性/就绪状态 已发布的行为记录为当前状态;无 API、默认值或输出变更。
审查检查 拒绝缺少标题、将信息性图标作为装饰性隐藏、仍然改变布局的浅层为空可选标量、丢弃根级 prop/ref/style,或没有部件结构的主题目标。
治理规则 architecture:public-component-api INV1 和 INV5–INV9;architecture:component-theming-surface INV2–INV6;architecture:component-test-sufficiency INV1–INV7、INV10–INV11;WCAG 2.2。

此表是审查投影;以下正文具有权威性。

意图

EmptyState 为原本为空的内容区域提供语义化标题、支持性上下文、可选装饰性视觉元素,以及可选且由调用方拥有的后续操作。

兼容性与迁移

  • 已发布的默认值保留:yes — 标题级别 3、默认布局、根节点上没有 live 角色。
  • 兼容性类别:记录已发布的行为;无公共 prop、默认值、DOM、目标或样式输出变更。
  • 受控/非受控行为:不适用
  • 迁移决策:无

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

所有权边界

拥有

  • 根节点、内容顺序、标题元素以及默认/紧凑布局;
  • 将图标插槽作为装饰性内容对辅助技术隐藏;以及
  • 可选插槽是否创建组件拥有的包装器和间距。

不拥有 / 非目标

  • 消息文案、图标含义、操作控件或操作行为 — 这些属于产品调用方及其提供的组件;
  • 页面级标题顺序 — 调用方为其文档选择 headingLevel;或
  • 错误、加载或已填充内容的行为。

公共概念

概念 封闭值或状态 含义 变体/方向/状态下的可用性 默认值 所有者 稳定性 无效值行为
title string 空区域的标题内容。 所有 必填 component:EmptyState 稳定 类型拒绝
description string 或不存在 标题下方的可选支持性上下文。 所有 不存在 component:EmptyState 稳定 nullish 和空字符串值会省略该部分
icon React 节点或不存在 可选的调用方视觉元素,作为文本消息旁的装饰性内容展示。 所有 不存在 产品调用方 稳定 nullish、布尔值和空字符串值会省略该插槽
actions React 节点或不存在 消息下方的可选调用方拥有的后续操作。 所有 不存在 产品调用方 稳定 nullish、布尔值和空字符串值会省略该插槽
标题级别 1 到 6 标题在周围文档大纲中的 HTML 标题级别。 所有 3 产品调用方 稳定 类型拒绝
布局变体 default、compact 紧凑布局会减少间距并将操作插槽垂直堆叠。 所有 default component:EmptyState 稳定 类型拒绝

行为与布局合约

ID 不变式 依据
FR1 当图标、文本组和操作存在时,组件 MUST 渲染一个包含这些内容的根节点,并按照该阅读顺序排列。组件 MUST NOT 向根节点添加 live role 或 aria-live。 当前实现与消费者文档;spec:AST-086 FR2;WCAG 2.2 SC 1.3.2
FR2 必需的标题 MUST 按照调用方选择的标题级别渲染,且不改变组件的视觉类型角色。 当前实现、测试与消费者文档;WCAG 2.2 SC 1.3.1 和 SC 2.4.6
FR3 null、undefined、boolean 和空字符串等可选值 MUST NOT 创建包装器、布局间隙或辅助技术节点;浅层非空的容器保持包装状态。 React 的直接子节点渲染语义;已确立的公共可选插槽接口
FR4 当插槽不存在时,装饰性图标包装器 MUST 不存在;渲染时 MUST 对辅助技术隐藏。 当前实现与测试;WCAG 2.2 SC 1.1.1
FR5 根 DOM/数据/ARIA/事件属性、ref、className、style 和 xstyle MUST 到达根节点并在其上组合。 architecture:public-component-api INV5–INV8
FR6 紧凑布局 MUST 减少组件间距并堆叠操作插槽,同时保持内容顺序和根语义不变。 当前实现、测试与消费者文档

允许的变化

  • AV1 — 调用方内容。 消息措辞、装饰性图形和操作组合可在产品调用点变化。
  • AV2 — 主题绘制。 主题控制的绘制和排版可通过文档化目标变化,而解剖结构和内容顺序保持稳定。

代表性状态

状态 必需不变量 允许的变化
仅标题 根节点和所选标题级别保持不变 消息措辞
描述 辅助文本位于标题之后 文本长度和换行
装饰性图标 视觉元素先于文本,并对辅助技术隐藏 由调用方提供的图形
操作 调用方控件位于文本组之后 一个或多个调用方拥有的控件
紧凑 减少间距和垂直操作保持语义 主题绘制和调用方内容
浅层为空的可选标量 nullish、boolean 和空字符串值不产生包装器 哪个可选插槽接收该值

转换与优先级顺序

  • ORD1 — 根组合。 组件语义和主题元数据与组件样式组合,然后在共享合并契约下与消费者 xstyle、className 和 style 组合。组件不设置 role,因此调用方的 role 原样到达根节点。

性能与资源

  • PR1 — 自身无资源。 EmptyState 自身不持有状态、监听器、观察器或计时器;其文本周围的共享播报包装器拥有宣告它的观察逻辑(spec:AST-086)。

无障碍契约

  • AR1 — 标题语义。 标题是位于调用方所选级别的标题。
  • AR2 — 装饰性视觉。 图标插槽对辅助技术隐藏;调用方将所有必要含义保留在标题或描述中。
  • AR3 — 无实时区域;出现时播报。 EmptyState 不向根节点添加 live role 或 aria-live,也不移动焦点。如果它在文档加载完成之前(或水合期间)渲染或变更,则不会播报任何内容。当它稍后出现或其消息变更时,通过共享的 polite 频道播报一次其消息(spec:AST-086 FR2、FR11)。该消息为标题和描述,不包含对辅助技术隐藏的内容;操作标签不属于其中。操作控件保留自己的名称、角色和行为。

设计关系

当前没有设计记录管辖 EmptyState 特有的表示。视觉判断仍作为证据,而非产品权威。

主题化解剖结构

{
  "Container": {"target": "empty-state"},
  "Icon": {
    "none": {
      "reason": "intentional: caller-supplied decorative content keeps its own styling and has no component-owned paint target"
    }
  },
  "Title": {"target": "empty-state-title"},
  "Description": {"target": "empty-state-description"},
  "Actions": {
    "none": {
      "reason": "intentional: caller-supplied controls keep their own component targets and behavior"
    }
  }
}

家族与系统关系

当前没有家族记录拥有 EmptyState 特有的行为。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
------------------- -------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --------------------------
FR1, FR3, FR4, AR2 EmptyState.test.tsx 插槽、顺序、装饰性图标、空插槽和实时角色测试;稳定的视觉基线 core-emptystate--default 仅标题;所有插槽;缺失和浅空插槽 为缺失或浅空插槽添加包装器、更改插槽顺序、图标未对辅助技术隐藏,或根元素上的实时角色,均会失败;更改的默认布局会作为变更返回以供审查。差距:没有辅助功能树检查证明隐藏的图标或标题(spec:AST-009 FR3)。 audit:EmptyState/a11y
FR2, AR1 EmptyState.test.tsx 标题测试 默认级别 3;每个级别 不是所选标题元素的标题会失败。差距:没有检查标题在每个标题级别上都保持一种字体样式。 audit:EmptyState/a11y
AR3 EmptyState.announce.test.tsx 随页面渲染;稍后出现;iframe;在实时容器内;消息更改;服务器渲染和水合;隐藏和显示 在加载或水合期间的公告、在稍后出现或更改时缺失或重复的公告、消息中的隐藏文本,或实时容器内的公告,均会失败。差距:没有测试断言当 EmptyState 出现时焦点保持在原位。 audit:EmptyState/a11y
FR5, ORD1 EmptyState.test.tsx ref、data-testid 和根组合测试 DOM、数据、事件、样式输入;调用方角色;ref 丢失的输入、被替换的调用方角色,或不是 div 的 ref 会失败。差距:ref 测试仅检查 ref 是 div,而不是检查它是根元素。没有测试断言调用方的 xstyle 遵循组件样式。 audit:EmptyState/api
FR6 EmptyState.test.tsx 紧凑和主题目标测试 默认和紧凑 未在根、标题和描述上体现的紧凑布局,或改变插槽顺序的紧凑布局会失败。差距:减少的间距和堆叠的操作没有自动化检查。 audit:EmptyState/layout
PR1 源代码审查 每个渲染路径 差距:如果 EmptyState 添加了自己的状态、监听器或计时器,没有自动化检查会失败。 audit:EmptyState/code
Theming anatomy map scripts/check-knowledge.mjs;themingTargets.test.ts 消费者解剖和当前目标 缺失、多余或过时的映射会导致存储库验证失败。 audit:EmptyState/theming

决策日志

无记录。该记录描述了已发布的行为。

未决问题

无。

内容边界

本文件不重复使用方 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则。它链接到各自的所属方。

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