Salt la conținutul principal

Prezentare generală

ListItem oferă aspectul vizual partajat de rândurile din liste și meniuri. În mod implicit, redă un div pentru conținut pasiv. Utilizați ListItemButton pentru rândurile de acțiuni obișnuite. Compuneți ListItem cu o ancoră pentru navigare sau cu un proprietar semantic personalizat atunci când este necesar. Folosește Dropdown sau Select atunci când ai nevoie de un popup complet sau de un container de selecție.

Utilizare

Anatomie

ListItem expune sloturi de conținut prin proprietăți. Aceste sloturi aranjează conținutul într-un singur rând; nu sunt componente exportate separat.
Rândul furnizează aspectul. render acceptă un element sau un callback care primește proprietăți native și stare vizuală. Distribuiți aceste proprietăți pe rădăcina efectivă atunci când utilizați un callback. Atributele native, gestionarii de evenimente, className, style și ref ajung la acea rădăcină. Pentru un rând cu butoane de acțiune independente, păstrează rândul neinteractiv, astfel încât acele butoane să rămână controale separate.

Rânduri pe mai multe linii

Setați descriptionPlacement="below" pentru a plasa conținutul suplimentar sub etichetă. Titlul își păstrează comportamentul actual de trunchiere, iar conținutul suplimentar se rearanjează pe rânduri în funcție de lățimea disponibilă. Poziționarea implicită inline și poziționarea end își păstrează aspectul actual.
Pentru previzualizări mai scurte, transmiteți o componentă Text cu truncate sau lineClamp drept description. Conținutul personalizat își controlează propria dispunere și propriile etichete accesibile.

Stări vizuale independente

Toată starea vizuală aparține apelantului. active identifică rândul deschis sau curent fără a-l selecta. selected reprezintă selectarea, iar focused reprezintă o evidențiere pentru navigarea cu tastatura fără a muta focalizarea DOM. active aplică fundalul rândului curent. Setați selectionAppearance="accent" pentru o umplere de accent pe rândurile selectate, independent de poziționarea descrierii. Aspectul implicit păstrează stilizarea existentă pentru selectare bazată pe indicator. focused aplică fundalul evidențiat partajat, inclusiv atunci când un apelant îl utilizează pentru evidențierea cu indicatorul. Conturul vizibil la focalizare urmează focalizarea reală de la tastatură pe rădăcină sau pe controalele acesteia. Aceste proprietăți nu adaugă stări accesibile. Furnizați aria-current, aria-selected sau starea checked a unui control proprietarului semantic corespunzător. Focalizarea reală de la tastatură păstrează și conturul nativ vizibil la focalizare.

Controale independente

Păstrați rădăcina implicită div atunci când un rând conține o casetă de selectare reală sau butoane de acțiune independente. Utilizați startIcon pentru caseta de selectare și actions pentru butoane. indicator decorativ este inutil atunci când o casetă de selectare reală afișează deja selectarea.
Selectarea și deschiderea sunt interacțiuni separate. Aplicația controlează propagarea evenimentelor și orice politică privind activarea rândurilor sau tastatura. ListItem.disabled modifică doar aspectul; transmiteți disabled fiecărui control real pentru a preveni activarea acestuia. Comportamentul existent privind vizibilitatea acțiunilor se aplică rândurilor pe mai multe linii: actionsVisibility="hover" afișează acțiunile la trecerea cursorului sau la focalizarea în rând și le menține vizibile pe dispozitivele tactile. Setați-o la always pentru acțiuni persistente, inclusiv atunci când este deschis un pop-up controlat de apelant. La lățimi de rând de 480px sau mai puțin, acțiunile pe mai multe linii se mută pe propria linie și se încadrează după cum este necesar.

Rând de acțiune

