Ant Design Avatar 图片加载失败降级机制：src、icon 与 children 的优先级解析

本文以 Avatar 组件官方演示 fallback（“图片不存在时”）为主线，完整讲解图片头像加载失败时的降级（fallback）规则：为什么 src 为 ReactElement 时组件会保留 src、字符串地址失效时如何依次回退到 icon 与 children，并结合 Avatar 源码、onError 钩子与 单元测试 说明整条降级链路的实现原理与接管方式。

官方演示：“图片不存在时”

Avatar 组件文档（index.zh-CN.md）将该演示注册为：

<code src="./demo/fallback.tsx" debug>图片不存在时</code>

演示代码见 demo/fallback.tsx：

import React from 'react';
import { Avatar, Space } from 'antd';

const App: React.FC = () => (
  <Space>
    <Avatar shape="circle" src="http://abc.com/not-exist.jpg">
      A
    </Avatar>
    <Avatar shape="circle" src="http://abc.com/not-exist.jpg">
      ABC
    </Avatar>
  </Space>
);

export default App;

两个 Avatar 都传入了一个刻意不存在的图片地址 http://abc.com/not-exist.jpg，因此 <img> 会触发 error 事件，组件进入降级流程：第一个头像显示单个字符 A，第二个显示 ABC。由于 ABC 宽度超出了圆形头像的可视区域，源码还会通过 transform: scale() 自动缩小字符，使其在保持两侧留有 gap 间距的前提下完整可见。

演示说明文档 demo/fallback.md 给出的核心结论是：

图片不存在时，如果 src 本身是个 ReactElement，会尝试回退到 src，否则尝试回退到 icon，最后回退到显示 children。

一句话概括降级优先级：

1. src（ReactElement）：src 是 React 元素时，直接渲染该元素本身，组件级降级不介入；
2. icon：字符串 src 加载失败时，若提供了 icon，优先显示图标；
3. children：都没有时，最终回退到头像内部的子节点（通常是文字）。

组件 API 文档中还有一条补充提示（index.zh-CN.md）：你可以设置 icon 或 children 作为图片加载失败的默认 fallback 行为，优先级为 icon > children。

源码解析：Avatar.tsx 的渲染决策

降级行为全部实现在 components/avatar/Avatar.tsx 中，核心是一个字符串 src 的“存活”状态位与一段有序的条件渲染。

状态位：isImgExist

// components/avatar/Avatar.tsx#L67-L69
const [scale, setScale] = React.useState(1);
const [mounted, setMounted] = React.useState(false);
const [isImgExist, setIsImgExist] = React.useState(true);

isImgExist 初始为 true，即先乐观地认为图片存在、直接渲染 <img>。

错误处理：handleImgLoadError

// components/avatar/Avatar.tsx#L108-L113
const handleImgLoadError = () => {
  const errorFlag = onError?.();
  if (errorFlag !== false) {
    setIsImgExist(false);
  }
};

<img> 的 onError 回调被绑定到字符串 src 上（见下文渲染分支）。当图片加载失败时：

• 先调用用户传入的 onError 回调；
• 只有当 onError 的返回值不等于 false（即未显式接管）时，才把 isImgExist 置为 false，从而让渲染流程落到 icon / children 分支；
• 如果 onError 返回 false，组件保留当前的 <img> 渲染，交由开发者自行实现降级（例如切换到备用地址），这也是 API 表格中 onError 一行的含义：“图片加载失败的事件，返回 false 会关闭组件默认的 fallback 行为”。

onError 的类型定义在 Avatar.tsx#L42-L44：

/* callback when img load error */
/* return false to prevent Avatar show default fallback behavior, then you can do fallback by yourself */
onError?: () => boolean;

渲染分支：降级优先级在 if/else 序列中体现

// components/avatar/Avatar.tsx#L158-L223（节选）
const hasImageElement = React.isValidElement(src);

