跳转至

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:internationalization INV1a)。
  • 溢出按钮目标尺寸(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