Prezentare generală
Avatar afișează o imagine cu o variantă de rezervă bazată pe prima literă. Utilizați-l lângă numele unei înregistrări sau într-un Chip. Rădăcina sa implicită este un span de prezentare.
Utilizare
-. colorSeed alege culori stabile pentru varianta de rezervă și are ca valoare implicită name; utilizați un identificator de înregistrare pentru a păstra culoarea stabilă când numele se schimbă.
Imaginea și alternativa implicită sunt decorative. name furnizează inițiala vizuală și culorile alternative fără a adăuga o etichetă accesibilă. Când avatarul este singura reprezentare a unei persoane sau înregistrări, setați imageProps={{ alt: name }} pentru a eticheta atât imaginea, cât și alternativa implicită. Păstrați avatarul decorativ când un nume vizibil sau un proprietar etichetat oferă deja acele informații.
imageProps acceptă contractul complet pentru imagine, inclusiv srcSet, sizes, crossOrigin, referrerPolicy, evenimente native, referințe și render. Valoarea sa src suprascrie forma prescurtată src. fallbackProps acceptă contractul complet pentru alternativă, inclusiv delay, elemente copil, etichetare, referințe și render. Un render alternativ personalizat gestionează semantica sa de accesibilitate; setați explicit aria-hidden când este decorativ.
Compuneți părțile
UtilizațiAvatar.Root, Avatar.Image și Avatar.Fallback când controlați structura. Root furnizează dimensiunea, forma și aspectul alternativei; nu generează elemente copil sau etichete accesibile.
img după o încărcare reușită, iar Fallback redă un span cât timp imaginea lipsește, se încarcă sau nu s-a încărcat. delay amână afișarea inițială a alternativei în milisecunde și are implicit valoarea 0. O sursă modificată este încărcată din nou și poate înlocui imaginea curentă sau alternativa.
Avatar.Image expune onLoadingStatusChange cu valorile de stare idle, loading, loaded și error. Callbackul rulează când Base UI raportează o schimbare de stare diferită de inactivă; demontarea părții Image resetează starea rădăcinii partajate la idle. Root, Image și Fallback acceptă funcții className, style și render care țin cont de stare, cu imageLoadingStatus; Image expune și transitionStatus.
Utilizați keepMounted pe Image când imaginea redată trebuie să se încarce pe loc, inclusiv cu loading="lazy" sau cu o componentă de imagine optimizată. Transmiteți atributele native, evenimentele și referința din redatoarele de imagini personalizate. O imagine montată poate fi încă în curs de încărcare sau poate să nu se fi încărcat; verificați starea de încărcare în loc să considerați prezența ei drept succes.
Redatorul componentei front acceptă în prezent calea implicită de preîncărcare cu src. Imaginea sa gazdă nu primește srcSet, sizes, loading, decoding sau referrerPolicy. O funcție render personalizată care se modifică, împreună cu keepMounted, poate lăsa ascunsă o imagine decodificată, deoarece lucrătorul nu poate citi starea de finalizare sau dimensiunile acesteia. Utilizați acolo preîncărcarea implicită până când aceste capacități ale redatorului devin disponibile.
Tipurile publice AvatarRootProps, AvatarImageProps, AvatarFallbackProps, AvatarRootState, AvatarImageState, AvatarFallbackState și AvatarImageLoadingStatus sunt exportate din twenty-ui/primitives/data-display. Referințele vizează elementul DOM redat: implicit span, img și span sau elementul furnizat prin render.
Formă și aspect
shape acceptă square, rounded-square sau circle. Dimensiunile sunt xs (12px), sm (14px), md (16px), lg (24px), xl (32px) și xxl (40px). Atât xl, cât și xxl folosesc text de rezervă de 16px.
Fosta dimensiune xl de 40px este acum xxl. Actualizați utilizările existente ale size="xl" la size="xxl" atunci când trebuie să rămână de 40px.
variant="outline" adaugă o bordură variantei de rezervă. Suprascrierile color, backgroundColor și borderColor personalizează varianta de rezervă, în timp ce o imagine încărcată își păstrează aspectul original.
icon are prioritate atât față de imagine, cât și față de varianta de rezervă bazată pe prima literă. Pictograma în sine este decorativă, așadar etichetați rădăcina când transmite informații. pulsing animează opacitatea și respectă preferințele privind mișcarea redusă.
Deschideți un profil
onClick și disabled pe butonul redat; Avatar prescurtat nu are proprietatea onClick, disabled sau nativeButton.
Pentru navigare, compuneți o ancoră cu un href sau un link de rutare care păstrează semantica ancorei. Linkurile native se activează cu Enter. Păstrați comportamentul de navigare și cel dezactivat în linkul sau componenta interactivă pe care o compuneți.
Migrați avatarele pe care se poate face clic
Compuneți un buton nativ prinrender pentru acțiuni sau o ancoră ori un link de rutare pentru navigare. Mutați onClick și disabled pe acel element principal și eliminați nativeButton. Oferiți elementului principal un nume accesibil util și evitați imbricarea elementelor interactive. Avatar.Root și celelalte părți explicite păstrează contractul complet de evenimente Base UI.
Avatarele prescurtate sunt decorative în mod implicit. name nu denumește imaginea, alternativa sau elementul principal interactiv. Utilizați un imageProps.alt nevid doar când avatarul transmite o identitate care nu este deja furnizată de text vizibil sau de o etichetă a elementului principal. Cu părți explicite, furnizați dvs. textul alternativ al imaginii și etichetele alternative sau atributele decorative și păstrați conținutul tradus în aplicația dvs.
Proprietăți
Tipurile și valorile implicite sunt generate din tipurile publice ale componentei. Părțile explicite acceptă atribute native și gestionari de evenimente. Avatar prescurtat omiteonClick; furnizați-l pe elementul principal transmis prin 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
implicit:"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
implicit:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
implicit:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
implicit:"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"
implicit:"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
implicit:"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
implicit:"false"
Surrounds the avatar with a background-colored ring so overlapping avatars stay distinct.
"circle" | "rounded-square" | "square"
implicit:"square"
Shape of the avatar and its fallback.
"lg" | "md" | "sm" | "xl" | "xs" | "xxl"
implicit:"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"
implicit:"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
implicit:"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
implicit:"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.