Avatar 头像

用户或成员的头像。给了 src 显示图片；没给、图片加载中或加载失败时显示默认插槽里的内容（首字母或图标）。

图片与 fallback

给了 src 显示图片；没给、加载中或加载失败时显示默认插槽里的首字母或图标。alt 在图片上是替代文本，在 fallback 上是宿主的 aria-label。

<pt-avatar src="data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 viewBox=%270 0 80 80%27%3E%3Crect width=%2780%27 height=%2780%27 fill=%27%238fb3d9%27/%3E%3Ccircle cx=%2740%27 cy=%2731%27 r=%2715%27 fill=%27%23f1d3bd%27/%3E%3Cpath d=%27M12 80c2-18 14-28 28-28s26 10 28 28z%27 fill=%27%232f4b6e%27/%3E%3C/svg%3E" alt="张三">张</pt-avatar>
<pt-avatar alt="张三">张</pt-avatar>
<pt-avatar src="/does-not-exist.png" alt="李四">李</pt-avatar>

图片直接渲染成 <img>，由它自己的 load / error 决定显示哪一边：服务端渲染出来的 HTML 里就有 img， 浏览器解析到就开始下载，不必等脚本加载完。hydrate 之前图片已经有结果的，组件加载时会补发一次 ptLoad / ptError。

尺寸

三档尺寸

24 / 32 / 40，与控件高度同一条刻度；默认 lg。

<pt-avatar size="sm" alt="张三">张</pt-avatar>
<pt-avatar size="md" alt="张三">张</pt-avatar>
<pt-avatar size="lg" alt="张三">张</pt-avatar>

尺寸写在宿主上：使用方直接给元素写 width / height（或 class="h-16 w-16"）就能改大小， 里面的图片与底色圆跟着撑满。改成方形头像设 --pt-avatar-radius。

延迟显示 fallback

延迟显示 fallback

图片通常很快就加载完，立刻出首字母会闪一下。设了 delay（毫秒）后，这段时间里只显示底色圆；加载失败时不再等。

<pt-avatar src="data:image/svg+xml,%3Csvg xmlns=%27http://www.w3.org/2000/svg%27 viewBox=%270 0 80 80%27%3E%3Crect width=%2780%27 height=%2780%27 fill=%27%238fb3d9%27/%3E%3Ccircle cx=%2740%27 cy=%2731%27 r=%2715%27 fill=%27%23f1d3bd%27/%3E%3Cpath d=%27M12 80c2-18 14-28 28-28s26 10 28 28z%27 fill=%27%232f4b6e%27/%3E%3C/svg%3E" alt="张三" delay="600">张</pt-avatar>

src 变化时回到加载中，delay 重新计时。没给 src 时不延迟 —— 没有要等的图片。

无障碍

• 图片显示时由 img 的 alt 朗读；没给 alt 时按装饰图处理（alt=""）。
• fallback 显示时，宿主挂 role="img" 与 aria-label（取 alt），读屏念的是「张三」而不是首字母「张」。

API

属性

属性	Attribute	类型	默认值	说明
alt	alt	string | undefined	—	替代文本。图片显示时是 img 的 alt，fallback 显示时是宿主的 aria-label
delay	delay	number | undefined	—	fallback 延迟多久才出现（毫秒）。图片通常很快就加载完，立刻出首字母会闪一下； 设了之后这段时间里只显示底色圆、不显示插槽内容。不设（或 ≤ 0）时立即显示。没给 src 时不延迟 —— 没有要等的图片。 加载中改它：还在等的按新值从当下重新计时；fallback 已经露出来的不再藏回去
size	size	"lg" | "md" | "sm"	'lg'	尺寸档位：sm 24px（字 12/16）、md 32px（字 13/20）、lg 40px（字 14/20）。 默认 lg 与源包一致；包装层传 undefined 时属性被摘掉，样式表里无属性即 lg，不需要 JS 兜底
src	src	string | undefined	—	图片地址。变化时重新进入加载中（先显示 fallback，delay 重新计时）

事件

事件	detail 类型	说明
ptError	{ src: string; }	图片加载失败，此后一直显示 fallback，直到 src 变化
ptLoad	{ src: string; }	图片加载成功（hydrate 前就已加载完的，在组件加载时补发一次）

插槽

名称	说明
（默认）	fallback 内容：首字母或图标。图片加载中 / 失败 / 未给 src 时显示

可定制的内部元素（::part()）

part	说明
fallback	fallback 容器（底色圆）
image	内部的 img

CSS 变量

变量	说明
--pt-avatar-radius	圆角，默认 --pt-radius-full（正圆）；方形头像设成 --pt-radius-md 之类