// ...
let childrenToRender: React.ReactNode;
if (typeof src === 'string' && isImgExist) {
  childrenToRender = (
    <img
      src={src}
      draggable={draggable}
      srcSet={srcSet}
      onError={handleImgLoadError}
      alt={alt}
      crossOrigin={crossOrigin}
    />
  );
} else if (hasImageElement) {
  childrenToRender = src;
} else if (icon) {
  childrenToRender = icon;
} else if (mounted || scale !== 1) {
  // 用 ResizeObserver 包裹的 .ant-avatar-string 渲染 children，
  // 并通过 scale 变换保证文字在头像内居中且不溢出
  childrenToRender = (
    <ResizeObserver onResize={setScaleParam}>
      <span className={`${prefixCls}-string`} ref={avatarChildrenRef} style={childrenStyle}>
        {children}
      </span>
    </ResizeObserver>
  );
} else {
  // 首次挂载前：先以 opacity: 0 渲染一次，避免带错误缩放值闪烁
  childrenToRender = (
    <span className={`${prefixCls}-string`} style={{ opacity: 0 }} ref={avatarChildrenRef}>
      {children}
    </span>
  );
}

把文档结论与这段代码逐条对应：

• 第一分支只匹配“字符串 + 图片存活”：typeof src === 'string' && isImgExist。只有此时才由 antd 托管 <img> 并监听其 error 事件。字符串 src 一旦报错（isImgExist 变 false），这个分支就不再命中，流程自然落到后面的分支——这就是降级发生的入口。
• ReactElement 分支：hasImageElement（React.isValidElement(src)）为 true 时直接渲染 src 本身。注意这条分支不依赖 isImgExist——antd 只给“自己创建的 <img>”绑定 onError，对开发者传入的元素不干预。因此 src 是 ReactElement 时，无论其中的图片是否失效，组件都“回退到 src”，错误处理由元素自己负责（例如传一个带 onError 的自定义 <img> 或 <picture>）。src 支持 ReactNode 自 4.8.0 起开放（见 API 表格）。
• icon 分支：字符串 src 失效且没有传 ReactElement 时，若有 icon 则显示图标，优先级高于 children。
• children 分支：最终兜底。这里还附带了“自动调整字符大小”的能力：通过 ResizeObserver 监听容器与文字宽度，计算 scale = (容器宽 - gap*2) / 文字宽（见 setScaleParam，gap 默认值为 4，在 Avatar.tsx#L62 处解构）。演示中 ABC 显示得比 A 小，正是这条缩放逻辑在降级后的体现。
• 首帧不闪动：mounted 为 false 且 scale === 1 时，先以 opacity: 0 渲染 children 占位（Avatar.tsx#L217-L222），待 ResizeObserver 拿到真实尺寸后再以正确缩放值显示，避免文字先以大字号闪现。

与降级相关的 class 变化

外层 span 的 className 由以下片段控制（Avatar.tsx#L162-L176）：

{
  [`${prefixCls}-image`]: hasImageElement || (src && isImgExist),
  [`${prefixCls}-icon`]: !!icon,
}

• 图片存活或 src 为 ReactElement 时，根节点带 ant-avatar-image；
• 字符串 src 失效后 isImgExist 为 false，ant-avatar-image 被移除，根节点呈现为普通头像（灰底 + 文字/图标）；
• 只要传了 icon 就会带 ant-avatar-icon。

从快照可以直观验证这一点：加载失败后的快照（Avatar.test.tsx.snap#L87-L98）是

<span class="ant-avatar ant-avatar-circle css-var-root ant-avatar-css-var">
  <span class="ant-avatar-string" style="transform: scale(1);">A</span>
</span>

没有任何 ant-avatar-image，内部是 .ant-avatar-string；而 onError 接管后成功换源的快照（Avatar.test.tsx.snap#L138-L146）则重新带上了 ant-avatar-image 和 <img>。

onError：接管默认降级并实现自动重试

默认降级是“一次性”的：图片失效就换图标/文字。若想在失效后自行重试（如切换到 CDN 备用地址），只需让 onError 返回 false 并更换 src。仓库测试 Avatar.test.tsx#L65-L85 演示了完整模式：

it('should handle onError correctly', () => {
  const Foo: React.FC = () => {
    const [avatarSrc, setAvatarSrc] = useState<string>(LOAD_FAILURE_SRC);
    const onError = (): boolean => {
      setAvatarSrc(LOAD_SUCCESS_SRC); // 切换到可用的备用地址
      return false; // 关闭 antd 默认 fallback
    };
    return <Avatar src={avatarSrc} onError={onError} />;
  };
  // 触发 img error 后，img 的 src 变为备用地址，且重新带 ant-avatar-image class
});

这套“换源重试”能生效，依赖源码里的一个复位副作用（Avatar.tsx#L101-L104）：

