AvatarGroupOverflow 组件契约¶
契约一览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | 一个溢出指示器,带有必需的 count、可选的 onClick,以及可选的、用于替换可见 “+N” 的自定义 children。 |
| 行为 | 没有 onClick 时,它是一个带名称的图像;有 onClick 时,它是组内轮转集合(roving set)中的原生按钮。除非调用方通过 aria-labelledby 为其命名,否则其名称是翻译后的计数。 |
| 最终用户影响 | 屏幕阅读器用户会听到有多少人被隐藏(“还有 5 人”);键盘用户可以将可点击指示器作为组内最后一项访问。 |
| 构建者影响 | 无;该记录描述的是已发布的行为。 |
| 兼容性/就绪状态 | 已发布的行为被记录为当前状态;没有 API、默认值或输出变化。两个实现差距列在“当前状态影响”下。 |
| 审查检查 | 拒绝负的显示计数、取自自定义 children 的名称、位于轮转集合中的静态指示器,或忽略组大小或形状的指示器。 |
| 治理规则 | architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface/INV2,INV6;architecture:internationalization/INV1a。 |
此表是审查概览;以下正文具有权威性。
意图¶
AvatarGroupOverflow 告诉读者 AvatarGroup 未显示多少成员,并可选择让他们打开其余成员。它拥有指示器的计数标签、其静态与按钮形态,以及其在组内的几何属性。
兼容性与迁移¶
- 已发布的默认值保持不变:
yes - 兼容性类别:记录已发布的行为;没有公共 prop、默认值、DOM、可访问性、目标或样式输出的变化
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
当前状态影响¶
- 目录之外的默认计数(FR2)。 可见的 “+N” 由原始数字拼装而成,因此永远不会按区域设置(locale)格式化:当名称显示为 “还有 4,912 人” 时,chip 显示 “+4912”,并且在具有自己数字体系的区域设置下,数字也会不同(
architecture:internationalizationINV1a)。 - 溢出按钮目标尺寸(AR4)。 在 16px 的组中,可点击指示器高 20px,低于 WCAG 2.2 2.5.8 的 24 × 24 CSS 像素要求。
所有权边界¶
拥有
- 指示器元素及其
avatar-group-overflow目标。 - 默认可见的 “+N” 内容和翻译后的计数名称。
- 静态图像和原生按钮形态。
- 在 AvatarGroup 之外使用的中等尺寸、圆形、无重叠呈现方式。
不拥有 / 非目标
- 选择可见头像并计算隐藏计数——由产品调用点(callsite)负责。
- 头像渲染和主题化——由
component:Avatar负责。 - 组的名称、上下文、成员顺序和轮转焦点算法——由
component:AvatarGroup负责;可点击指示器通过项目标记加入。 - 调用方提供的
children——本组件只负责将其放入指示器,其他方面不拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 负责人 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 计数 | 调用方提供的数字 | 驱动翻译后的名称和默认的 “+N”。 | 两种形态;组内或组外 | 必需 | component:AvatarGroupOverflow |
稳定 | 负计数会显示为零,并被命名为零。 |
| 显示内容 | 默认 “+N”;调用方 children |
可见内容;名称仍由计数派生。 | 两种形态 | “+N” | component:AvatarGroupOverflow |
稳定 | — |
| 激活 | 静态;可点击 | onClick 选择按钮形态,并在激活时被调用。 |
组内和组外 | 静态 | component:AvatarGroupOverflow |
稳定 | — |
| 呈现 | 组提供;独立使用 | 尺寸、形状和重叠由 AvatarGroup 提供;否则为中等尺寸、圆形、无重叠。 | 所有尺寸和形状;两个方向 | 独立使用时的中等尺寸圆形 | component:AvatarGroupOverflow |
稳定 | — |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| --- | --- | --- |
| FR1 | 在没有 onClick 时,指示器是一个带 role="img" 的 span,调用方的 role 会替换它。有 onClick 时,它是一个原生的 button type="button",在激活时调用 onClick,并绘制共享的 focus-visible 轮廓以及共享的悬停和按下覆盖层。 |
当前源代码和测试 |
| FR2 | 在生成名称和默认内容之前,负的 count 会被钳制为零。名称在这两种形式下都是已翻译的“{count} more”,并替换调用方的 aria-label;而调用方的 aria-labelledby 会到达根节点并改为为根节点命名;调用方的 children 仅替换可见的“+N”。运行时的 count 通过 catalog 格式化(architecture:internationalization INV1a)。实现缺口:默认的“+N”是在 catalog 之外组装的,因此可见的 count 从未按 locale 格式化:分组分隔符以及某些 locale 中的数字都与名称不同(当前状态影响)。 |
当前源代码和测试 |
| FR3 | 在与 AvatarGroup 位于同一层(spec:AST-038 FR7、FR8)内时,指示器使用该组的大小、形状、数字大小和重叠;在该组之外(包括从组打开的层中)时,它使用 md、circle 且不重叠。 |
当前源代码和测试 |
| FR4 | 指示器的宽度至少为头像大小加上两侧各 2px 表面色边框,高度正好等于该值;当内容更宽时,它会通过 --spacing-2 行内内边距在行内扩展,并采用组的负行内起始重叠。它使用次要文本、正文族、中等字重,以及 --text-supporting-size 与头像大小 35% 中较大者作为字号,在表面之上绘制中性色。其圆角遵循形状。 |
当前源代码、测试和 stories |
| FR5 | 根节点承载反映 size 和 shape 的 avatar-group-overflow 目标。受支持的 DOM、ARIA、data 和事件 props 以及 ref 都会到达根节点;xstyle、className 和 style 按此顺序在组件样式之后合并。 |
当前源代码和测试 |
| FR6 | 按钮形式带有 data-avatar-item 标记,因此 AvatarGroup 会将其包含在其巡游集合中;静态形式不带标记,并且其上的调用方 tabIndex 会被转发,但不会将该静态形式添加到该集合中。 |
当前源代码和 AvatarGroup 测试 |
允许的变化¶
- AV1 — 数量与内容。 计数和调用方内容会变化;更宽的内容会让指示器内联扩展。
- AV2 — 主题绘制。 主题可以按
size和shape重设avatar-group-overflow的样式,而不会移动目标。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 静态计数 | role="img" 的 span,名称为“{count} more”,显示 “+N”;不是漫游项。 |
数量、大小、形状。 |
| 静态自定义内容 | 由计数派生名称;调用方内容可见。 | 内容。 |
| 可点击 | 名为“{count} more”的按钮;在分组时是最后一个漫游项。 | 数量、内容。 |
| 负计数 | 名称和显示均为零。 | 调用方内容。 |
| 宽计数 | 在解析后的高度上内联扩展。 | 宽度。 |
| 独立 | 无重叠的 md 圆形。 |
数量、激活方式。 |
| 从右到左 | 重叠和顺序遵循文档方向。 | — |
变换与优先级顺序¶
- ORD1 — 呈现。 AvatarGroup 上下文 →
md、circle、无重叠。 - ORD2 — 内容。 将
count钳制为零 → 转换后的名称;调用方子元素 → 否则为 “+N”。 - ORD3 — 根属性。 静态:
role="img"→ 调用方 props → 名称 → 组件类名和样式。按钮:type和onClick→ 调用方 props → 名称和项目标记 → 按压标记 → 组件类名和样式。
性能与资源¶
- PR1 — 无本地资源。 指示器自身不持有状态、监听器、观察器或定时器。两种形式都在挂载时安装共享的文档级按压控制器;只有按钮携带其按压标记。
无障碍契约¶
- AR1 — 计数名称。 两种形式都由转换后的计数命名,绝不会由自定义子元素命名;调用方的
aria-labelledby会到达根元素并改为命名任一形式,而调用方的aria-label会被替换。 - AR2 — 角色。 静态形式是图像,除非调用方提供了角色;可点击形式是具有共享焦点可见轮廓的原生按钮。
- AR3 — 分组参与。 只有可点击形式会加入 AvatarGroup 的漫游集。
- AR4 — 目标尺寸。 可点击指示器的目标至少为 24×24 CSS 像素,或具有 WCAG 2.2 2.5.8 允许的间距。从
xsm起,按钮至少为 24×24,并绘制在被其重叠的头像上方。实现差距:在 16px 大小的分组中,按钮高度为 20px。
设计关系¶
| 结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 计数标签 | 与头像匹配的中性标签上的紧凑辅助计数。 | 当前源码和文档 | 辅助 | FR2, FR4, AR1 |
| 按钮行为 | 具有共享覆盖层和焦点可见处理的原生按钮。 | 当前源码和共享工具 | 辅助操作 | FR1, FR6, AR2, AR3 |
主题化:根是 avatar-group-overflow 目标;计数标签继承该目标。使用方的结构未命名任何根部分,因此不声明任何结构主题化块。
家族与系统关系¶
component:AvatarGroup提供大小、形状和重叠,并负责管理可点击形式加入的漫游集。architecture:component-theming-surface负责目标资格与反映。architecture:public-component-api负责透传、样式组合和 ref 规则。spec:AST-002负责批准对此公共表面的任何变更。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR2 | AvatarGroupOverflow.test.tsx 渲染、角色和回调测试 |
静态、调用者角色、可点击 | 错误的元素、丢失的 img 角色或调用者角色、缺少的按钮或丢失的回调都会导致失败。差距:按钮的 type="button"、其焦点轮廓以及悬停和按下覆盖层没有自动化检查。 |
audit:AvatarGroupOverflow/behavior |
| FR2, AR1, ORD2 | AvatarGroupOverflow.test.tsx 数量、内容和区域设置测试 |
零、负数、大数量、自定义内容、本地化 | 负数、错误的默认 "+N" 或名称、缺少自定义内容或未翻译的名称都会导致失败。差距:没有测试断言带有自定义子元素时的名称、调用者的 aria-label 被替换、调用者的 aria-labelledby 或具有自有数字系统的区域设置;大数量测试断言未格式化的 "+4912" 与 "4,912 more" 并存,这是已记录的差距。 |
audit:AvatarGroupOverflow/behavior |
| FR3, ORD1 | AvatarGroupOverflow.test.tsx 尺寸和形状测试 |
分组;独立 | 丢失分组尺寸或形状会导致失败。差距:没有测试断言独立的 md、circle 和无重叠回退,或图层子句。 |
audit:AvatarGroupOverflow/layout |
| FR4 | AvatarGroup.test.tsx 重叠测试;AvatarGroupOverflow.stories.tsx |
分组、宽数量、每种形状 | 丢失重叠边距会导致失败。差距:盒尺寸、边框、行内增长和内边距、绘制、字号下限和圆角仅在渲染的 fixture 中可见。 | audit:AvatarGroupOverflow/layout |
| FR5, ORD3 | themingTargets.test.ts;AvatarGroupOverflow.test.tsx ref、className 和调用者角色测试 |
两种形式 | 目标漂移、丢失的 ref、被丢弃的 className,或无法到达静态形式或落在其 role="img" 之前的调用者 props 都会导致失败。差距:没有测试涵盖 xstyle、style、按钮形式的透传或 ORD3 顺序的其余部分。 |
audit:AvatarGroupOverflow/theming |
| FR6, AR3 | AvatarGroup.test.tsx 溢出 roving 测试 |
交互式头像之后的按钮 | roving 集合中缺少按钮会导致失败。差距:没有测试断言静态形式不携带标记,或其上的调用者 tabIndex 会被转发。 |
audit:AvatarGroupOverflow/accessibility |
| Right-to-left | apps/storybook/rtl-audit/targets.json 条目 |
两个方向上的分组溢出 | 差距:审计列出了该 fixture,但没有自动化检查会在未镜像的头像到溢出顺序上失败。 | audit:AvatarGroupOverflow/i18n-rtl |
| AR1, AR2 | 无障碍树证据(spec:AST-009 FR3) |
静态与可点击形态 | 缺口:没有无障碍树检查可以验证图像或按钮的角色及计数名称;单元测试直接查询 DOM。 | audit:AvatarGroupOverflow/accessibility |
| AR4 | AvatarGroupOverflow.stories.tsx 在浏览器中 |
组中的可点击指示器 | 缺口:没有自动化的目标尺寸检查;16px 组是已记录的缺口。 | audit:AvatarGroupOverflow/accessibility |
决策日志¶
未记录任何决策。该记录描述的是已发布行为。
未决问题¶
无。
内容边界¶
本文件不会重复使用者 prop 表格/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到这些内容的所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx