الانتقال إلى المحتوى الرئيسي

نظرة عامة

يعرض Avatar صورة مع بديل للحرف الأول. استخدمه بجانب اسم سجل أو داخل شريحة. العنصر الجذر الافتراضي له هو span للعرض.

استخدام

عند غياب الصورة أو تعذر تحميلها، يعرض البديل الحرف الأول من الاسم بعد إزالة المسافات منه، بأحرف كبيرة. يعرض الاسم الفارغ -. يختار colorSeed ألوانًا ثابتة للبديل ويكون افتراضيًا name؛ استخدم معرّف سجل للحفاظ على ثبات اللون عند تغيير الاسم. الصورة والبديل الافتراضي للعودة عنصران زخرفيان. يوفر name الحرف الأول المرئي وألوان البديل للعودة من دون إضافة تسمية يمكن الوصول إليها. عندما تكون الصورة الرمزية هي التمثيل الوحيد لشخص أو سجل، اضبط imageProps={{ alt: name }} لتسمية كل من الصورة والبديل الافتراضي للعودة. أبقِ الصورة الرمزية زخرفية عندما يوفّر اسم مرئي أو مالك مُسمّى هذه المعلومات بالفعل. يقبل imageProps عقد الصورة الكامل، بما في ذلك srcSet وsizes وcrossOrigin وreferrerPolicy والأحداث الأصلية والمراجع وrender. تتجاوز خاصية src الخاصة به الاختصار src. يقبل fallbackProps عقد البديل للعودة الكامل، بما في ذلك delay والعناصر التابعة والتسمية والمراجع وrender. يتولى render المخصص للبديل للعودة دلالات إمكانية الوصول الخاصة به؛ اضبط aria-hidden صراحةً عندما يكون زخرفيًا.

ركّب الأجزاء

استخدم Avatar.Root وAvatar.Image وAvatar.Fallback عندما تكون مسؤولًا عن البنية. يوفر Root الحجم والشكل ومظهر البديل للعودة؛ ولا ينشئ عناصر تابعة أو تسميات يمكن الوصول إليها.
تتشارك الأجزاء حالة تحميل الصورة في Base UI. يعرض Image عنصر img بعد تحميل ناجح افتراضيًا، ويعرض Fallback عنصر span بينما تكون الصورة غائبة أو قيد التحميل أو فشل تحميلها. تؤخر delay العرض الأولي للبديل للعودة بالمللي ثانية، وتكون قيمتها الافتراضية 0. يُحمّل مصدر متغيّر مرة أخرى ويمكنه استبدال الصورة الحالية أو البديل للعودة. يكشف Avatar.Image عن onLoadingStatusChange مع قيم الحالة idle وloading وloaded وerror. يُشغَّل رد الاتصال عندما تُبلغ Base UI عن تغيّر حالة غير idle؛ وتؤدي إزالة تركيب جزء Image إلى إعادة تعيين حالة الجذر المشتركة إلى idle. تقبل Root وImage وFallback دوال className وstyle وrender المدركة للحالة مع imageLoadingStatus؛ ويكشف Image أيضًا عن transitionStatus. استخدم keepMounted على Image عندما يجب تحميل الصورة المعروضة في موضعها، بما في ذلك loading="lazy" أو مكوّن صورة محسّن. مرّر السمات والأحداث الأصلية والمرجع من مُصيّرات الصور المخصصة. قد تظل الصورة المركبة قيد التحميل أو يكون تحميلها قد فشل؛ افحص حالة التحميل بدلًا من اعتبار وجودها نجاحًا. يدعم مُصيّر المكوّن الأمامي حاليًا مسار التحميل المسبق الافتراضي باستخدام src. لا تتلقى صورة المضيف الخاصة به srcSet أو sizes أو loading أو decoding أو referrerPolicy. قد تؤدي دالة render مخصصة متغيرة مع keepMounted إلى إبقاء صورة مفككة مخفية لأن العامل لا يمكنه قراءة حالة اكتمالها أو أبعادها. استخدم التحميل المسبق الافتراضي هناك إلى أن تتوفر إمكانات المُصيّر هذه. تُصدَّر الأنواع العامة AvatarRootProps وAvatarImageProps وAvatarFallbackProps وAvatarRootState وAvatarImageState وAvatarFallbackState وAvatarImageLoadingStatus من twenty-ui/primitives/data-display. تستهدف المراجع عنصر DOM المعروض: span وimg وspan افتراضيًا، أو العنصر المقدم عبر render.

الشكل والمظهر

يقبل shape القيم square أو rounded-square أو circle. الأحجام هي xs ‏(12px)، وsm ‏(14px)، وmd ‏(16px)، وlg ‏(24px)، وxl ‏(32px)، وxxl ‏(40px). يستخدم كل من xl وxxl نصًا احتياطيًا بحجم 16px. أصبح الحجم السابق xl البالغ 40px هو الآن xxl. حدّث استخدامات size="xl" الحالية إلى size="xxl" عندما ينبغي أن تظل بحجم 40px. تضيف variant="outline" حدًا إلى البديل. تخصص تجاوزات color وbackgroundColor وborderColor البديل، بينما تحافظ الصورة المحمّلة على مظهرها الأصلي.
تكون للأيقونة icon الأولوية على كل من الصورة والبديل ذي الحرف الأول. الأيقونة نفسها زخرفية، لذا سمِّ الجذر عندما تنقل معلومات. تُحرّك pulsing الشفافية وتحترم تفضيلات تقليل الحركة.

فتح ملف شخصي

