跳转至

AvatarStatusDot 组件契约

契约概览

领域 契约
公共契约 用于 Avatar 的 status 插槽的状态点,包含 variant(默认 success)、可选 label 和可选 icon。
行为 该点根据所属 Avatar 以三档尺寸自我调整大小,将每个内置 variant 与不同的形状配对,并将其 label 报告给 Avatar。
最终用户影响 屏幕阅读器用户会在 avatar 名称中听到状态;有视力的用户除了颜色之外,还能通过形状区分不同状态。
构建者影响 无;该记录描述的是已发布行为。
兼容性/就绪状态 已发布行为记录为当前状态;无 API、默认值或输出变更。一处实现差距列于“当前状态影响”下。
审查检查 拒绝仅靠颜色区分的内置 variant、暴露的图形或图标,或停止传递给所属 Avatar 的 label。
治理规则 architecture:component-theming-surface/INV2,INV6,INV14;architecture:public-component-api/INV5,INV6,INV8;WCAG 2.2 1.4.1。

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

意图

AvatarStatusDot 渲染通过 Avatar 的 status 插槽组合而成的紧凑状态指示器。它负责该点的大小档位、内置的非颜色标记,以及将其 label 报告到所属 Avatar 的可访问名称中。

兼容性与迁移

  • 已发布的默认值被保留:是
  • 兼容性类别:记录已发布行为;无公共 prop、默认值、DOM、目标或样式输出变更
  • 受控/非受控行为:不适用
  • 迁移决策:无

消费者迁移说明应归属于消费者文档和发布说明。

当前状态影响

  • 无回退的扩展 variant(FR6)。 AvatarStatusDotVariantMap 允许主题新增名称,但没有内置规则的新名称会渲染为无填充、墨色或图形的点几何及 data-variant。调用方传入带 style 颜色的 icon 可以覆盖中档和大档,但小档会丢弃图标,且没有任何东西提供与主题无关的安全基线。 architecture:component-theming-surface INV14 要求可扩展的视觉轴具有安全的主题无关基线。

所有权边界

拥有

  • 已绘制的状态点根元素及其 avatar-status-dot 目标。
  • 内置的填充、环形和减号视觉分支,以及 avatar-status-dot-glyph 目标。
  • 从 Avatar 已解析的数值尺寸解析大小档位。
  • 将其可选状态 label 报告到 Avatar 的可访问名称中。

不拥有 / 非目标

  • Avatar 身份、图像回退、形状、状态放置或交互行为——由 component:Avatar 拥有。
  • 调用方提供的图标内容的含义或图形。

公共概念

消费者语法保留在 AvatarStatusDot.doc.mjs 中。

概念 封闭值或状态 含义 按 variant/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
Status variant 内置 success、neutral、error;已发布映射也允许扩展名称 选择底板颜色和内置的非颜色标记。 所有尺寸档位;LTR 和 RTL。 success component:AvatarStatusDot 稳定 扩展名称会反映为 data-variant,并保持安全的主题无关基线(FR6);目前尚无基线,即 FR6 差距。
Status label 字符串或缺失 命名独立的状态点,并报告到所属 Avatar 名称中。 每个 variant 和尺寸。 缺失 调用方提供含义;组件暴露并报告它 稳定 空或缺失的 label 不会在该点上发出 role 或可访问名称,也不会报告状态名称。
Custom icon 可渲染的 React 内容或缺失 在尺寸档位允许时替换内置图形。 中档和大档;小档隐藏。 缺失 调用方拥有图形;组件拥有放置和抑制规则 稳定 布尔值和空字符串会被忽略;渲染无 DOM 的组件仍会抑制内置图形。
DOM extension 受支持的 BaseProps 输入和 ref 扩展根元素并合并消费者样式。 每个渲染分支。 无额外输入。 architecture:public-component-api 稳定 BaseProps 省略项仍不受支持。

行为和布局契约

