صورة رمزية (Avatar)

يعرض مكوّن صورة رمزية (Avatar) صورة الشخص أو الأحرف الأولى من اسمه أو أيقونة، مع إطار ونقطة حالة اختياريين.

التثبيت

bash

npx @smicolon/cli init
npx @smicolon/cli add avatar status-indicator

يستخدم مكوّن صورة رمزية (Avatar) مكوّن status-indicator لنقطة الحالة، لذلك أضف الاثنين.

معاينة

الأنماط (variant)

تحدد الخاصية variant ما يظهر. القيمة الافتراضية image تعرض الصورة، وإذا كانت قيد التحميل أو تعذّر تحميلها تعرض الأحرف الأولى من name، ثم أيقونة المستخدم إن لم يكن هناك اسم. أما initials أو icon فتعرض كلٌّ منهما محتواها حتى مع وجود صورة. وتختار radius مربعًا بزوايا مستديرة أو دائرة، وتضيف border حلقة داخل الحافة.

إذا كانت الصورة غير متوفّرة أو تعذّر تحميلها، تعرض الصورة الرمزية الأحرف الأولى من الاسم، أو الأيقونة إن لم يكن هناك اسم.

standardstandard + borderroundedrounded + border

الأحجام

الحجم 32 للرؤوس والبطاقات والتعليقات، والحجم 24 للجداول والقوائم الكثيفة، والحجم 12 للإشارات داخل السطر، وفيه تصغر الأحرف الأولى إلى حرف واحد بحجم 10px.

نقطة الحالة

تضيف الخاصية status مكوّن مؤشر الحالة (Status Indicator) في زاوية النهاية السفلية. تظهر النقطة فقط حين تحددها، لأنها تُخبر بحضور الشخص، فاعرضها حين تعرف حالته.

إتاحة الوصول (accessibility)

تسمّي name الصورة الرمزية في كل الأنماط (variant): فهي النص البديل alt للصورة، ونص مخفي خلف الأحرف الأولى أو الأيقونة، ولا يقرأ قارئ الشاشة الأحرف الظاهرة.
مرّر name="" إذا كان اسم الشخص مكتوبًا بجانب الصورة الرمزية، حتى لا يُعلن مرتين.
يقرأ قارئ الشاشة النقطة بعد الاسم: «ليلى حداد» ثم «متصل»، أو «Online» حين تكون أقرب قيمة لـ lang هي الإنجليزية. مرّر statusLabel لتقول أكثر.
يتبع المكوّن اتجاه الصفحة من السمة (attribute) dir، وليس من خاصية، فتظهر النقطة دائمًا في الزاوية الصحيحة للصفحة.

الخصائص (props)

الخاصية	النوع	الافتراضي	الوصف
`variant`	`"image" \| "initials" \| "icon"`	`"image"`	ما يظهر: صورة أو أحرف أولى أو أيقونة.
`size`	`"32" \| "24" \| "12"`	`"32"`	حجم الصورة الرمزية بالبكسل.
`radius`	`"standard" \| "rounded"`	`"standard"`	مربع بزوايا مستديرة أو دائرة.
`border`	`boolean`	`false`	يضيف حلقة داخل الحافة.
`src`	`string`	لا يوجد	رابط الصورة.
`name`	`string`	لا يوجد	اسم الشخص: النص البديل والأحرف الأولى.
`status`	`"online" \| "away" \| "busy" \| "offline"`	لا يوجد	يضيف نقطة حالة.
`statusLabel`	`string`	لا يوجد	اسم النقطة لقارئ الشاشة، ويتبع لغة الصفحة افتراضيًا.
`className`	`string`	لا يوجد	أصناف (class) إضافية للمكوّن.

الاستخدام

tsx

import { Avatar } from "@/components/ui/avatar"

// صورة، ثم الأحرف الأولى، ثم أيقونة المستخدم
<Avatar src={user.photo} name={user.name} />

// الأحرف الأولى أو الأيقونة، أيًّا كان ما يُمرَّر
<Avatar variant="initials" name={user.name} />
<Avatar variant="icon" name={user.name} />

// في القوائم الطويلة: أجّل تحميل الصور خارج الشاشة، وقدّم مصدرًا أوضح للشاشات الكثيفة
<Avatar src={user.photo} srcSet={`${user.photo} 1x, ${user.photo2x} 2x`} loading="lazy" name={user.name} />

// دائرة بإطار ونقطة حالة
<Avatar src={user.photo} name={user.name} radius="rounded" border status="online" />

// داخل السطر، بجانب اسم يعرّف صاحبه
<Avatar size="12" src={user.photo} name="" /> {user.name}