ركّب زرًا أصليًا للإجراءات. يتولى التركيز والتنشيط بمفتاحي Enter وSpace وسلوك التعطيل. وفّر اسمًا يمكن الوصول إليه ومحددًا للإجراء. ضع onClick وdisabled على الزر المعروض؛ لا تتضمن الصورة الرمزية المختصرة خاصية onClick أو disabled أو nativeButton. للتنقل، ركّب رابط ارتساء مع href أو رابط موجه يحافظ على دلالات رابط الارتساء. تُفعّل الروابط الأصلية بمفتاح Enter. أبقِ سلوك التنقل والتعطيل مع الرابط أو المكوّن التفاعلي الذي تركّبه.

رحّل الصور الرمزية القابلة للنقر

ركّب زرًا أصليًا عبر render للإجراءات، أو رابط ارتساء أو رابط موجه للتنقل. انقل onClick وdisabled إلى ذلك المالك وأزل nativeButton. امنح المالك اسمًا مفيدًا يمكن الوصول إليه وتجنب تداخل العناصر التفاعلية. يحتفظ Avatar.Root والأجزاء الصريحة الأخرى بعقد أحداث Base UI الكامل. الصور الرمزية المختصرة زخرفية افتراضيًا. لا يحدد name اسم الصورة أو البديل للعودة أو المالك التفاعلي. استخدم imageProps.alt غير فارغ فقط عندما تنقل الصورة الرمزية هوية لا يوفرها بالفعل نص مرئي أو تسمية مالك. مع الأجزاء الصريحة، وفّر النص البديل للصورة وتسميات البديل للعودة أو السمات الزخرفية بنفسك، وأبقِ المحتوى المترجم في تطبيقك.

الخصائص

تُنشأ الأنواع والقيم الافتراضية من أنواع المكوّنات العامة. تقبل الأجزاء الصريحة السمات الأصلية ومعالجات الأحداث. تحذف الصورة الرمزية المختصرة onClick؛ وفّره على المالك المُمرَّر عبر render.
string
Background color override for a first-letter fallback.
string
Border color override for the outline fallback.
string | ((state: AvatarRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
string
Text color override for a first-letter fallback.
string
Stable value used to choose fallback colors. Defaults to name.
AvatarFallbackProps
Complete Avatar.Fallback props, including caller-owned children, labeling, refs, render, and fallback delay in milliseconds.
ReactNode
Decorative icon rendered instead of the image and first-letter fallback. Give the root an accessible label when the icon conveys information.
AvatarImageProps
Complete Avatar.Image props, including native image attributes, refs, render, keepMounted, and onLoadingStatusChange. Alternative text defaults to an empty string. Supply a nonempty alt to label the image and default fallback.
string
Name used for the first-letter fallback and fallback colors. Does not add an accessible label.
boolean
افتراضي:"false"
Animates the avatar opacity. Respects reduced-motion preferences.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
boolean
افتراضي:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
افتراضي:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
افتراضي:"md"
Avatar size: xs (12px), sm (14px), md (16px), lg (24px), xl (32px), or xxl (40px).
string | null
Image URL. A missing or failed image shows the fallback. imageProps.src overrides this value.
CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
"outline" | "soft"
افتراضي:"soft"
Visual treatment of the fallback.

Avatar.Root

string
Background color override for a first-letter fallback.
string
Border color override for the outline fallback.
ReactNode
Caller-owned Image, Fallback, and other content.
string | ((state: AvatarRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
string
Text color override for a first-letter fallback.
string
Stable value used to choose fallback colors. Defaults to name.
string
Name used to choose fallback colors. Does not add children or accessible labels.
boolean
افتراضي:"false"
Animates the avatar opacity. Respects reduced-motion preferences.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarRootState>
Caller-supplied root element or renderer. Defaults to a presentational span. Compose a native button or link explicitly for interaction, and put its click handler and disabled state on that owner.
boolean
افتراضي:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
افتراضي:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
افتراضي:"md"
Avatar size: xs (12px), sm (14px), md (16px), lg (24px), xl (32px), or xxl (40px).
CSSProperties | ((state: AvatarRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
"outline" | "soft"
افتراضي:"soft"
Visual treatment of the fallback.

Avatar.Image

string
Caller-owned alternative text. Use an empty string for decorative images.
string | ((state: AvatarImageState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"" | "anonymous" | "use-credentials"
Native image cross-origin policy, also used during preloading.
boolean
افتراضي:"false"
Keeps the image mounted and loads it in place. Loading and failed images stay hidden while Fallback is shown.
"eager" | "lazy"
Native eager or lazy loading. Use keepMounted for lazy loading.
((status: ImageLoadingStatus) => void)
Called when Base UI reports a loading, loaded, or error status. Shares that state with Root and Fallback.
"" | "no-referrer-when-downgrade" | "no-referrer" | "origin-when-cross-origin" | "origin" | "same-origin" | "strict-origin-when-cross-origin" | "strict-origin" | "unsafe-url"
Native image referrer policy, also used during preloading.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, AvatarImageState>
Replaces the image. Preserve a native image and forward the supplied attributes, events, and ref.
string
Native responsive image sizes used with srcSet.
string
Image URL. Image renders after a successful load unless keepMounted is enabled.
string
Native responsive image source candidates.
CSSProperties | ((state: AvatarImageState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

Avatar.Fallback

ReactNode
Caller-owned fallback content, such as initials or an icon.
string | ((state: AvatarFallbackState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
number
افتراضي:"0"
Milliseconds before the initial fallback is shown. Defaults to 0.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, AvatarFallbackState>
Replaces the fallback span. Forward the supplied props and ref, and provide its accessible label or decorative attributes.
CSSProperties | ((state: AvatarFallbackState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.