ID 不变量 依据
FR1 36px 及以下的 Avatar 尺寸对应一个带 1px 边框、无自定义图标的 10px 圆点;40–72px 对应 20px 圆点、2px 边框和 12px 图标;96px 及以上对应 32px 圆点、4px 边框和 18px 图标。边框使用表面颜色。在相同层(spec:AST-038 FR7, FR8)中,Avatar 之外的圆点采用 36px 档。 当前源码、测试和 stories
FR2 success 绘制一个填充的 --color-success 底板,内部无字形;neutral 绘制一个表面底板,并带有次要文本颜色的环;error 绘制一个 --color-error 底板,并在 --color-on-error 上带有一条减号条;success 将 --color-on-success 作为其墨色。字形以 currentColor 按档位以 1、1.5 或 2px 描边;减号条占据内部区域的 75%,带有圆头端点。底板是强状态填充,其墨色是对应的内容角色(architecture:theme-tokens INV11)。 当前源码、测试和消费者文档
FR3 在中档和大档位,可渲染的 icon 内容会替换内置字形,并居中放置在一个对辅助技术隐藏的包装器中,该包装器的大小与对应档位的图标尺寸一致。在小档位,图标被省略,内置字形保留。布尔值和空字符串不可渲染。 当前源码和测试
FR4 非空 label 会为圆点添加 role="img" 和 aria-label。圆点会在绘制前、在任意包装器深度下,将同一标签报告给所属 Avatar,并在卸载时撤回该标签。 当前源码和 Avatar 集成测试
FR5 根元素携带带有 variant 的 avatar-status-dot;环形和减号 SVG 携带带有 shape 的 avatar-status-dot-glyph。受支持的消费者属性和 ref 会传递到根元素;圆点自身的 role、名称和样式在调用方属性之后应用,且 xstyle、className 和 style 按该顺序合并。 当前源码、文档和目标测试
FR6 已发布的 AvatarStatusDotVariantMap 允许扩充名称,且可扩展的视觉轴具有安全的、与主题无关的基线(architecture:component-theming-surface INV14)。对于不匹配的名称,根元素的几何形状和反射的 data-variant 保留,而内置填充、墨色和字形缺失;在中档和大档位,带有 style 颜色的调用方 icon 提供颜色和标记,在小档位则不渲染图标。实现缺口:没有与主题无关的基线来绘制不匹配的名称(当前状态影响)。 当前源码、文档、聚焦测试和 architecture:component-theming-surface/INV14

允许的变化

  • AV1 — 身份与含义。 状态标签和调用方图标图案可以变化。
  • AV2 — 主题输出。 目标与反射轴可以通过公开的主题系统变化,而无需转移目标所有权。
  • AV3 — 消费者样式。 根节点上受支持的 BaseProps 输入可以变化,而组件自有的尺寸和上报行为保持不变。

代表性状态

状态 必需的不变量 允许的变化
内置变体 填充、环形和减号分支以及反射的 variant 保持不变。 标签、Avatar 内容、尺寸、主题和方向可以变化。
小尺寸档位 Dot 和内置形状保持不变;自定义图标被省略。 内置变体和标签可以变化。
中尺寸和大尺寸档位 档位尺寸生效;可渲染的自定义图标取代字形。 图标图案、变体、标签和主题可以变化。
带标签 Dot 暴露其标签并将其上报给 Avatar。 调用方编写的标签可以变化。
无标签 Dot 没有角色或名称,并且不上报状态标签。 视觉变体和图标仍可渲染。
增强变体 根节点几何形状和反射的 data-variant 会渲染;内置填充、墨色和字形不存在(FR6 缺口)。 主题可以绘制新增的名称。
RTL Dot 内容方向中性;Avatar 负责逻辑角位置的摆放。 主题、变体、尺寸、标签和图标可以变化。

转换与优先级顺序

  • ORD1 — 解析尺寸。 取所属 Avatar 的解析后尺寸(同一层中位于 Avatar 之外时为 36px),然后选择离散的尺寸档位和尺寸。
  • ORD2 — 解析标记。 当档位允许时,可渲染的图标优先;否则在存在内置变体字形时选择该字形。
  • ORD3 — 解析根节点。 调用方 props → 角色和名称 → 组件目标和样式 → xstyle → className → style。

性能与资源

  • PR1 — 免重渲染的上报。 上报或撤销标签不会导致 Dot 或 Avatar 的额外渲染,也不会遗留任何监听器、观察器或计时器。

