Avatar

An image element with a fallback for representing the user.

Overview

三种装载路径：内嵌照片、首字母 fallback、以及图片加载失败 → fallback。

GPUI · Live previewGPUI WASM

Installation

Avatar 是单个 Rust 文件（src/avatar.rs）。图片走 gpui 的真实 img 元素 —— 演示用的是 4 张内嵌 JPEG 小头像（assets/avatar-*.jpg，每张约 3KB），解码成 RenderImage 后走真实 img 管线；换成你自己的 ImageSource（URI / Embedded / Render）即可。

Cargo.toml

1[dependencies]2gpui-kit = "0.6.6"3image = { version = "0.25", default-features = false, features = ["jpeg"] }45# avatar.rs renders real pixels through gpui's img6# element — bundled JPEGs decode once into cached7# RenderImage frames, so no network is needed.

Download runnable example

Terminal

1# Download the runnable example crate, then:2cargo run --locked -- --avatar34# Other demos:5cargo run --locked -- --avatar badge6cargo run --locked -- --avatar badge-icon7cargo run --locked -- --avatar group8cargo run --locked -- --avatar group-count9cargo run --locked -- --avatar group-icon10cargo run --locked -- --avatar sizes

Usage

Avatar 是 render-once 元素（IntoElement），builder 配置图片源、首字母 fallback、尺寸与角标；group 叠压由调用方用负外边距组合。

Example.rs

1use justdo_command::avatar::{Avatar, AvatarBadge, AvatarImage, AvatarSize};23// A stack of overlapping avatars or a standalone one —4// Avatar is a render-once element, drop it into any container.5div().child(6    Avatar::new()7        .image(AvatarImage::Photo(0))8        .initials("CN")9        .badge(AvatarBadge::Dot),10)

网页预览与桌面端运行同一份 Rust / GPUI 组件。

Composition

组合结构对齐 shadcn/ui 的 Avatar / AvatarGroup。

Structure

1Avatar                    circular root, self-rounded quads2├── AvatarImage           .image(..) -> img + ObjectFit::Cover3├── AvatarFallback        .initials(..) — shown on missing source4└── AvatarBadge           .badge(..) — bottom-right status dot56AvatarGroup               overlapping row: -10px margin + ring7├── Avatar × N8└── AvatarGroupCount      "+3" circle — or an icon in the same slot

Example.rs

1// Pictures go through gpui's image pipeline, so the2// fallback is real: point .image(..) at a source that3// fails to decode and the initials render instead.4Avatar::new()5    .image(AvatarImage::Broken)   // -> fallback6    .initials("ER");

Notes

Circular clipping. GPUI 的 overflow_hidden 裁剪是矩形的，不会沿圆角裁子元素 —— 圆形头像要给每个绘制 quad（img、fallback 块）各自设置 .rounded(px(9999.))。avatar.rs 已处理。

Group overlap. -10px 外边距 + 每个头像 .border_2() 页面色描边，即可得到 shadcn 的分割叠压效果。

Accessibility

Semantics

头像用图片或首字母均可识别用户；状态角标带独立含义（在线/忙碌），以 badge 颜色 + 图形表达。纯展示组件，无键盘焦点。

Fallback

图片加载失败始终渲染首字母 fallback —— 不依赖网络成功，也避免空白占位。fallback 文字颜色与背景保持可读对比度。

API Reference

元素暴露的 builder 方法。

API	Signature	Notes
`Avatar::new()`	`-> Avatar`	Default size, no image — initials only.
`.image(..)`	`AvatarImage`	Photo(seed) \| Broken — real img element path.
`.initials(..)`	`impl Into<SharedString>`	Fallback text shown when no image or load fails.
`.size(..)`	`AvatarSize`	Sm 24 \| Default 32 \| Lg 40 diameter.
`.badge(..)`	`AvatarBadge`	Dot \| Icon — bottom-right status indicator with ring.
`.ring(..)`	`impl Into<Hsla>`	Page-surface color behind the badge/group ring.
`.dark(bool)`	`bool`	Dark scheme for fallback bg, ink and default ring.

Source & inspiration

结构与视觉参考 shadcn/ui Avatar 。本页交互由 Rust / GPUI 绘制，基础样式来自 gpui-kit 。