跳转至

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-api INV5 将受支持的输入发送到根元素。
  • 分组交互式工具提示在重新渲染时丢失(FR7、AR4)。 在 AvatarGroup 中,作为链接或按钮的头像如果不是该组的制表位,在重新渲染重新挂载其根元素后,当键盘焦点到达它时将不再打开其工具提示:一个新的 status 元素(内联的 status prop 会在每次父级渲染时创建一个)、更改的 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-038 FR7 和 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