Avatar
Mẫu chuẩnĐại diện cho một người hoặc một tổ chức bằng ảnh. Không có ảnh thì hiện chữ trên nền nhạt, chữ và viền đậm hơn cùng màu. Không có chữ thì hiện Female02Icon hoặc User02Icon. Ảnh vỡ không bao giờ hiện. Có 3 size và một chấm trạng thái hiện diện tuỳ chọn.
Playground
Chuyển Nguồn ảnh sang "ảnh hỏng" và quan sát: không có biểu tượng ảnh vỡ nào xuất hiện, chữ cái đầu hiện ra thay thế và ở lại vĩnh viễn.
idle — chưa bắt đầu tải.
import { Avatar, AvatarFallback, AvatarImage } from "@nexobox/ui";
<Avatar size="md">
<AvatarImage src="/nexoframe-ds-kit/components/avatar-photo-sample.png" alt="Nguyễn Văn A" />
<AvatarFallback seed="Nguyễn Văn A">NA</AvatarFallback>
</Avatar>Khi nào sử dụng
Nên dùng
Đại diện cho một con người hoặc một tổ chức: danh sách người dùng, hàng hội thoại, thanh tài khoản, danh sách thành viên.
Tránh dùng
Logo của một kênh bên thứ ba (Facebook, Zalo, ngân hàng) — đó là ChannelMark, một primitive khác đại diện cho một loại thực thể khác. Làm nút — bọc trong Button hoặc link nếu cần bấm được. Làm ảnh minh hoạ nội dung.
Anatomy
| # | Phần | Ghi chú |
|---|---|---|
| 1 | Root | span do Radix Avatar.Root dựng. Hình tròn, nền --nf-semantic-surface-subtle, kích thước theo prop size. |
| 2 | Image | Chỉ render khi ảnh đã tải xong thành công. Lấp đầy Root, cắt theo khung. |
| 3 | Fallback | Có chữ: nền nhạt, chữ semibold, viền hairline pha nhạt cùng màu. Không chữ: Female02Icon khi gender là female, còn lại User02Icon trắng trên đĩa xám, viền trắng mảnh. |
| 4 | AvatarStatus | Sub-component tuỳ chọn, truyền làm children của Avatar. Chấm tròn ở góc dưới-phải, có viền tách khỏi ảnh bên dưới. |
Không có prop name, không có hàm sinh chữ cái đầu trong primitive. Cắt tên người là một luật nghiệp vụ và phụ thuộc ngôn ngữ, không thuộc primitive thị giác — initialsFor ở trang này là minh hoạ cục bộ, không thuộc package. Primitive cũng không suy giới tính từ tên. gender="female" chỉ khi dữ liệu đã ghi nhận; bỏ trống thì icon là User02Icon.
Sizes
Ba size trên thang riêng của Avatar, không phải thang control. Mặc định là md. sm dùng chữ caption 12px; md và lg dùng chữ UI 14px. Cả ba bậc dùng weight semibold. Chấm trạng thái co theo cùng prop size — vòng của sm là 1px, vòng của md và lg là 2px. Truyền đúng size của Avatar cha vào AvatarStatus.
| Size | Kích thước | Chấm trạng thái | Token |
|---|---|---|---|
| sm | 24px | 6px | --nf-component-avatar-sm-size |
| md (mặc định) | 32px | 8px | --nf-component-avatar-size |
| lg | 40px | 10px | --nf-component-avatar-lg-size |
States
Không có variant, không có nhóm avatar xếp chồng. Trạng thái tải ảnh (do Radix quản lý) và trạng thái hiện diện (do AvatarStatus vẽ) là hai trục độc lập, chồng lên nhau tự do — một avatar đang tải ảnh vẫn có thể mang một chấm trạng thái.
Ảnh tải xong, Image hiện.
Mô phỏng — ảnh thật tải quá nhanh trên máy cục bộ để bắt được khung hình loading. Hình dạng giống hệt khung loading thật.
Ảnh lỗi. Chữ cái đầu hiện thay, không có biểu tượng ảnh vỡ.
Không có src. Fallback hiện ngay.
Fallback vẫn cân giữa với một chữ cái duy nhất.
Loading và error: có. Không có chữ là một trạng thái: icon người. Nữ dùng Female02Icon. Nam, không rõ, hoặc không truyền gender dùng User02Icon.
User02Icon trắng trên đĩa xám, viền trắng mảnh.
Female02Icon khi gender là female.
Cùng User02Icon. Bộ icon chỉ có hai glyph.
Đang hoạt động, sẵn sàng nhận tin nhắn ngay.
Đang trực tuyến nhưng không muốn bị làm phiền.
Đã đăng nhập nhưng không hoạt động một thời gian.
Một tác vụ nền đang chạy cho người/tổ chức này.
Không kết nối. Màu trung tính, không phải màu trạng thái.
Design tokens
Root đọc --nf-semantic-surface-subtle, --nf-component-avatar-radius, và một trong ba --nf-component-avatar-size / -sm-size / -lg-size theo prop size. Fallback có chữ đọc một cặp --nf-component-avatar-tone-*-fill / -ink (cobalt, jade, coral, và ba cặp deep). Fallback không chữ đọc --nf-foundation-color-neutral-400 và --nf-foundation-color-neutral-0. Viền chữ là mực pha 45% trong suốt, dày --nf-foundation-stroke-hairline. Weight là --nf-foundation-font-weight-semibold. Cỡ chữ kế thừa từ Root: sm đọc caption, md và lg đọc UI. AvatarStatus đọc --nf-component-avatar-status-size / -status-sm-size / -status-lg-size theo cùng prop size, viền qua --nf-component-avatar-status-sm-ring-width (sm) hoặc --nf-component-avatar-status-ring-width (md, lg) và --nf-component-avatar-status-ring-color, và màu qua một trong năm token trạng thái: --nf-semantic-status-success-icon (online), --nf-semantic-status-danger-icon (busy), --nf-semantic-status-warning-icon (away), --nf-semantic-status-information-icon (syncing), hoặc --nf-semantic-text-muted (offline).
API & triển khai
| Prop | Mặc định | Quy ước |
|---|---|---|
| size | md | Trên Avatar. sm (24px), md (32px), lg (40px). |
| onLoadingStatusChange | — | Trên Avatar (Root). Phát khi trạng thái tải đổi. |
| src | — | Trên AvatarImage. Nguồn ảnh. |
| alt | — | Trên AvatarImage. Tên truy cập, hoặc rỗng nếu tên đã hiện bằng chữ cạnh đó. |
| delayMs | — | Trên AvatarFallback. Trì hoãn hiện fallback, chống chớp khi ảnh về nhanh. |
| children | — | Trên AvatarFallback. Chuỗi thì hiện chữ và cặp màu. Bỏ trống thì hiện icon. |
| gender | — | Trên AvatarFallback. female → Female02Icon. male, unknown, hoặc bỏ trống → User02Icon. Chỉ khi không có chữ. |
| seed | chuỗi chữ | Trên AvatarFallback. Khoá chọn một trong sáu cặp màu. |
| status | — | Trên AvatarStatus. Bắt buộc. online, busy, away, syncing hoặc offline. |
| size (AvatarStatus) | md | Nên khớp size của Avatar cha để chấm nằm đúng vị trí. |
| label | — | Trên AvatarStatus. Bắt buộc. Tên trạng thái, hoặc false khi cạnh đó đã có chữ. |
AvatarProps, AvatarImageProps, AvatarFallbackProps đều là ComponentPropsWithoutRef của phần Radix tương ứng — mọi thuộc tính gốc đều truyền thẳng xuống. AvatarStatusProps là ComponentPropsWithoutRef<"span">.