Avatar 组件契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | 一个具有尺寸和形状的身份图像,包含 src、fallbackSrc、name、alt、status、tooltip,以及可选的 href/as/target/rel 或 onClick 交互。 |
| 行为 | 头像显示最先加载成功的图像,然后是姓名首字母,最后是默认图标;它可以是一个具名图像(将状态标签组合进其名称)、一个链接或一个按钮,在没有名称时则为装饰性元素。 |
| 最终用户影响 | 屏幕阅读器用户通过一个名称即可听到头像所代表的人物及其状态;键盘用户可以揭示其工具提示并操作交互式头像。 |
| 构建者影响 | 无;此记录描述的是已发布的行为。 |
| 兼容性/就绪状态 | 已发布的行为记录为当前状态;无 API、默认值或输出变更。四个实现缺口列于“当前状态影响”之下。 |
| 审查检查 | 应拒绝以下情况:一个具名静态头像在调用方未覆盖的情况下丢失其派生的 role="img";一个辅助技术无法访问的状态标签;一个未分组的静态头像,其工具提示仅能通过指针揭示;或一个绕过共享目标规则的交互式头像。 |
| 治理规则 | family:navigation-destinations;spec:AST-005;architecture:public-component-api/INV5,INV6,INV8;architecture:component-theming-surface/INV2,INV6;architecture:internationalization/INV1a。 |
此表格是审查投影;下文正文具有权威性。
意图¶
Avatar 使用图像代表一个人或实体,或在没有图像加载时提供一个可读的替身。它拥有图像回退链、尺寸和形状、状态位置、可访问名称、可选的名称工具提示,以及静态、链接或按钮根元素的选择。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:记录已发布的行为;无公共 prop、默认值、DOM 或样式输出变更
- 受控/非受控行为:不适用;图像失败跟踪是内部状态
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 静态头像上的调用方
tabIndex被替换(FR9)。 静态头像在调用方 props 之后设置自己的tabIndex:在组外显示工具提示时为0,否则为无。调用方的tabIndex永远不会到达它,而architecture:public-component-apiINV5 将受支持的输入发送到根元素。 - 分组交互式工具提示在重新渲染时丢失(FR7、AR4)。 在 AvatarGroup 中,作为链接或按钮的头像如果不是该组的制表位,在重新渲染重新挂载其根元素后,当键盘焦点到达它时将不再打开其工具提示:一个新的
status元素(内联的statusprop 会在每次父级渲染时创建一个)、更改的name、alt、区域设置、调用方的 ARIA、或调用方的ref,或一个在挂载后才启用的工具提示,因此有视力的键盘用户会丢失名称工具提示(WCAG 2.2 2.1.1)。 - 小型交互式头像(AR7)。 16 或 20px 的链接或按钮头像低于 WCAG 2.2 2.5.8 的 24×24 CSS 像素目标,并且 AvatarGroup 中的交互式头像会重叠,因此它们不具备间距例外。
- 分组静态头像工具提示(AR4)。 在 AvatarGroup 内,带有工具提示的静态头像没有制表位,也不是漫游焦点项,因此有视力的键盘用户无法揭示其工具提示,而 WCAG 2.2 2.1.1 和 1.4.13 期望悬停内容可以通过键盘访问。自定义工具提示字符串仍可作为头像的描述到达辅助技术。
所有权边界¶
拥有
- 根元素、裁剪的内容区域,以及 Photo、Initials 和 Default 图标部分。
- 回退链、尺寸和形状的解析,以及状态位置。
- 可访问名称,包括组合已报告的状态标签。
- 名称工具提示以及揭示它的静态制表位。
- 静态、链接或按钮根元素的选择及其 focus-visible 轮廓。
- 它在 AvatarGroup 内的适配:组尺寸和形状、表面环、重叠偏移、项目标记,以及放弃自身的制表位。
不拥有 / 非目标
- 状态点的渲染、尺寸层级、字形和标签报告 — 由
component:AvatarStatusDot拥有。Avatar 仅拥有状态槽的位置以及已报告标签如何进入其名称。 - 跨头像的堆叠、溢出和漫游焦点 — 由
component:AvatarGroup和component:AvatarGroupOverflow拥有。 - 导航目标安全性和路由替换 — 由
family:navigation-destinations和spec:AST-005拥有。 - 工具提示的表面、位置和打开时机 — 由共享的 tooltip hook 拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Size | xsm(20)、sm(24)、md(36)、lg(48)、xl(128),或 16、20、24、32、36、40、48、60、64、72、96、128、144、180 px |
以 CSS 像素为单位的方形盒子尺寸。 | 组外;组内由组的尺寸决定 | md |
component:Avatar |
稳定 | TypeScript 拒绝其他值。 |
| Shape | circle、rounded、square |
圆角半径 --radius-full、--radius-element 或 --radius-none。 |
组外;组内由组的形状决定 | circle |
component:Avatar |
稳定 | TypeScript 拒绝其他值。 |
| Visual | 照片;备用照片;首字母;默认图标 | 内容区域显示的内容(FR2)。 | 所有根元素 | — | component:Avatar |
稳定 | — |
| Root | 静态;链接;按钮 | 头像的根元素是什么(FR6)。 | 由 href 和 onClick 解析 |
静态 | component:Avatar |
稳定 | href 优先于 onClick。 |
| Tooltip | 名称(默认);自定义字符串;无 | 在悬停和键盘聚焦时显示的文本。 | 所有根元素 | 名称 | component:Avatar |
稳定 | 空名称或空字符串不显示工具提示。 |
| Status | 节点或不存在 | 角标内容,通常是 AvatarStatusDot。 | 所有根元素和形状 | 不存在 | component:Avatar |
稳定 | 假值不渲染状态插槽。 |
行为与布局约定¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 根元素是一个相对定位、不收缩的 inline-flex 盒子,具有解析后尺寸的方形盒子和该形状的圆角;它带有 avatar 目标,该目标反映 size 和 shape。被裁剪的内容区域以相同的圆角填满根元素,并禁止文本选中。 |
当前源码和测试 |
| FR2 | 内容区域在 src 尚未加载失败时显示 src,然后在其尚未加载失败时显示 fallbackSrc,当名称能产生首字母时显示首字母,否则以盒子尺寸的 60% 显示默认人物图标。每张图片以空 alt 和 object-fit: cover 渲染。失败是按源跟踪的,因此更改后的 src 或 fallbackSrc 会再次尝试。 |
当前源码和测试 |
| FR3 | 首字母取自去除首尾空格后的 name 的首词和末词的第一个字母、数字或 emoji,并转为大写;单词开头的标点会被跳过,没有可用字符(字母、数字或 emoji)的单词会被丢弃,只有一个符合条件的单词时生成一个首字母,且字素簇永远不会被拆分。仅含空白的名称视为不存在。首字母和默认图标以 --color-neutral 和主要文本色绘制在 avatar-fallback 目标上(反映 size),这一对颜色在浅色和深色模式下对比度至少为 4.5:1,使用正文字体族和中等字重,首字母大小为盒子的 40%。在强制颜色模式下,单独的 Avatar 的首字母和默认图标采用周围颜色(currentColor):默认采用强制前景色,并采用在其周围绘制颜色的控件的系统颜色(GrayText、HighlightText);在 AvatarGroup 内部,它们保持组环上的强制前景色。 |
当前源码与测试 |
| FR4 | 真值(truthy)的 status 渲染在裁剪内容区域之外的绝对定位插槽中。在圆形上,它位于圆边缘底部行内末端 45° 点处并以其为中心;在其他形状上,它位于底部行内末端角,并向外偏移其自身尺寸的四分之一。在从右到左的文档中,位置会镜像。 |
当前源码与测试 |
| FR5 | 解析后的名称为 alt,否则为 name(空白字符串视为不存在);当两者都存在时,与状态标签组合成已翻译的“{name}, {status}”;仅状态标签本身也可为该头像命名。状态标签来自传入元素上的字符串 label,在每次渲染时读取,也来自 AvatarStatusDot 在任意包装深度上报的标签,后者优先,并在不进行第二次渲染的情况下于绘制前更新根节点。 |
当前源码与测试 |
| FR6 | href 将渲染共享的链接组件(或 as),并带有 target 和 rel;否则 onClick 渲染 button type="button";否则根元素为 div。链接和按钮根元素带有 data-avatar-item 标记和共享的 focus-visible 轮廓;onClick 附加到链接或按钮上。在开发模式下,如果交互式头像的唯一名称是状态标签,或者没有名称且调用方未提供 aria-label/aria-labelledby,则会记录一条警告。 |
当前源码与测试 |
| FR7 | 工具提示显示去除首尾空格后的自定义字符串,否则显示有意义的 name,显示在元素上方,在悬停和键盘聚焦时出现;tooltip={false} 或结果为空时不显示。带有工具提示且不在组内的静态头像会获得 tabIndex={0},以便键盘用户能够显示它。自定义字符串会追加到调用方值之后的 aria-describedby 中;默认的名称工具提示不会追加,因为它重复了名称。实现差距:组内的链接或按钮头像若不是组的 Tab 停靠点,在重新渲染并重新挂接其根元素后,会在聚焦时停止打开其工具提示——这些情况包括:新的 status 元素(内联的 status prop 在每次父级渲染时都会创建一个)、变更的 name、alt、locale、调用方 ARIA、调用方 ref,或挂载之后才打开的工具提示(当前状态影响)。 |
当前源码与测试 |
| FR8 | 在同一层(spec:AST-038 FR7、FR8)的 AvatarGroup 内,组的尺寸和形状优先于头像自身的 props;根元素在其盒子外部获得一个 2px 的表面色环,并应用组的负 inline-start 重叠;静态头像不添加 tooltip Tab 停靠点,而链接和按钮根元素保留 data-avatar-item 标记,从而加入该组的漫游集合。对于从组打开的 hover card、popover 或其他层中的头像,其保留自身的尺寸和形状,不获得环或重叠,并保留其 tooltip Tab 停靠点;那里的链接或按钮头像仍携带该标记,因此该组的漫游焦点会在其 DOM 子树中选择带标记的元素,仍会包含它。 |
当前源码与测试 |
| FR9 | ref 可到达每个变体的根元素。受支持的 DOM、ARIA、data 和 event props 在派生 ARIA 之后到达根元素,因此调用方的 aria-label、role 或 aria-hidden 优先(architecture:public-component-api INV5);data-testid 到达根元素;xstyle、className 和 style 按该顺序在组件样式之后合并。实现缺口:在静态根元素上,组件在调用方 props 之后设置 tabIndex,因此调用方传入的 tabIndex 会被替换(当前状态影响)。 |
当前源码与测试 |
允许的变体¶
- AV1 — 主题绘制。 主题可以按
size和shape重新设置avatar的样式,并按size重新设置avatar-fallback的样式,而不改变回退链或名称。 - AV2 — 路由链接。
LinkProvider或as组件可以在family:navigation-destinations下替换原生锚点。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变体 |
|---|---|---|
| 照片,已命名 | 根元素具有 role="img",由 alt 或 name 命名;内部图片具有空 alt。 |
尺寸、形状。 |
| 照片加载失败 | 回退到照片,然后是首字母或图标;新的 src 会重试。 |
— |
| 首字母 | 在 avatar-fallback 上显示大写首字母。 |
名称。 |
| 未命名,无状态 | 具有 role="presentation" 且 aria-hidden="true";默认图标;无 tooltip。 |
— |
| 已命名并带状态点 | 名称读作“{name}, {status}”;状态点位于边缘或角落。 | 形状、方向。 |
| 链接 | 链接根元素带标记、轮廓和 aria-label。 |
路由组件。 |
| 按钮 | 根元素为 button type="button",带标记、轮廓和 aria-label。 |
— |
| 带 tooltip 的静态状态 | tabIndex={0};悬停和聚焦时显示 tooltip。 |
Tooltip 文本。 |
| 在组中 | 组的尺寸和形状;表面环;重叠;没有自己的 Tab 停靠点(AR4 针对 tooltip 的缺口)。 | 组重叠。 |
转换与优先级顺序¶
- ORD1 — 视觉。
src→fallbackSrc→ 首字母 → 默认图标。 - ORD2 — 名称。
alt→name;然后与状态标签组合;所报告的标签 → 所传入元素的label。调用方的aria-label会替换该结果。 - ORD3 — 根元素。
href→onClick→ 静态。 - ORD4 — 尺寸和形状。 同一层中的 AvatarGroup → 头像自身的 prop → 默认值。
性能与资源¶
- PR1 — 名称更新无需重新渲染。 被包裹的 AvatarStatusDot 所报告的、或之后发生变化的状态标签,会在绘制前更新头像的名称,而无需额外渲染该头像。
无障碍契约¶
- AR1 — 命名图片。 带有名称的静态头像使用
role="img"并包含该名称;没有名称且没有状态标签时,它使用role="presentation"并设置aria-hidden="true"。内部图片和默认图标均为装饰性元素。首字母是照片的备用方案,与内部图片一样属于装饰性:每个根元素(链接、按钮、静态)都向辅助技术隐藏它们,因此可访问名称仅包含人物姓名,默认名称工具提示(FR7)在悬停和聚焦时显示该姓名。 首字母通过私有实例级 CSS 变量生成内容绘制,因此不会进入可访问名称;Avatar 不为它们渲染任何公共属性。 - AR2 — 状态可到达辅助技术。 由于
role="img"根元素会剪除其后代,状态标签被合成到头像自身的名称中(FR5)。 - AR3 — 交互式根元素。 链接和按钮根元素保留其原生角色,仅接受
aria-label;它们绘制共享的 focus-visible 轮廓。 -
AR4 — 键盘可到达的提示。 头像的提示可以通过键盘揭示(WCAG 2.2 2.1.1、1.4.13):它在键盘聚焦时打开,组外的静态头像在具有提示时获得一个 Tab 停靠点。 实现差距:在同一图层内的 AvatarGroup 中,静态头像会失去该 Tab 停靠点,组的漫游焦点仅覆盖链接和按钮头像,因此其提示仅在悬停时打开;此外,组内非 Tab 停靠点的链接或按钮头像,在根元素因重新渲染而被重新附加后,会停止在键盘聚焦时打开提示:新的
status元素(内联status属性会在每次父级渲染时创建)、更改的name、alt、区域设置、调用方 ARIA 或调用方ref,或挂载后才启用的提示。 -
AR5 — 无重复的描述。 只有自定义提示字符串描述根元素;默认名称提示不添加任何描述。
- AR6 — 调用方 ARIA 优先。 调用方的
aria-label、role或aria-hidden在首次渲染及后续状态更新时覆盖派生值。 - AR7 — 目标尺寸。 交互式头像的目标区域至少为 24×24 CSS 像素,或具有 WCAG 2.2 2.5.8 允许的间距。实现差距:
xsm(20px)或 16/20px 的链接或按钮头像尺寸更小,且 AvatarGroup 中的交互式头像会与其邻居重叠。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 照片 | 人物图片,裁剪以填充形状。 | 当前源码和文档 | Prominent | FR1, FR2 |
| 首字母 | 从名称派生的可读替代。 | 当前源码和文档 | Prominent | FR2, FR3 |
| 默认图标 | 无图片或名称时的通用剪影。 | 当前源码和文档 | Supporting | FR2, FR3 |
| 状态点 | 可用性显示在底部内联末尾、裁剪区域之外。 | 当前源码和文档 | Supporting | FR4, FR5, AR2 |
主题化:根元素是 avatar 目标,首字母和默认图标表面是 avatar-fallback 目标;照片继承根元素。状态点的目标属于 component:AvatarStatusDot。消费方解剖结构未命名根部分,因此不声明解剖主题化块。
家族与系统关系¶
family:navigation-destinations和spec:AST-005拥有链接根元素的目的地检查;Avatar 通过共享链接组件采用它们。component:AvatarStatusDot将其标签报告给所属的 Avatar,Avatar 合成该标签(FR5)并放置插槽(FR4)。spec:AST-038FR7 和 FR8 在图层边界处停止组的上下文携带成员资格;FR8 的尺寸、形状、环、重叠和 Tab 停靠点适配仅在一个图层内适用,而键盘所有权不变。component:AvatarGroup向其成员提供尺寸、形状和重叠,并拥有对data-avatar-item根元素的漫游焦点(FR8)。architecture:internationalization拥有合成名称背后的目录。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1–FR3 | Avatar.test.tsx 的回退、首字母、重试和目标测试;在真实 Chromium 中模拟强制颜色模式运行的 AvatarForcedColors.a11y.chromium.spec.ts |
照片、失败、首字母、标点、表情符号、空白名称;lg 盒子;单独、在 GrayText 和 HighlightText 内以及分组的强制颜色模式 |
错误的首字母或图标回退、分割的字素、丢失的重试、缺失的目标、错误的 lg 盒子大小,或强制颜色模式下的首字母在单独使用时未匹配周围系统颜色、在分组使用时保留强制前景色,均会导致失败。缺口:没有测试同时设置 src 和 fallbackSrc,因此 src 优先的顺序未被验证;除 lg 以外的尺寸以及数值尺寸仅在 Avatar.stories.tsx 中可见。 |
audit:Avatar/behavior |
| FR4 | Avatar.test.tsx 的形状和状态测试;Avatar.stories.tsx 的状态 fixtures |
每个带状态的形状;RTL | 缺失状态槽位则失败。缺口:测试仅断言存在性,因此槽位的位置、镜像和偏移仅在渲染的 fixtures 中可见。 | audit:Avatar/layout |
| FR5, AR1, AR2, PR1 | Avatar.test.tsx 的状态名称和包装器测试套件 |
直接、包装、变化、移除标签 | 丢失的组合名称、额外渲染或过时标签均会导致失败。 | audit:Avatar/a11y |
| AR1, AR3 | Avatar.test.tsx 中的“首字母是图片的一部分,而非控件的文本”套件;在真实 Chromium 和 WebKit 中运行的 AvatarLabelInName.a11y.browser.spec.ts(axe 规则 label-content-name-mismatch、有和没有强制颜色模式时绘制的首字母、键盘聚焦时的名称工具提示) |
带首字母的静态、链接和按钮根元素;照片根元素;强制颜色模式 | 如果首字母变成控件的文本、名称不是该人的姓名、首字母离开屏幕,或者工具提示在聚焦时不显示名称,则失败。 | audit:Avatar/a11y |
| FR6, AR3 | Avatar.test.tsx 的交互性测试套件 |
链接、按钮、静态、开发警告 | 错误的根元素、缺失的标记或缺失的警告均会导致失败。缺口:没有测试检查 focus-visible 轮廓。 | audit:Avatar/behavior |
| FR7, AR4, AR5 | Avatar.test.tsx name-tooltip 套件 |
默认、自定义、禁用、空白 | 缺少 Tab 停靠点、重复的描述或丢失的 ref 即失败。缺口:没有测试覆盖分组 avatar 在重新渲染并重新挂载其根元素后的 tooltip:一个新的 status 元素(内联 status prop 会在每次父级渲染时创建一个)、更改后的 name、alt、locale、调用方的 ARIA 或调用方的 ref,或挂载后才开启的 tooltip。 |
audit:Avatar/a11y |
| FR8 | Avatar.test.tsx 分组形状测试;AvatarGroup.test.tsx 尺寸级联、重叠和 roving(漫游)套件;layerScopedContext.test.tsx AvatarGroup 层测试 |
在分组内;在从分组打开的层中;在分组外 | 在分组内 avatar 的 size 或 shape prop 胜出、重叠丢失、交互式 avatar 从 roving(漫游)集合中缺失,或层中的静态 avatar 丢失其 tooltip Tab 停靠点,均失败。缺口:没有测试断言 ring,或层内的尺寸与形状。 | audit:Avatar/behavior |
| FR9, AR6 | Avatar.test.tsx 调用方 ARIA 覆盖套件 |
静态和交互根元素 | 派生值替换调用方的 aria-label、role 或 aria-hidden 即失败。缺口:没有测试覆盖调用方的 tabIndex。 |
audit:Avatar/a11y |
| AR1–AR3, AR5 | 无障碍树证据(spec:AST-009 FR3) |
已命名、装饰性、由 status 组成、交互式 | 缺口:没有无障碍树检查证明计算出的角色、名称或描述;单元测试查询的是 DOM。 | audit:Avatar/a11y |
| AR7 | 浏览器中的 Avatar.stories.tsx 交互式和尺寸 fixtures |
每种尺寸下的交互式 avatar | 缺口:没有自动化的目标尺寸检查;尺寸不足的目标是已记录在案的缺口。 | audit:Avatar/a11y |
决策日志¶
无记录。本记录描述已发布行为。
待解决问题¶
无。
内容边界¶
本文件不重复消费者 prop 表格/示例、当前审计结果、实施步骤或家族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx