From 9bfa80f168e060fe567571325ef716575b2b2026 Mon Sep 17 00:00:00 2001
From: anlyyao <anly_yaw@163.com>
Date: Wed, 9 Sep 2026 16:03:28 +0800
Subject: [PATCH 1/3] fix(avatar): fix image load error fallback and reload
 when image source changes

---
 packages/components/avatar/avatar.less |  8 ++++++++
 packages/components/avatar/avatar.ts   | 18 +++++++++++++-----
 packages/components/avatar/avatar.wxml |  6 +++---
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/packages/components/avatar/avatar.less b/packages/components/avatar/avatar.less
index a5a15b4f9f..c487d34d65 100644
--- a/packages/components/avatar/avatar.less
+++ b/packages/components/avatar/avatar.less
@@ -72,6 +72,14 @@
   &__image {
     width: 100%;
     height: 100%;
+
+    &-alt {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: @spacer;
+      overflow: hidden;
+    }
   }
 
   &--circle {
diff --git a/packages/components/avatar/avatar.ts b/packages/components/avatar/avatar.ts
index b12e4c2fed..30239da8c9 100644
--- a/packages/components/avatar/avatar.ts
+++ b/packages/components/avatar/avatar.ts
@@ -26,6 +26,7 @@ export default class Avatar extends SuperComponent {
     prefix,
     classPrefix: name,
     isShow: true,
+    isImgExist: true,
     zIndex: 0,
     windowWidth: systemInfo.windowWidth,
   };
@@ -52,6 +53,15 @@ export default class Avatar extends SuperComponent {
         ...obj,
       });
     },
+
+    image(image) {
+      // 图片地址变化时重置加载失败标记，避免切换后无法重新渲染
+      if (image) {
+        this.setData({
+          isImgExist: true,
+        });
+      }
+    },
   };
 
   methods = {
@@ -62,11 +72,9 @@ export default class Avatar extends SuperComponent {
     },
 
     onLoadError(e: WechatMiniprogram.CustomEvent) {
-      if (this.properties.hideOnLoadFailed) {
-        this.setData({
-          isShow: false,
-        });
-      }
+      this.setData({
+        isImgExist: !this.properties.hideOnLoadFailed,
+      });
       this.triggerEvent('error', e.detail);
     },
   };
diff --git a/packages/components/avatar/avatar.wxml b/packages/components/avatar/avatar.wxml
index a851deb8ca..e1d902658c 100644
--- a/packages/components/avatar/avatar.wxml
+++ b/packages/components/avatar/avatar.wxml
@@ -28,9 +28,9 @@
       aria-hidden="{{ ariaHidden }}"
     >
       <t-image
-        wx:if="{{image}}"
+        wx:if="{{image && isImgExist}}"
         t-class="{{prefix}}-image {{classPrefix}}__image"
-        t-class-load="{{prefix}}-class-alt"
+        t-class-load="{{classPrefix}}__image-alt {{prefix}}-class-alt"
         style="{{imageProps && imageProps.style || ''}}"
         src="{{image}}"
         mode="{{imageProps && imageProps.mode || 'aspectFill'}}"
@@ -38,7 +38,7 @@
         loading="{{imageProps && imageProps.loading || 'default'}}"
         shape="{{imageProps && imageProps.shape || 'round'}}"
         webp="{{imageProps && imageProps.webp || false}}"
-        error="{{alt || 'default'}}"
+        error="{{imageProps && imageProps.error || alt || 'default'}}"
         bind:error="onLoadError"
       />
       <template

From 0d77fc6b7aee39992c5e7777ca7f7867ac890bd8 Mon Sep 17 00:00:00 2001
From: anlyyao <anly_yaw@163.com>
Date: Wed, 9 Sep 2026 16:04:00 +0800
Subject: [PATCH 2/3] test: update test unit

---
 packages/components/avatar-group/type.ts        |  2 +-
 packages/components/avatar/README.en-US.md      | 10 +++++-----
 .../components/avatar/__test__/index.test.js    | 17 +++++++++++++++--
 packages/components/avatar/type.ts              |  2 +-
 4 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/packages/components/avatar-group/type.ts b/packages/components/avatar-group/type.ts
index 442610a867..1d203fa0a3 100644
--- a/packages/components/avatar-group/type.ts
+++ b/packages/components/avatar-group/type.ts
@@ -4,7 +4,7 @@
  * 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
  * */
 
