跳转至

AvatarGroup 组件契约

契约一览

方面 契约
公开契约 一个带标签的组,包含调用方提供的 Avatar 子元素,可选地以单个 AvatarGroupOverflow 结尾,并具有统一的 size 和 shape。
行为 成员按头像尺寸的四分之一重叠;交互式成员共享一个 Tab 停靠点,支持方向键漫游和已翻译的键盘提示。
最终用户影响 屏幕阅读器用户会听到一个已命名的组;键盘用户只需按一次 Tab 进入组,即可用方向键在交互式头像之间移动。
构建者影响 无;该记录描述的是已发布的行为。
兼容性/就绪状态 已发布的行为记录为当前状态;无 API、默认值或输出变更。一个实现差距列在“当前状态影响”下。
审查检查 拒绝以下实现:成员自身的 size 或 shape 在组内生效;交互式成员上有多个 Tab 停靠点;或存在键盘提示但没有交互式成员。
治理规则 architecture:public-component-api/INV5,INV6,INV7,INV8;architecture:component-theming-surface/INV2,INV6;architecture:internationalization/INV1a。

此表为审查概览;以下正文具有权威性。

意图

AvatarGroup 将多个人显示为一条紧凑、重叠的行。它拥有组名、传递给成员的统一 size 和 shape、重叠几何结构,以及交互式成员之间的键盘移动。

兼容性与迁移

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

使用方的迁移说明属于使用方文档和发布说明。

当前状态影响

  • 过期的提示与 Tab 停靠点(FR5、AR2、AR3)。 当某个成员在其自身状态作用下变为链接、按钮或静态元素,而组没有重新渲染时,组会保留之前的提示和 Tab 停靠点。新的交互式成员不会获得提示,并且在焦点进入组之前是独立的 Tab 停靠点;如果组内没有任何交互式成员,则会保留过期的提示;当持有 Tab 停靠点的成员变为静态时,其余链接仍保持 tabindex="-1",因此 Tab 会跳过该组,键盘用户直到其重新渲染才能到达这些链接。

所有权边界

拥有

  • 组根元素、其 role 和名称,以及 avatar-group 目标。
  • 通过 context 提供给成员的尺寸、形状、重叠比例和数字尺寸。
  • 用于将第一个被重叠的成员保持在组内的起始内边距。
  • 在带有 avatar item 标记的成员间漫游焦点,以及键盘提示。

不拥有 / 非目标

  • 哪些头像可见以及隐藏数量——由产品调用方负责,调用方会对其列表进行切片。
  • 每个成员的渲染、名称、工具提示和组内环——由 component:Avatar 负责。
  • “+N”指示器——由 component:AvatarGroupOverflow 负责。

公开概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
尺寸 任意 component:Avatar size 应用于每个成员和溢出指示器。 所有组 md component:AvatarGroup 稳定 TypeScript 拒绝其他值。
形状 circle、rounded、square 应用于每个成员和溢出指示器。 所有组 circle component:AvatarGroup 稳定 TypeScript 拒绝其他值。
键盘 静态组;交互式组 是否存在任意成员带有 avatar item 标记。 在组自身每次渲染时读取 静态 component:AvatarGroup 稳定 —

行为与布局契约

