Avatarv1.0.2
تصویر پروفایل کاربر؛ اگر تصویر نباشد یا بار نشود، حروف اول نام (فارسی یا انگلیسی) یا یک آیکون جایگزین می‌شود. رنگ، اندازه، شعاع گوشه و قاب‌دار بودن محورهای مستقل‌اند و AvatarGroup چند آواتار را روی‌هم‌افتاده کنار هم می‌چیند.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/avatar.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/avatar.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/avatar.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/avatar.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from "@/components/ui/avatar"
// سریع: تصویر یا نام را مستقیم بده
<Avatar src="/avatar.png" name="الناز رضایی" color="primary" />
// دستی: کنترل کامل روی تصویر و جایگزین
<Avatar>
<AvatarImage src="/avatar.png" alt="الناز" />
<AvatarFallback>ال</AvatarFallback>
</Avatar>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
Avatar به دو شکل قابل استفاده است. اگر src یا name مستقیم به خودِ Avatar بدهید، تصویر و جایگزین (حروف اول یا آیکون) خودکار ساخته می‌شوند؛ برای اکثر موارد همین کافی است.
اگر به کنترل کامل روی محتوای تصویر یا جایگزین نیاز دارید (مثلاً یک آیکون یا JSX دلخواه به‌جای حروف اول)، همان الگوی قبلی هم کار می‌کند: AvatarImage و AvatarFallback را دستی به‌عنوان فرزند Avatar بگذارید؛ در این حالت پراپ‌های name/src/icon/getInitials روی خودِ Avatar نادیده گرفته می‌شوند و فرزندان دستی رندر می‌شوند.
رنگ، اندازه، شعاع گوشه، قاب‌دار و غیرفعال بودن در هر دو حالت یکسان کار می‌کنند و وقتی داخل AvatarGroup باشند، مقدار پیش‌فرضشان از گروه به ارث می‌رسد مگر روی خودِ Avatar صریح ست شده باشد.
دسترس‌پذیری
- وقتی src ندهید یا تصویر بار نشود، حروف اول name یا آیکون جایگزین همیشه چیزی نشان می‌دهد؛ آواتار هیچ‌وقت کاملاً خالی نمی‌ماند.
- alt تصویر از name پر می‌شود؛ اگر متن دیگری لازم دارید (مثلاً «لوگوی برند X»)، alt را جدا بدهید.
- AvatarGroup نقش role="group" دارد تا صفحه‌خوان مجموعه را یک واحد معرفی کند.
- پراپ focusable آواتار را با Tab قابل‌دسترس می‌کند؛ فقط وقتی بدهید که خودِ آواتار عمل مستقلی دارد (مثلاً باز کردن پروفایل)، نه برای تزیین صرف.
- disabled هم پوینتر را غیرفعال می‌کند و هم aria-disabled می‌گذارد تا صفحه‌خوان بفهمد این آواتار در حال حاضر قابل‌تعامل نیست.
مرجع API
Avatar
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| name | string | — | نام صاحب آواتار؛ وقتی تصویری نیست یا بار نشده، حروف اول آن (فارسی یا انگلیسی) جایگزین می‌شود. |
| src | string | — | آدرس تصویر. |
| alt | string | name | متن جایگزین تصویر. |
| icon | React.ReactNode | — | آیکون جایگزین دلخواه به‌جای حروف اول، برای وقتی name نیست. |
| getInitials | (name: string) => string | — | استخراج سفارشی حروف اول از name؛ پیش‌فرض هم فارسی هم انگلیسی را پوشش می‌دهد. |
| size | "sm" | "default" | "lg" | "default" | اندازهٔ آواتار. |
| color | "default" | "primary" | "secondary" | "success" | "warning" | "destructive" | "default" | رنگ پس‌زمینهٔ جایگزین و حلقهٔ bordered. |
| radius | "none" | "sm" | "md" | "lg" | "full" | "full" | شعاع گوشه. |
| bordered | boolean | false | حلقهٔ هم‌رنگ دور آواتار. |
| disabled | boolean | false | کم‌رنگ و غیرقابل‌کلیک می‌کند. |
| focusable | boolean | false | آواتار را در چرخهٔ Tab قرار می‌دهد. |
AvatarImage
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| src | string | — | آدرس تصویر. |
| alt | string | — | متن جایگزین تصویر. |
AvatarFallback
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| delayMs | number | — | تأخیر نمایش جایگزین برای جلوگیری از سوسو زدن. |
AvatarGroup
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| max | number | — | بیشینهٔ آواتارهای نمایش‌داده‌شده؛ نبود آن یعنی همه نمایش داده شوند. |
| total | number | — | عدد شمارندهٔ «+N» را دستی مشخص می‌کند، مستقل از تعداد فرزندان. |
| renderCount | (count: number) => React.ReactNode | — | آواتار «+N» سفارشی به‌جای پیش‌فرض. |
| grid | boolean | false | چیدمان شبکه‌ای به‌جای روی‌هم‌افتادگی. |
| size / color / radius / bordered / disabled | همان مقادیر Avatar | — | مقدار پیش‌فرض برای همهٔ فرزندان؛ هر Avatar با ست‌کردن پراپ خودش می‌تواند این پیش‌فرض را بشکند. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
اندازه‌ها
سه اندازه: sm، پیش‌فرض و lg.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
رنگ‌ها
رنگ محور مستقلی از اندازه و شعاع است و روی پس‌زمینهٔ جایگزین (حروف اول یا آیکون) و حلقهٔ bordered می‌نشیند. پیش‌فرض یعنی همان خاکستری خنثای دیگ.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
شعاع گوشه
پیش‌فرض دایره (full) است؛ برای آواتار مربعی یا نیمه‌گرد از radius استفاده کنید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
تصویر
با src تصویر نمایش داده می‌شود؛ تا زمان بار شدن، یا اگر آدرس نامعتبر باشد، جایگزین (حروف اول یا آیکون) دیده می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
حروف اول فارسی و انگلیسی
برای نام یک‌بخشی دو نویسهٔ اول، برای نام چندبخشی حرف اول دو بخش اول، روی حروف فارسی و انگلیسی یکسان کار می‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
آیکون جایگزین
بدون src و بدون name، سیلوئتِ توپُرِ پیش‌فرض (خنثی/مرد) نمایش داده می‌شود؛ با icon می‌توانید هر آیکون دلخواه دیگری بگذارید — مثلاً سیلوئتِ زن وقتی جنسیت مشخص است، لوگوی دیگ برای حالتِ برند/سیستمی (نه یک شخصِ خاص)، یا هر آیکونِ دیگر.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
قاب‌دار
bordered یک حلقه هم‌رنگ دور آواتار می‌کشد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
غیرفعال
disabled آواتار را کم‌رنگ و غیرقابل‌کلیک می‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
قابل‌فوکوس
با focusable آواتار در چرخهٔ Tab قرار می‌گیرد و حلقهٔ فوکوس نشان می‌دهد؛ برای وقتی خودِ آواتار عمل مستقلی دارد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
گروه آواتار
AvatarGroup چند آواتار را روی‌هم‌افتاده کنار هم می‌چیند و اندازه/رنگ/شعاع/قاب‌دار/غیرفعال را به همهٔ فرزندان می‌دهد مگر روی خودِ آواتار صریح تغییر کرده باشد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
بیشینه و شمارندهٔ باقیمانده
max تعداد نمایش‌داده‌شده را محدود می‌کند و بقیه به‌صورت «+N» جمع می‌شوند؛ total اگر بدهید، همان عدد به‌جای شمارش خودکار نشان داده می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
چیدمان شبکه‌ای گروه
grid روی‌هم‌افتادگی را برمی‌دارد و آواتارها را در شبکهٔ چهارستونه می‌چیند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
رنگ و قاب گروه
رنگ، bordered و disabled روی خودِ AvatarGroup برای همهٔ فرزندان اعمال می‌شود؛ هر آواتار می‌تواند با ست‌کردن پراپ خودش این پیش‌فرض را بشکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نبود تصویر (Fallback)
همیشه name بدهید، حتی وقتی src دارید. اگر تصویر خراب باشد، حروف اول نام جایش می‌نشیند؛ بدون name، آواتار خالی می‌ماند و کاربر نمی‌فهمد این کیست.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نام‌های بلند و تک‌واژه‌ای (Overflow)
حروف اول از دو واژهٔ اول ساخته می‌شود. نام تک‌واژه‌ای یک حرف می‌گیرد و نام‌های بلند هم دو حرف؛ اندازهٔ آواتار ثابت می‌ماند و چیدمان فهرست نمی‌شکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال دریافت (Loading)
آواتار خالی نگذارید. جای خالیِ گِرد و هم‌اندازه بگذارید تا موقع رسیدن داده، سطر جابه‌جا نشود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| اندازه‌ها | سه اندازه: sm، پیش‌فرض و lg. |
| رنگ‌ها | رنگ محور مستقلی از اندازه و شعاع است و روی پس‌زمینهٔ جایگزین (حروف اول یا آیکون) و حلقهٔ bordered می‌نشیند |
| شعاع گوشه | پیش‌فرض دایره (full) است؛ برای آواتار مربعی یا نیمه‌گرد از radius استفاده کنید. |
| تصویر | با src تصویر نمایش داده می‌شود؛ تا زمان بار شدن، یا اگر آدرس نامعتبر باشد، جایگزین (حروف اول یا آیکون) دیده می‌شود. |
| حروف اول فارسی و انگلیسی | برای نام یک‌بخشی دو نویسهٔ اول، برای نام چندبخشی حرف اول دو بخش اول، روی حروف فارسی و انگلیسی یکسان کار می‌کند. |
| آیکون جایگزین | بدون src و بدون name، سیلوئتِ توپُرِ پیش‌فرض (خنثی/مرد) نمایش داده می‌شود؛ با icon می‌توانید هر آیکون دلخواه دیگری بگذارید — مثلاً سیلوئتِ زن وقتی جنسیت مشخص است، لوگوی دیگ برای حالتِ برند/سیستمی (نه یک شخصِ خاص)، یا هر آیکونِ دیگر. |
| قاب‌دار | bordered یک حلقه هم‌رنگ دور آواتار می‌کشد. |
| غیرفعال | disabled آواتار را کم‌رنگ و غیرقابل‌کلیک می‌کند. |
| قابل‌فوکوس | با focusable آواتار در چرخهٔ Tab قرار می‌گیرد و حلقهٔ فوکوس نشان می‌دهد؛ برای وقتی خودِ آواتار عمل مستقلی دارد. |
| گروه آواتار | AvatarGroup چند آواتار را روی‌هم‌افتاده کنار هم می‌چیند و اندازه/رنگ/شعاع/قاب‌دار/غیرفعال را به همهٔ فرزندان می‌دهد مگر روی خودِ آواتار صریح تغییر کرده باشد. |
| بیشینه و شمارندهٔ باقیمانده | max تعداد نمایش‌داده‌شده را محدود می‌کند و بقیه به‌صورت «+N» جمع می‌شوند؛ total اگر بدهید، همان عدد به‌جای شمارش خودکار نشان داده می‌شود. |
| چیدمان شبکه‌ای گروه | grid روی‌هم‌افتادگی را برمی‌دارد و آواتارها را در شبکهٔ چهارستونه می‌چیند. |
| رنگ و قاب گروه | رنگ، bordered و disabled روی خودِ AvatarGroup برای همهٔ فرزندان اعمال می‌شود؛ هر آواتار می‌تواند با ست‌کردن پراپ خودش این پیش‌فرض را بشکند. |
| نبود تصویر (Fallback) | کاربری که عکس نگذاشته یا تصویرش بارگذاری نشده |
| نام‌های بلند و تک‌واژه‌ای (Overflow) | نام‌های فارسی که تعداد واژه‌هایشان فرق می‌کند |
| در حال دریافت (Loading) | کارت کاربر که اطلاعاتش با تاخیر می‌آید |
دستورالعمل استفاده
اندازهٔ یکسان در گروه آواتارها
انجام بده
همهٔ آواتارهای یک گروه باید هم‌اندازه باشند تا کنار هم یک ردیف مرتب و هم‌تراز بسازند؛ AvatarGroup این را خودکار تضمین می‌کند.
انجام نده
تغییر اندازهٔ یک آواتار وسط گروه، هم‌ترازی ردیف را به‌هم می‌زند و بصری نامنظم می‌سازد.
alt توصیفی برای تصویر
انجام بده
alt باید بگوید تصویر مال کیست؛ برای صفحه‌خوان همین یک کلمه فرق زیادی می‌کند.
انجام نده
alt خالی یا کلی مثل «عکس» هیچ اطلاعاتی به کاربر صفحه‌خوان نمی‌دهد.
حروف اول کوتاه و خوانا
انجام بده
name را با نام واقعی بدهید تا حروف اول خودکار و خوانا ساخته شود؛ یک یا دو حرف داخل دایرهٔ آواتار جا می‌شود.
انجام نده
نوشتن متن بلند داخل جایگزین دستی از فضای دایره‌ای بیرون می‌زند یا ریز و غیرقابل‌خواندن می‌شود.