-import { ShapeEnum } from '../common/common';
+import type { ShapeEnum } from '../common/common';
 
 export interface TdAvatarGroupProps {
   /**
diff --git a/packages/components/avatar/README.en-US.md b/packages/components/avatar/README.en-US.md
index d29ed5a457..896b2ccdf3 100644
--- a/packages/components/avatar/README.en-US.md
+++ b/packages/components/avatar/README.en-US.md
@@ -9,13 +9,13 @@ name | type | default | description | required
 style | Object | - | CSS(Cascading Style Sheets) | N
 custom-style | Object | - | CSS(Cascading Style Sheets)，used to set style on virtual component | N
 alt | String | - | show it when url is not valid | N
-badge-props | Object | - | Typescript：`BadgeProps`，[Badge API Documents](./badge?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/avatar/type.ts) | N
+badge-props | Object | - | Typescript: `BadgeProps`，[Badge API Documents](./badge?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/avatar/type.ts) | N
 bordered | Boolean | false | \- | N
 hide-on-load-failed | Boolean | false | hide image when loading image failed | N
 icon | String / Object | - | \- | N
 image | String | - | images url | N
-image-props | Object | - | Typescript：`ImageProps`，[Image API Documents](./image?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/avatar/type.ts) | N
-shape | String | - | shape。options: circle/round。Typescript：`ShapeEnum`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts) | N
+image-props | Object | - | Typescript: `ImageProps`，[Image API Documents](./image?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/avatar/type.ts) | N
+shape | String | - | shape。options: circle/round。Typescript: `ShapeEnum`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts) | N
 size | String | - | size | N
 
 ### Avatar Events
@@ -47,10 +47,10 @@ name | type | default | description | required
 -- | -- | -- | -- | --
 style | Object | - | CSS(Cascading Style Sheets) | N
 custom-style | Object | - | CSS(Cascading Style Sheets)，used to set style on virtual component | N
-cascading | String | 'left-up' | multiple images cascading。options: left-up/right-up。Typescript：`CascadingValue` `type CascadingValue = 'left-up' \| 'right-up'`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/avatar-group/type.ts) | N
+cascading | String | 'left-up' | multiple images cascading。options: left-up/right-up。Typescript: `CascadingValue` `type CascadingValue = 'left-up' \| 'right-up'`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/avatar-group/type.ts) | N
 collapse-avatar | String | - | \- | N
 max | Number | - | \- | N
-shape | String | - | shape。options: circle/round。Typescript：`ShapeEnum`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts) | N
+shape | String | - | shape。options: circle/round。Typescript: `ShapeEnum`。[see more ts definition](https://github.com/Tencent/tdesign-miniprogram/blob/develop/packages/components/common/common.ts) | N
 size | String | - | size | N
 
 ### AvatarGroup Events
diff --git a/packages/components/avatar/__test__/index.test.js b/packages/components/avatar/__test__/index.test.js
index 5ae843532f..9095851786 100644
--- a/packages/components/avatar/__test__/index.test.js
+++ b/packages/components/avatar/__test__/index.test.js
@@ -67,7 +67,18 @@ describe('Avatar & Avatar Groups', () => {
       expect($text.dom.textContent).toBe('A');
     });
 
-    it(':hideOnLoadFailed', async () => {
+    it(':hideOnLoadFailed=false 图片加载失败后保留图片', async () => {
+      const comp = simulate.render(id);
+      comp.attach(document.createElement('parent-wrapper'));
+
+      const $image = comp.querySelector('.error-avatar-wrapper >>> #image');
+      $image.dispatchEvent('error');
+      await simulate.sleep(20);
+      // 默认 hideOnLoadFailed=false：图片组件仍保留，由 t-image 内部展示错误占位
+      expect(comp.querySelector('.error-avatar-wrapper >>> .t-image')).toBeTruthy();
+    });
+
+    it(':hideOnLoadFailed=true 图片加载失败后移除图片回退字符', async () => {
       const comp = simulate.render(id);
       comp.attach(document.createElement('parent-wrapper'));
 
@@ -80,7 +91,9 @@ describe('Avatar & Avatar Groups', () => {
       });
       $image.dispatchEvent('error');
       await simulate.sleep(20);
-      expect($wrapper.dom.style.display).toBe('none');
+      // 仅移除图片组件（回退展示字符内容），头像 wrapper 仍保留
+      expect($wrapper.dom.style.display).toBe('');
+      expect(comp.querySelector('.error-avatar-wrapper >>> .t-image')).toBeFalsy();
     });
   });
 
diff --git a/packages/components/avatar/type.ts b/packages/components/avatar/type.ts
index 2e7af6b36e..f89fe05079 100644
--- a/packages/components/avatar/type.ts
+++ b/packages/components/avatar/type.ts
@@ -6,7 +6,7 @@
 
 import { BadgeProps } from '../badge/index';
 import { ImageProps } from '../image/index';
-import { ShapeEnum } from '../common/common';
+import type { ShapeEnum } from '../common/common';
 
 export interface TdAvatarProps {
   /**

From b7c80ca80ba9ede9a544acacd00e73a8fd82e1d6 Mon Sep 17 00:00:00 2001
From: tdesign-bot <tdesign@tencent.com>
Date: Wed, 9 Sep 2026 08:17:09 +0000
Subject: [PATCH 3/3] chore: stash changelog [ci skip]

---
 packages/tdesign-miniprogram/.changelog/pr-4635.md | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 packages/tdesign-miniprogram/.changelog/pr-4635.md

diff --git a/packages/tdesign-miniprogram/.changelog/pr-4635.md b/packages/tdesign-miniprogram/.changelog/pr-4635.md
new file mode 100644
index 0000000000..54f0f299fd
--- /dev/null
+++ b/packages/tdesign-miniprogram/.changelog/pr-4635.md
@@ -0,0 +1,6 @@
+---
+pr_number: 4635
+contributor: anlyyao
+---
+
+- fix(Avatar): 修复图片加载失败后回退展示及切换图片地址无法重新加载的问题 @anlyyao ([#4635](https://github.com/Tencent/tdesign-miniprogram/pull/4635))