无障碍契约

  • AR1 — 无障碍名称。 非空的 label 为独立的 Dot 命名,并被合成到所属 Avatar 的名称中。
  • AR2 — 装饰性视觉标记。 内置 SVG 和自定义图标包装器对辅助技术隐藏,因为根节点或 Avatar 名称承载状态。
  • AR3 — 内置非颜色线索。 三种内置变体除语义颜色外,还使用填充、环形和减号拓扑(WCAG 2.2 1.4.1)。在中尺寸和大尺寸档位,调用方图标会取代该标记,因此非颜色区分随后取决于调用方是否为每种状态使用不同图标。

设计关系

解剖结构或状态 设计需求 表示权威 层级角色 组件契约
Status-dot 根节点 Avatar 边缘上紧凑的语义状态标牌。 当前源代码和消费者文档;当前没有组件设计记录 辅助性指示器 FR1, FR2, FR5
内置字形 环形或减号为中性/错误状态补充颜色。 WCAG 2.2 SC 1.4.1 以及当前已交付的表示形式 有意义的非文本线索 FR2, AR3
自定义图标 在空间允许的情况下,调用方图案取代内置标记。 调用方拥有图案;当前源代码拥有放置位置 条件性有意义线索 FR3, AR2, AR3

家族与系统关系

  • architecture:component-theming-surface 负责绘制目标限定、反射轴,以及可扩展视觉轴所需的可靠且与主题无关的回退;FR6 记录与之相关的缺口。
  • architecture:component-style-authoring 负责 StyleX 降级,并允许此处使用的组件自有的非字形 SVG 形状。
  • architecture:public-component-api 负责已发布的子路径、BaseProps 透传、样式组合、ref 可达性和兼容性边界。
  • architecture:theme-tokens 负责语义颜色和圆角词汇。
  • spec:AST-002 负责 API 准入,并要求未来的公共行为或默认值变更指明当前权威。

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1–FR3, AR2, AR3 AvatarStatusDot.test.tsx 和 AvatarStatusDot.stories.tsx 在浏览器中 三种尺寸档位、三种内置状态、自定义图标存在/不存在 尺寸档位、标记选择、隐藏图标或内置形状的偏离会使针对性断言或渲染夹具失败。 audit:AvatarStatusDot/behavior
FR4, AR1 Avatar.test.tsx 状态名称套件和 AvatarStatusDot.test.tsx 直接/包裹/变化/移除的标签;有标签和无标签的圆点 丢失独立或组合的状态名称、提交阶段更新或清理,会使角色/名称断言失败。 audit:AvatarStatusDot/accessibility
FR5 themingTargets.test.ts 和 extensibleAxes.test.ts 内置和增强变体、字形环/减号 缺少目标元数据或轴接线会导致结构检查失败。缺口:没有测试渲染圆点来检查消费者 props、ref 和样式输入是否到达根节点。 audit:AvatarStatusDot/theming
FR6 AvatarStatusDot.test.tsx 增强变体测试 没有匹配内置规则的新增名称 出现未匹配名称的字形会失败。缺口:填充出现以及调用方 icon 路径没有自动化检查。 audit:AvatarStatusDot/api
RTL relation AvatarStatusDot.stories.tsx 在浏览器中以两个方向运行 所有尺寸档位下的内置状态 任何新的方向性字形、物理定位或未匹配的变换都会在渲染夹具中显现。 audit:AvatarStatusDot/i18n-rtl
Record structure scripts/check-knowledge.mjs 本记录 缺少所需结构或关系会导致仓库验证失败。 audit:AvatarStatusDot/docs
PR1 Avatar.test.tsx 无额外渲染测试 包裹的状态标签 额外的渲染或报告循环会导致失败。 audit:AvatarStatusDot/behavior
AR1, AR2 可访问性树证据(spec:AST-009 FR3) 有标签和无标签的独立圆点 缺口:没有可访问性树检查证明独立图像角色和名称或隐藏标记;单元测试查询的是 DOM。 audit:AvatarStatusDot/accessibility

Decision log

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

Open questions

无。

Content boundary

本文件不重复消费者示例、当前审计分数、截图、运行清单、资格数据或共享 API/主题规则。它链接到这些内容的所属方。

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