ID 不变量 依据
FR1 根元素是一个 inline-flex、垂直居中的 div,带有 role="group",由调用方的 aria-label 或 aria-labelledby 命名,否则使用翻译后的“头像”。它承载反映 size 和 shape 的 avatar-group 目标,并按顺序渲染子元素。 当前源码与测试
FR2 组将其 size、shape、数值尺寸,以及数值尺寸四分之一取整后的重叠量,提供给同一层中位于其下的每个 Avatar 和 AvatarGroupOverflow(spec:AST-038 FR7、FR8;在悬停卡、弹出框或其他层中的成员保留自己的尺寸和形状,但其中被标记的成员仍留在 FR4 漫游集合中);成员自身的尺寸和形状永远不会生效,即使在组使用默认值时也是如此。 当前源代码和测试
FR3 每个成员(包括第一个)都将负重叠量作为其 inline-start 外边距;组在 inline-start 方向填充相同的量,使第一个成员保持在组内;空组没有起始内边距。当成员被包裹在 HoverCard 或 Tooltip 中时,重叠仍然成立。 当前源代码和测试
FR4 带有 data-avatar-item 的元素——链接和按钮头像,以及可点击的溢出指示器——构成一个水平漫游集合,只有一个 Tab 停靠点:方向键按渲染方向在它们之间移动并在两端循环,Home 和 End 跳到第一个和最后一个。成员中其他可聚焦内容(例如状态槽中的按钮)不在该集合中。 当前源代码和测试
FR5 提示和 Tab 停靠点取决于组自身最近一次渲染时读取到的“是否有成员带有条目标记”:只要有一个成员带标记,组内部就会渲染一条视觉隐藏的翻译提示(“使用方向键在头像之间移动”),并将其附加到调用者已有的 aria-describedby 值之后;完全静态的组没有 Tab 停靠点,也没有提示。实现缺口:成员通过自身状态获得或失去该标记,而未触发组重新渲染时,提示和 Tab 停靠点会保持陈旧(当前状态影响)。 当前源代码和测试
FR6 ref 到达根元素。受支持的 DOM、ARIA、data 和事件 props 到达根元素;组件自带的 role、name、description 和 data-testid 在其后应用;调用者的 onKeyDown 和 onFocus 在漫游处理程序之前运行,若调用 preventDefault() 则跳过该事件的漫游处理程序(architecture:public-component-api INV7);xstyle、className 和 style 按该顺序合并到组件样式之后。 当前源代码和测试

允许的变体

  • AV1 — 主题绘制。 主题可以按 size 和 shape 重新设置 avatar-group 的样式,而不改变成员组成、重叠归属或焦点行为。
  • AV2 — 成员组成。 成员的数量和种类因调用点而异。

代表性状态

状态 必需的不变式 允许的变体
静态组 命名组;无 Tab 停靠点;无提示。 成员。
交互式组 一个成员具有 tabIndex={0},其余为 -1;方向键漫游;提示被描述。 成员。
带溢出按钮 溢出指示器是最后一个漫游项。 数量。
空组 渲染时没有起始填充。 —
从右到左 重叠和方向键移动遵循渲染方向。 —

变换与优先级顺序

  • ORD1 — 成员尺寸和形状。 组值 → 成员自身的 prop(在组内被忽略)。
  • ORD2 — 描述。 调用者的 aria-describedby → 键盘提示 id。
  • ORD3 — 按键和焦点处理。 调用者的 onKeyDown 或 onFocus → 漫游处理程序;调用者处理程序若调用 preventDefault(),则跳过该事件的漫游处理程序。

性能与资源

  • PR1 — 成员检测。 检测交互式成员不会增加观察器或监听器;组在每次自身渲染后重新读取其成员;如果任何成员是否为交互式的状态发生变化,组会在绘制前重新渲染。

无障碍契约

  • AR1 — 命名组。 根元素是 role="group",并带有一个翻译后的默认名称,调用者可替换。
  • AR2 — 单个 Tab 停靠点。 交互式成员共享单个 Tab 停靠点,并可通过方向键、Home 和 End 在两个方向上都按视觉顺序到达,以组自身最近一次渲染时读取到的状态为准(成员本地变更的 FR5 缺口)。
  • AR3 — 键盘提示。 提示仅在漫游适用时描述该组,以组自身最近一次渲染时读取到的状态为准(成员本地变更的 FR5 缺口)。
  • AR4 — 静态成员。 静态头像不是漫游项,在组内也没有 Tab 停靠点;component:Avatar 记录了该状态对其工具提示的影响。

设计关系