Utilizați ListItemButton pentru a asocia stilizarea rândului cu interacțiunea nativă a unui buton. Transmiteți disabled o singură dată pentru a controla atât aspectul, cât și activarea.
Un proprietar de buton personalizat poate în continuare compune ListItem prin render. Acel proprietar furnizează focalizare nativă, activare cu Enter și Spațiu, precum și comportament dezactivat. ListItem.disabled furnizează doar stilul vizual corespunzător. shortcut afișează indicii; aplicația dvs. înregistrează comenzile rapide. Transmiteți o ancoră prin render atunci când întregul rând navighează. Puneți atributele ancorei, inclusiv href, target și rel, pe acel element.
Etichetele de tip șir rămân text, inclusiv șirurile cu aspect de URL. ListItem nu creează linkuri. Pentru a crea un link pentru o parte dintr-un rând neinteractiv, furnizați o ancoră drept conținut deținut de apelant. Păstrați acel rând ca div pentru a evita linkurile sau butoanele imbricate. Etichetele de tip șir își păstrează trunchierea și indicația pentru depășire; conținutul personalizat poate utiliza OverflowingTextWithTooltip cu o ancoră redată explicit. Linkurile nu au un atribut nativ disabled. Dacă o destinație nu este disponibilă, proprietarul linkului trebuie să furnizeze semantica, ordinea de tabulare și politica de navigare adecvate. Stilizarea sa doar cu ListItem.disabled nu împiedică navigarea.

Proprietar al elementului pop-up

Folosește Dropdown.ActionItem sau Dropdown.OptionItem în containerul popupului acestora. Aceste părți compun deja aspectul ListItem și îi expun sloturile vizuale. Proprietarul pop-up furnizează roluri, focalizare, navigare cu tastatura, activare și comportament dezactivat.

Politica evenimentelor native

ListItem redirecționează obiecte și gestionari de evenimente native. Clicurile se propagă în mod normal, inclusiv clicurile pe controalele de acțiune de la final. Plasați orice limită intenționată pe proprietarul interactiv sau pe gestionarul apelantului.
Apelantul deține, de asemenea, orice politică preventDefault(), cum ar fi prevenirea navigării unui link. Transmiterea lui onClick nu adaugă un rol, nu face un div utilizabil cu tastatura și nu modifică propagarea.

Glisare gestionată de aplicație și navigare în editor

Compuneți rânduri reordonabile cu ListItem în interiorul gazdei de glisare a aplicației. Puneți atributele și listenerii de glisare ai gazdei pe mânerul acesteia și transmiteți mânerul sau priza prin startIcon. Păstrați controale independente de vizibilitate, editare și ștergere în actions. Gazda de glisare gestionează reordonarea cu indicatorul și tastatura, glisarea dezactivată și etichetele accesibile ale mânerului. Pentru sugestiile editorului, păstrați lista existentă a editorului și proprietarul opțiunii active. Redați fiecare ListItem cu role="option" și aria-selected și utilizați focused pentru aspectul rândului activ. Editorul gestionează navigarea cu săgețile și activarea cu Enter, în timp ce focalizarea rămâne în suprafața de editare. Preveniți modificările focalizării la apăsarea indicatorului atunci când editorul le necesită și gestionați selectarea cu indicatorul în handlerul de rând al aplicației. Pentru sugestiile dintr-o pagină Dropdown, utilizați Dropdown.OptionItem sau Dropdown.ActionItem, astfel încât pagina respectivă să gestioneze navigarea și activarea. Nu adăugați un al doilea handler pentru Enter sau Space la un proprietar care se activează deja de la tastatură.

Rând de setări

Utilizează SettingsRow pentru un rând de comutator etichetat. Compune ListItem și Switch, gestionează asocierea accesibilă dintre ele și utilizează starea dezactivată a comutatorului pentru aspectul rândului.

Indicator de selecție

active, selected, focused și disabled controlează independent stilizarea rândului. Acestea nu înregistrează acțiuni, nu mută focalizarea DOM, nu adaugă roluri sau stări accesibile și nu suprimă evenimente. Indicatorii check și checkbox sunt decorativi; utilizați un Checkbox real pentru un control de formular. Setați aria-pressed, aria-selected sau alte semantici de stare pe proprietarul care are nevoie de ele.

Rânduri de selectare.