React.useEffect(() => {
  setIsImgExist(true);
  setScale(1);
}, [src]);

src 变化时，isImgExist 被重置回 true，渲染重新进入“字符串 + 图片存活”分支、再次挂载新的 <img>；若新地址加载成功，头像恢复图片形态。测试用例 should show image on success after a failure state（Avatar.test.tsx#L87-L114）验证了完整往返：先用失败地址触发 error，断言出现 .ant-avatar-string（即 children 兜底已生效、且文字不带 opacity: 0）；再 rerender 一个成功地址，断言节点重新出现 ant-avatar-image 与 <img>。

需要注意的边界：

• onError 返回 false 时，若不更换 src，<img> 会原样保留并持续处于错误态（浏览器层面），不会自动回落到 icon/children，接管责任完全在开发者；
• onError 只作用于字符串 src。src 为 ReactElement 时 antd 不绑定 onError，需要在传入的元素上自行监听。

与降级链路配合的常用属性

结合 API 文档 与 AvatarProps 定义，下面几个属性与图片降级直接相关：

属性	类型	说明	与降级的关系
src	string | ReactNode	图片地址或图片元素	字符串走组件托管的 <img> + onError 链路；ReactNode 直接渲染并“回退到 src”（ReactNode 支持自 4.8.0）
icon	ReactNode	自定义图标	字符串 src 失效时的第一顺位兜底，优先级高于 children
children	ReactNode	文字等子节点	最终兜底，并自动 scale 缩放适配
alt	string	图像无法显示时的替代文本	透传给 <img alt>，图片失效时由浏览器/读屏软件使用
onError	() => boolean	图片加载失败回调	返回 false 关闭默认 fallback，实现自定义重试
crossOrigin	'anonymous' | 'use-credentials' | ''	CORS 属性	透传给 <img crossOrigin>，CORS 策略不当也会表现为加载失败（4.17.0 起支持）
gap	number	字符距左右边界像素，默认 4	决定 children 兜底时缩放公式中的留白

测试用例如何覆盖降级链路

components/avatar/tests/Avatar.test.tsx 中对 fallback 有四个针对性用例，均可作为行为依据：

1. should render fallback string correctly（L54-L63）：渲染 <Avatar src="http://error.url">Fallback</Avatar>，手动 fireEvent.error 触发图片错误，断言容器中出现 .ant-avatar-string 且内容为 Fallback——验证“最终回退到 children”；
2. should handle onError correctly（L65-L85）：onError 返回 false 并换源后，<img> 的 src 变为备用地址且快照重新带 ant-avatar-image——验证“返回 false 关闭默认 fallback”；
3. should show image on success after a failure state（L87-L114）：先失败后换成功地址，验证失败→children 兜底→成功→恢复图片的完整状态迁移；
4. fallback（L167-L178）：与官方 demo 相同形态（shape="circle" + 无效地址 + 子节点 A）的快照用例，对应快照输出见 Avatar.test.tsx.snap#L87-L98。

此外，demo 级快照 demo.test.tsx.snap#L578 与 demo-extend.test.ts.snap#L679 分别对 fallback.tsx 的默认渲染和 RTL 扩展上下文做了固化，说明该演示在文档站快照测试中被长期覆盖。

实践建议

• 只传文字场景：src + children 即可，失效时显示文字，长文字会被自动缩放，无需额外处理；
• 需要品牌一致性：优先提供 icon（如用户图标），它在 src 失效时优先于 children 显示；
• 多 CDN / 弱网环境：实现 onError 重试，返回 false 并在回调内切换 src（可叠加本地重试计数防止死循环），依赖 Avatar.tsx#L101-L104 的 src 复位副作用完成重新加载；
• 需要精细控制（如 <picture>、多格式源）：直接把 src 写成 ReactElement，此时组件级降级不介入，错误处理逻辑写在元素自身的事件处理中；
• 无障碍：给 <img> 场景补上 alt，图片失效时替代文本仍可供浏览器与读屏软件使用。

整体来看，Avatar 的降级机制是“乐观渲染 + 单状态位 + 有序分支”的实现：先用 isImgExist 假定图片可用，error 事件翻转状态位，再按 ReactElement src → icon → children 的顺序逐级回落；onError 返回 false 是唯一能中断这条默认链路的入口，也是实现自定义重试的标准姿势。