Panoramica
OverflowingList misura la larghezza disponibile, mantiene gli elementi che rientrano in una riga compatta e offre un pulsante +N che apre l’elenco completo in un popup. Il conteggio si aggiorna quando cambiano il contenitore, il contenuto degli elementi o l’elenco ordinato. Gli elenchi vuoti e gli elenchi che rientrano non hanno un pulsante di overflow né un popup esposto.
Fornisci l’elenco ordinato completo come elementi con chiave. La tua applicazione gestisce il contenuto, le azioni e i dati di ciascun elemento. La riga compatta rimane visibile quando si apre il popup. Il popup ripete l’elenco completo, inclusi gli elementi che rientrano nella riga.
Utilizzo
Visibilità del conteggio
La modalità predefinita mantiene la visibilità corrente del conteggio mentre un elemento inline ha il focus, in modo che la visualizzazione del conteggio non spinga quell’elemento fuori dalla riga. Portare il focus sul pulsante del conteggio rende visibile il conteggio.
Usa
false quando l’interfaccia circostante offre un altro modo per accedere agli elementi nascosti. Modificandolo in false, il conteggio viene nascosto senza chiudere un popup già aperto. open e defaultOpen possono comunque mostrare l’elenco completo quando gli elementi eccedono lo spazio disponibile. La rimozione degli elementi in eccesso o l’allargamento dell’elenco finché tutto non rientra chiude il popup e rimuove il pulsante del conteggio. Il conteggio descrive sempre gli elementi esterni alla riga compatta.
maxInlineCount limita il numero di elementi visibili nella riga. La larghezza disponibile può ridurre ulteriormente quel numero. Il popup contiene comunque l’elenco completo. Non recupera elementi mancanti né virtualizza il popup.
Stato del popup
L’elenco gestisce lo stato del proprio popup quandoopen è omesso. Usa defaultOpen per il suo stato iniziale. Il valore predefinito è false; un popup inizialmente aperto richiede comunque elementi in eccesso.
Passa open e aggiornalo in onOpenChange per gestire lo stato del popup. Il callback riceve il valore booleano richiesto e i dettagli dell’evento Popover installato, inclusi reason, event, trigger, cancel() e preventUnmountOnClose(). La chiamata a cancel() impedisce la modifica dello stato richiesta. Nell’uso controllato, aggiorna il tuo stato solo per le modifiche che accetti.
Passa actionsRef per ricevere i metodi close() e unmount() di Popover. close() richiede la chiusura tramite onOpenChange e rispetta l’annullamento. Se il callback chiama preventUnmountOnClose() per eseguire un’uscita gestita dal chiamante, chiama actionsRef.current?.unmount() al termine di tale uscita. Questo rilascia il popup mantenuto senza rimuovere l’elenco e ne consente una nuova apertura.
Destinazioni native e composizione
Gli attributidiv nativi, i gestori, gli stili, i nomi di classe e i ref su OverflowingList hanno come destinazione la radice della riga compatta. Usa triggerProps per il pulsante del conteggio e popupProps per il div del contenuto del popup. Entrambi mantengono le proprietà native, i gestori, il ref e la composizione render di elemento/funzione della rispettiva parte di Popover.
Personalizza il trigger con triggerProps.render, come nell’esempio controllato, oppure fornisci triggerProps.children per sostituire +N. I componenti personalizzati devono inoltrare le proprietà e il ref forniti. Anche i componenti popup personalizzati devono eseguire il rendering degli elementi figlio forniti; OverflowingList gestisce il contenuto degli elementi. overflowLabel usa per impostazione predefinita “Mostra tutti gli elementi”. Il nome accessibile del pulsante predefinito combina il relativo conteggio e quell’etichetta, ad esempio “+3 Mostra tutti i team”. Sovrascrivi triggerProps['aria-label'] o popupProps['aria-label'] quando il relativo contenuto richiede un nome diverso.
Per impostazione predefinita, OverflowingList interrompe la propagazione di click, mousedown, pointerdown, keydown e keyup sul trigger e sul popup. Ciò impedisce che l’apertura del popup e l’interazione con i relativi elementi attivino un campo o un selettore circostante. Un gestore fornito tramite triggerProps o popupProps sostituisce il valore predefinito per quell’evento. Chiama event.stopPropagation() nel tuo gestore per mantenere il blocco, oppure omettilo per consentire la propagazione di quell’evento. Gli altri eventi mantengono i valori predefiniti. I gestori su un elemento render personalizzato si compongono come di consueto con le proprietà fornite.
Quando una sostituzione del clic del popup consente la propagazione, il portale Base UI installato può inviare quel clic due volte a un antenato React circostante con lo stesso evento nativo. Ciò si verifica anche con un semplice Popover. OverflowingList mantiene tale comportamento upstream; non garantisce un callback dell’antenato per ogni evento popup nativo quando la propagazione è abilitata.
Tastiera e focus
Invio, Spazio e l’attivazione tramite puntatore aprono un popup non modale. Esc e l’interazione esterna lo chiudono. La chiusura ordinaria ripristina il focus sul pulsante del conteggio. Il focus già presente su un elemento inline visibile o su un controllo esterno viene mantenuto. Il popup supporta contenuti, collegamenti e pulsanti con il loro comportamento nativo da tastiera; non li trasforma in elementi di menu né aggiunge la navigazione con le frecce del menu. UsapopupProps.initialFocus e popupProps.finalFocus per personalizzare il focus all’apertura e alla chiusura tramite il contratto Popover installato.
Ogni elenco gestisce indipendentemente le proprie misurazioni responsive. Lo smontaggio di un elenco rilascia i relativi osservatori e lascia funzionanti gli altri elenchi.
Rendering del server e idratazione
Il markup del server include i primi elementimaxInlineCount, oppure tutti gli elementi quando il limite è omesso. La misurazione della larghezza e il contenuto del popup diventano disponibili dopo il montaggio del client.
L’idratazione riutilizza la riga provvisoria e applica la misurazione responsive dopo il montaggio del client. Gli elementi figlio della riga e del popup sono istanze di rendering separate. Mantieni lo stato condiviso tra queste posizioni nel chiamante.
Migrazione
Il popup continua a mostrare l’elenco completo e usa per impostazione predefinita “Mostra tutti gli elementi”.showOverflowCount={false} mantiene la riga ritagliata e nasconde il conteggio. Non chiude un popup già aperto. Il trigger e il popup mantengono il blocco predefinito per click, mousedown, pointerdown, keydown e keyup. Sovrascrivi un singolo gestore tramite triggerProps o popupProps quando l’interfaccia circostante deve ricevere quell’evento.
Props
RefObject<PopoverRootActions | null>
Ref exposing the Popover close() and unmount() methods. After preventUnmountOnClose(), call unmount() when the caller-owned exit finishes.
ReactElement<unknown, string | JSXElementConstructor<any>>[]
obbligatorio
Complete ordered list of elements, each with a stable key. The popup contains the complete list, including items visible in the compact row.
boolean
predefinito:"false"
Initial popup visibility when uncontrolled. Defaults to false.
number
Maximum number of items visible in the compact row. Available width can reduce this count further. The popup still contains the complete list.
((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)
Receives the requested open state and unchanged Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose().
boolean
Controlled popup visibility. A popup can appear only when items overflow.
string
predefinito:"Show all items"
Accessible label for the popup. The default overflow button is named by its visible count followed by this label. Defaults to Show all items.
Omit<PopoverPopupProps, "children">
Popover.Popup native props, handlers, ref, render composition and focus options for the overflow content. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default.
Ref<HTMLDivElement>
Ref forwarded to the compact row root div.
boolean
Shows the count on hover, keyboard focus or while open by default. Use true to keep it visible whenever items overflow, or false to hide the count and clip the row. An already-open popup stays open until dismissed. Empty lists and lists that fit have no trigger.
Omit<
ComponentPropsWithRef<typeof Popover.Trigger>,
'handle' | 'payload' | 'ref'
> & { ref?: Ref<HTMLElement> }
Popover.Trigger native props, handlers, ref, children and render composition for the count button. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default. Custom components must forward supplied props and ref.