Selecția aparține părintelui. ListItem nu are o stare de selecție necontrolată: transmiteți selected și actualizați-o din onClick. Folosiți indicator="check" pentru o singură opțiune și indicator="checkbox" pentru opțiuni multiple. Ambii indicatori sunt decorativi; proprietarul interactiv gestionează activarea. Într-o casetă listă existentă, transmiteți role="option" și aria-selected și păstrați gestionarea focalizării și a tastelor săgeată în caseta listă. Pentru un widget de selecție complet, utilizați Select. Butoanele de selecție independente pot utiliza aria-pressed, ca în aceste exemple.

Selecție unică

Plasați un Avatar în startIcon pentru a identifica o înregistrare. Utilizați description pentru text de suport și descriptionPlacement="end" pentru o valoare la final.

Selecție multiplă

Compuneți Tag ca conținut al rândului pentru valori etichetate sau puneți ColorSample în startIcon pentru o alegere de culoare. Un rând poate conține și text simplu sau un avatar.
Indicatorul casetei de bifare nu este un control de formular și nu trimite o valoare. Utilizați Checkbox când aveți nevoie de participare la formular. Setați disabled nativ pe butonul redat pentru a preveni activarea și a-l elimina din ordinea de tabulare. Transmiteți, de asemenea, ListItem.disabled pentru aspectul său vizual.

Sloturi

Utilizați startIcon și endIcon pentru pictograme sau conținut controlat de apelant, description pentru text de susținere, actions pentru conținut la final și hasSubmenu pentru un indicator de submeniu. descriptionPlacement acceptă inline, end sau below. color="danger" stilizează o acțiune distructivă. Evitați imbricarea controalelor interactive într-un rând redat ca buton.

Etichete

Utilizați shortcutJoinLabel pentru a personaliza textul dintre pașii succesivi ai comenzilor rapide. Valoarea implicită este then; un șir gol elimină textul de îmbinare. Aceeași proprietate este disponibilă în părțile elementului Dropdown.

Proprietăți

Referința este generată din tipurile publice ale componentei. Sunt acceptate atribute și gestionari div nativi, inclusiv nume accesibile și evenimente native. Puneți atributele specifice butonului sau ancorei pe elementul furnizat prin render. Atât ref, cât și referința elementului redat vizează rădăcina DOM efectivă.
ReactNode
Trailing content, such as buttons, rendered after the content.
"auto" | "end"
implicit:"auto"
Keeps actions beside the content at every width when set to end. The default auto preserves responsive wrapping. Hidden end actions do not reserve width on devices without touch.
"always" | "hover"
implicit:"hover"
When trailing actions are visible: on hover and focus, or always.
boolean
implicit:"false"
Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item.
"danger" | "neutral"
implicit:"neutral"
Color of the text and icons. danger marks a destructive action.
ReactNode
Supporting text, placed according to descriptionPlacement.
"below" | "end" | "inline"
implicit:"inline"
Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
boolean
implicit:"false"
Applies disabled styling only. Set native disabled behavior and accessible semantics on the button, link, or popup item owner.
ReactNode
Icon rendered after the content.
boolean
implicit:"false"
Applies highlighted styling without moving DOM focus or handling keyboard navigation.
boolean
implicit:"false"
Shows a chevron indicating that the item opens a submenu.
"check" | "checkbox" | "none"
implicit:"none"
Selection indicator: a check icon after the content or a checkbox before it.
Ref<HTMLElement>
Ref to the actual DOM root, including a composed native button or link.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ListItemState>
Composes the row with an element or render callback. The owner supplies interaction semantics, native attributes, and behavior.
boolean
implicit:"false"
Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner.
"accent" | "default"
implicit:"default"
Selection styling independent of description placement. default preserves indicator-based styling; accent fills selected rows with the accent background.
ShortcutDefinition
Keyboard shortcut keys displayed at the end of the row. Registering the shortcut is up to the application.
string
Text between sequential shortcut steps. Defaults to then; pass an empty string to omit it.
ReactNode
Icon rendered before the content.
Transmiteți shortcut={['Mod', 'Enter']} pentru taste simultane sau shortcut={[['G'], ['P']]} pentru apăsări succesive. Consultați Shortcut pentru combinații imbricate și formatorul de șiruri partajat.