iter(g325): avatar 破图自动回退文字头像，不再露浏览器碎图标

packages/skin/ui/src/avatar.ts

@@ -1,15 +1,17 @@
 import { h } from '@ui-arch/frame';
 import type { AvatarProps } from './types.js';
 
-/*** 头像：有 src 渲染图片（alt 用名称），否则用名称首字做占位；尺寸与语义底色由 props 决定 ***/
+/*** 头像：有 src 渲染图片（alt 用名称），否则用名称首字做占位；src 加载失败就地回退文字头像，尺寸与语义底色不变 ***/
 export function avatar(props: AvatarProps): HTMLElement {
   const size = `${props.size ?? 32}px`;
+  const textAvatar = (): HTMLElement =>
+    h('span', { class: 'ua-avatar-text', role: 'img', 'aria-label': props.name }, firstChar(props.name)); // 文字头像补 role=img，aria-label 才会被读屏当名称播报
+  const img = props.src ? h('img', { class: 'ua-avatar-img', src: props.src, alt: props.name }) : null;
+  img?.addEventListener('error', () => img.replaceWith(textAvatar())); // 破图兜底：碎图标比空白更刺眼，回退首字占位
   return h(
     'span',
     { class: `ua-avatar ua-avatar-${props.variant ?? 'default'}`, style: `width:${size};height:${size}`, title: props.name },
-    props.src
-      ? h('img', { class: 'ua-avatar-img', src: props.src, alt: props.name })
-      : h('span', { class: 'ua-avatar-text', role: 'img', 'aria-label': props.name }, firstChar(props.name)), // 文字头像补 role=img，aria-label 才会被读屏当名称播报
+    img ?? textAvatar(),
   );
 }
 

packages/skin/ui/ua.manifest.json

@@ -29,7 +29,7 @@
       "card(props, ...children)：卡片容器",
       "badge(props)：徽标，variant = default | success | warning | danger",
       "tag(props)：可关闭标签，variant 五档语义色，closable + onClose 支持从数据源移除（纯展示请用 badge）",
-      "avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，size 可调 + 四档语义底色",
+      "avatar(props)：头像，有 src 渲染图片（alt 用名称）、无 src 用首字占位，src 加载失败自动回退文字头像，size 可调 + 四档语义底色",
       "alert(props)：提示条，variant 四档语义色 + 可选 title 与 closable 关闭按钮，role=alert 读屏可播报",
       "toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失（悬停暂停、移出续时），出入场微动画；showToast(props) 为完整入参版本（closable 显示关闭按钮，同屏最多 4 条）",
       "tooltip(props, trigger)：包裹式悬浮提示，hover / 键盘聚焦延迟出场，Esc 收起；触摸屏按下即出、抬手延迟 1.2s 收起，气泡 pointer-events: none 不挡点击",
@@ -1019,7 +1019,8 @@
           "只传 name：用名称首字做占位（中文取首字、英文大写），底色走 accent 淡化，暗色自动适配",
           "有图片就传 src：渲染 img 并用 name 作 alt，读屏语义完整；图片缺失时由浏览器 alt 兜底",
           "尺寸用 size（像素）控制，头像不参与布局拉伸（flex:none），可安全排进 .row 与表格单元格",
-          "需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌"
+          "需要区分类别（在线/告警）时用 variant 换底色档，颜色一律来自令牌",
+          "src 加载失败（404 / 断网）时自动回退为文字头像：首字占位、role=img 与 aria-label 不变，尺寸与语义底色保持，不会露出浏览器碎图标"
         ]
       },
       {
@@ -4633,4 +4634,4 @@
       }
     ]
   }
-}
+}