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-086FR2、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