Panoramica
Gli elementi primitivi sono i controlli fondamentali in Twenty UI. Includono input, elementi di visualizzazione, navigazione e controlli composti come Select, Popover e AlertDialog. Ogni elemento primitivo riceve dati e callback dalla tua applicazione. Importa gli elementi primitivi da un punto di ingresso della famiglia, ad esempiotwenty-ui/primitives/input. L’entry aggregata twenty-ui/primitives esporta anche ogni famiglia di primitive. Consulta Guida introduttiva per l’installazione e la configurazione del tema.
I componenti combinano queste primitive in preimpostazioni di progettazione condivise e blocchi di base riutilizzabili per le app.
Proprietà dello stato
Usa lo stato non controllato quando un componente può gestire le proprie interazioni. Una prop predefinita fornisce lo stato iniziale. Usa lo stato controllato quando l’applicazione deve coordinare tale stato con altri controlli, la navigazione o i dati dell’applicazione.
In modalità controllata, passa lo stato corrente e aggiornalo nella callback di modifica. In modalità non controllata, puoi comunque rilevare le modifiche senza assumere la proprietà dello stato. L’aggiunta di una sola callback non rende un componente controllato.
Scegli una modalità per ogni stato e mantienila per l’intera durata del componente. Le prop predefinite inizializzano lo stato; modificarle in seguito non sostituisce lo stato corrente. Evita di passare sia la prop predefinita sia quella controllata per lo stesso stato.
Alcuni componenti hanno più di uno stato indipendente. Ad esempio, Select può avere un valore controllato e la visibilità del popup non controllata.
Lo stato appartiene alla parte che gestisce l’interazione. Configura la selezione dei pulsanti di opzione in RadioGroup, non in ogni Radio. I componenti di visualizzazione come Text non hanno una modalità controllata o non controllata. Toast delega la propria visibilità e rimozione all’applicazione.
Composizione
Le primitive composte espongono parti comeSelect.Root, Select.Trigger e Select.Popup. Mantieni le parti correlate sotto la stessa radice nell’albero dei componenti affinché condividano lo stato e le relazioni di accessibilità. La sezione anatomia di ciascun componente identifica le parti obbligatorie e i contenuti facoltativi.
Gli slot come InputGroup.startElement e ListItem.actions accettano nodi React come prop. Aggiungono contenuto all’interno del layout di un componente. Parti e slot sono API diverse; usa i nomi elencati nella guida del componente.
Composizione dei popup
Select, Popover e Autocomplete espongono partiPortal, Positioner e Popup separate:
Annida Popup all’interno di Positioner e Positioner all’interno di Portal. Inserisci il contenuto all’interno di Popup e aggiungi Arrow esplicitamente quando necessario. Il portale può spostare il DOM sottoposto a rendering in un altro contenitore mantenendo la gerarchia e il contesto del componente. Consulta la tematizzazione per i contenitori del portale con ambito definito.
Ogni parte sottoposta a rendering mantiene i propri attributi nativi, la destinazione ref e la composizione di rendering. Autocomplete mantiene anche le parti upstream installate per raccolta, raggruppamento, griglia, filtro e stato.
Dialog e AlertDialog espongono parti
Portal, Backdrop, Viewport e Popup separate. Configura il montaggio e la destinazione in Portal, l’aspetto della sovrapposizione in Backdrop e Viewport e le dimensioni e lo stato attivo del contenuto in Popup. Ogni parte conserva i propri attributi nativi, la destinazione ref e la composizione del rendering. Queste API per le finestre di dialogo sono destinate all’interfaccia utente autonoma e all’host Twenty. I componenti Front usano l’API del dialogo host SDK.
Componenti personalizzati
Per le parti che supportanorender, passa un elemento o componente compatibile per sostituire l’elemento predefinito. Ad esempio, Popover.Trigger può usare un Button di Twenty mantenendo il proprio comportamento di trigger.
Un wrapper personalizzato deve passare le props e il ref forniti all’elemento interattivo. Ciò preserva i gestori di eventi, gli attributi di accessibilità, il posizionamento e il ripristino del focus. Questo esempio li inoltra tramite Button, che li associa al proprio pulsante nativo.
render e mantieni ogni azione come un singolo controllo interattivo. Quando aggiungi il tuo comportamento, conserva i gestori e il ref forniti al tuo wrapper. Il ref deve raggiungere l’elemento che riceve il focus.
Usa un pulsante nativo per le parti simili a pulsanti. Nelle parti che espongono nativeButton, imposta nativeButton={false} solo quando l’elemento renderizzato non è un pulsante nativo. Un componente personalizzato che alla fine renderizza un pulsante, come HelpButton, mantiene il comportamento predefinito del pulsante.