结构或状态 设计要求 表示权威 层级角色 组件契约
头像子元素 统一尺寸的成员在一行中重叠排列。 当前源码与文档 突出 FR1–FR3
溢出指示器 行尾可选的“+N”成员。 当前源码与文档 辅助 FR2, FR4

主题:根元素的主题目标是 avatar-group。成员保留各自的主题目标; 溢出指示器的主题目标 avatar-group-overflow 属于 component:AvatarGroupOverflow。消费方结构没有命名根部分,因此不声明 结构主题块。

家族与系统关系

  • component:Avatar 读取组上下文,并在其自身的根元素上应用环、重叠和项目标记。
  • component:AvatarGroupOverflow 读取相同的上下文,并在可点击时加入轮转集合。
  • architecture:internationalization 管理组名称和提示背后的目录。

验证映射

契约 验证 代表性状态 变更或失败预期 审计部分
FR1, AR1 AvatarGroup.test.tsx 渲染、标签、尺寸反映、test-id 和空组测试 默认与自定义 aria-label;尺寸;空 缺少 group 角色、默认或自定义名称、data-size 反映或子元素时失败。缺口:没有测试断言内联 flex 居中、data-shape、子元素顺序、调用方的 aria-labelledby 或调用方 role 被替换。 audit:AvatarGroup/a11y
FR2, ORD1 AvatarGroup.test.tsx 尺寸级联与重叠套件;Avatar.test.tsx 组形状测试;AvatarGroupOverflow.test.tsx 尺寸与形状测试 组尺寸与形状、默认值、组外;md 重叠 成员自身的尺寸或形状在组内生效,或 md 重叠值错误,则失败。缺口:没有测试断言除 md 之外尺寸的重叠值,或另一层中的成员保留自身尺寸和形状。 audit:AvatarGroup/behavior
FR3 AvatarGroup.test.tsx 重叠套件 普通与包裹成员、溢出指示器、空组 缺少成员外边距、缺少起始内边距,或空组上有起始内边距,则失败。 audit:AvatarGroup/layout
FR3(布局) AvatarGroup.stories.tsx 尺寸;AvatarGroupOverflow.stories.tsx AllShapes 尺寸与形状,LTR 和 RTL 缺口:没有自动化检查;被裁剪的第一个成员或未镜像的重叠仅能在渲染的夹具中可见。 audit:AvatarGroup/layout
FR4, AR2, AR4 AvatarGroup.test.tsx 轮转焦点套件 交互式头像、溢出按钮、状态按钮、静态组 出现多个 Tab 停靠点、丢失 ArrowRight/ArrowLeft 移动、缺少溢出项、集合中包含状态按钮,或静态组上有 Tab 停靠点,则失败。缺口:换行、Home 和 End 以及从右到左的箭头方向没有自动化检查。 audit:AvatarGroup/a11y
FR5, AR3, ORD2 AvatarGroup.test.tsx 提示测试 交互式与静态组 交互式组缺少提示,或静态组出现提示,则失败。缺口:没有测试覆盖调用方 aria-describedby 之后提示的顺序,或成员通过自身状态改变交互性的情况。 audit:AvatarGroup/a11y
FR6, ORD3 AvatarGroup.test.tsx test-id 测试 调用方的 data-testid 丢失 test id 则失败。缺口:没有测试覆盖 ref、DOM 透传、属性顺序、调用方处理程序的顺序与取消,或样式输入合并。 audit:AvatarGroup/api
PR1 源码审查 交互式与静态组 缺口:如果成员检测添加了观察器或监听器,没有自动化检查会失败。 audit:AvatarGroup/behavior
AR1, AR3 无障碍树证据(spec:AST-009 FR3) 静态和交互组 差距:没有无障碍树检查证明组角色、名称或描述;单元测试查询 DOM。 audit:AvatarGroup/a11y

决策日志

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

未决问题

无。

内容边界

本文件不重复消费者属性表/示例、当前审计结果、实施步骤或家族/系统规则。它链接到其所有者。

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