Componenti
Composizione
I componenti UI inclusi sono progettati per essere assemblati, non usati singolarmente. Un menu a discesa si apre all'interno di una finestra di dialogo, un modulo viene convalidato in un pannello laterale e un menu trova posto in una riga di tabella. Questa pagina spiega i meccanismi che rendono possibile tutto ciò: la struttura delle famiglie di componenti composti, il modo in cui i trigger inoltrano le proprietà dei pulsanti, il funzionamento sottostante di API Interactivity e il modello a livelli che mantiene coerenti le superfici sovrapposte.
Famiglie di componenti composti
Un componente composto è un blocco radice con blocchi figli. La radice gestisce lo stato; ogni figlio dichiara il proprio ruolo nella famiglia tramite parent e usesContext nel proprio block.json:
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Le radici espongono un'area InnerBlocks con un elenco allowedBlocks e un template iniziale, così inserendo una finestra di dialogo nell'editor vengono predisposti il trigger, il backdrop e il popup. La famiglia si comporta allo stesso modo sia che venga composta nell'editor, in una pagina basata su file o nei tag:
<bs:bsui-select name="role" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
</bs:bsui-select-popup>
</bs:bsui-select>
Popup e pannelli sono vere aree InnerBlocks, non slot con una sintassi speciale. Un bsui/dialog-popup accetta blocchi annidati proprio come un blocco gruppo: inserire al suo interno un modulo, un menu a discesa o un'altra finestra di dialogo è quindi una normale operazione di composizione.
Dati piatti o figli composti
Alcune famiglie accettano i contenuti come dati anziché come figli. Se gli passate un array options JSON, il menu a discesa genera il proprio trigger e listbox; questa soluzione è adatta alle opzioni provenienti da PHP:
bs_render_block([
'name' => 'bsui/select',
'data' => [
'name' => 'role',
'placeholder' => 'Pick a role',
'options' => wp_json_encode([
['value' => 'viewer', 'label' => 'Viewer'],
['value' => 'editor', 'label' => 'Editor'],
]),
],
]);
Entrambe le forme producono lo stesso contratto di markup e lo stesso comportamento in fase di esecuzione. Usate i figli quando la struttura è definita manualmente e options quando viene calcolata.
Inoltro dei trigger
I componenti overlay si aprono da un pulsante, che dovrebbe essere il pulsante di sistema. Anziché reimplementarne uno per ogni trigger, i blocchi trigger di bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible e bsui/tooltip incorporano bsui/button tramite un campo campo block:
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
Il idStructure espande i campi del pulsante sul trigger usando il prefisso trigger_. Sono disponibili tutte le proprietà del pulsante: trigger_label, trigger_variant, trigger_size, trigger_icon, trigger_iconPosition, trigger_href, trigger_disabled.
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
Nel template del trigger, $a['trigger'] è il pulsante completamente renderizzato, quindi il suo foglio di stile e le modifiche future vengono mantenuti. In fase di esecuzione, un helper condiviso inoltra al pulsante interno gli attributi ARIA del wrapper (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) e li mantiene sincronizzati tramite un MutationObserver, così le tecnologie assistive rilevano un unico controllo coerente.
Il funzionamento sottostante di Interactivity API
Ogni famiglia interattiva è un'istanza WordPress dello store Interactivity API, chiamata come il blocco radice: bsui/dialog, bsui/select, bsui/form, bsui/tabs e così via. Ne derivano tre conseguenze.
Lo stato viene inizializzato lato server. Il template radice stampa lo stato iniziale come data-wp-context, direttamente dagli attributi del blocco:
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Il primo rendering è corretto HTML senza sfarfallio dovuto all'idratazione lato client; i popup si avviano hidden e lo stesso markup funziona nell'area di lavoro dell'editor, perché il contesto non dipende da un passaggio di stato riservato al frontend.
Il comportamento è collegato con direttive, non con il vostro JavaScript. I template collegano il markup agli store in modo dichiarativo. Il trigger del menu a discesa, privato del suo PHP, è composto solo da direttive:
<button
data-wp-interactive="bsui/select"
data-wp-on--click="actions.toggle"
data-wp-on--keydown="actions.handleTriggerKeyDown"
data-wp-bind--aria-expanded="state.ariaExpanded"
data-wp-text="state.displayValue"
data-bsui-select-trigger
aria-haspopup="listbox"
>
data-wp-on indirizza gli eventi alle azioni, data-wp-bind mantiene gli attributi sincronizzati con lo stato derivato, data-wp-text mostra lo stato come testo e data-wp-on-document--click consente alle radici di chiudersi quando si fa clic all'esterno. Per comporre i componenti non serve mai scrivere un gestore di eventi: lo store viene fornito con il blocco come modulo inline.
I vostri store possono integrarsi nei componenti. I controlli dei moduli accettano espressioni di direttive come attributi e la sintassi con namespace di Interactivity API li indirizza a qualsiasi store. onChange inoltra la gestione delle modifiche a una delle vostre azioni, checked associa lo stato del controllo al vostro stato e bindText mostra un'etichetta come elemento span data-wp-text associato a qualsiasi percorso dello stato:
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText è disponibile sugli elementi bsui/label, bsui/checkbox, bsui/switch, bsui/toggle e bsui/radio-group. Nei checkbox, negli switch e negli elementi radio, il testo passa alla primitiva di etichetta condivisa, mantenendo la tipografia esatta dell'etichetta di sistema. Menu a discesa e altri input inviano inoltre un evento change con propagazione dal loro elemento radice, che contiene il nuovo valore in detail, per integrazioni più generiche.
Valori controllati
Lasciate value o checked non impostato per un controllo che gestisce autonomamente il proprio valore. Usate defaultValue, defaultChecked o defaultPressed di Toggle per la selezione iniziale. Un Toggle autonomo gestisce l’input da puntatore e da tastiera senza uno store consumer.
Per controllare un campo dal vostro store, fornite sia il relativo binding sia un’azione onChange che aggiorni il valore associato. value è un percorso direttiva, non un valore predefinito letterale. Input, Textarea, Password Input, Number Field, Slider, Radio Group, Color Picker, Rating e Time Picker supportano value.
Checkbox, Switch e Toggle usano invece checked.
Qualificate i percorsi con lo spazio dei nomi proprietario, per esempio
my/settings::context.quantity o my/settings::state.quantity. I controlli composti hanno un proprio spazio dei nomi; un percorso senza qualificatore si riferisce a quel controllo, non automaticamente allo store genitore. I binding dei valori composti supportano percorsi con punti nel contesto o nello stato, comprese le chiavi numeriche degli array, ma non le espressioni JavaScript o le chiamate di funzione.
Ecco un binding completo di Number Field in un blocco personalizzato con il supporto Interactivity API abilitato:
<div
data-wp-interactive="my/settings"
data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
<bs:bsui-number-field
nameAlt="quantity"
defaultValue="2"
value="my/settings::context.quantity"
onChange="my/settings::actions.setQuantity"
/>
<output data-wp-text="context.quantity"></output>
</div>
import { getContext, store } from '@wordpress/interactivity';
store('my/settings', {
actions: {
setQuantity(event) {
// Compound controls publish their normalized value in a custom change event.
if (event.detail?.value !== undefined) {
getContext().quantity = event.detail.value;
}
},
},
});
Impostate il valore predefinito corrispondente per il valore iniziale renderizzato dal server. Dopo l’hydration, le modifiche al genitore aggiornano ogni istanza associata, inclusi zero, false e i valori vuoti. Anche gli input nascosti dei form di Checkbox e Switch seguono il binding checked. I valori di Time Picker usano HH:MM nel formato a 24 ore oppure una stringa vuota.
Per gli handler nativi di Input, Textarea e Password Input, leggete event.target.value; i controlli composti con valore pubblicano event.detail.value.
I limiti di Number Field sono facoltativi: se min e max sono omessi, il campo non è limitato; lo zero esplicito resta un limite valido.
Select, Date Input, Phone Input e OTP Input pubblicano le modifiche tramite onChange, ma non espongono questo binding value controllato. Per i valori iniziali, usate le proprietà predefinite documentate.
Comporre usando i vostri blocchi
La composizione non è limitata alle pagine. I tag dei blocchi vengono renderizzati automaticamente nei template dei blocchi, così un blocco del progetto può generare direttamente componenti bsui e racchiuderli nella propria struttura:
<div useBlockProps class="settings-panel">
<bs:bsui-switch label="Public profile" name="public" />
<bs:bsui-space size="4" />
<bs:bsui-button label="Save" variant="default" />
</div>
Lo stesso vale da PHP con bs_block(), anche annidando tramite la chiave content, come descritto nella sezione rendering programmatico. In entrambi i casi, il foglio di stile e lo store del componente vengono caricati insieme a esso e il vostro blocco resta un sottile livello di disposizione dei componenti di sistema.
Per disporre i componenti affiancati, bsui/stack è la riga o colonna flex generica: direction, gap sulla scala delle spaziature, align, justify e un interruttore wrap. Per impostazione predefinita, i figli mantengono le loro dimensioni naturali; l'interruttore grow li allunga in modo che condividano equamente la lunghezza della pila. È così che in un footer due pulsanti si dividono la larghezza invece di restare ammassati a un'estremità.
Gruppi di campi e schede
bsui/field-group visualizza un fieldset. La variante predefinita raggruppa i campi correlati senza aggiungere una superficie. Usate variant="card" per una cornice esterna attenuata, quindi inserite i campi dentro bsui/field-group-content per ottenere una superficie di contenuto incassata. Mantenete il titolo e la descrizione fuori da questo blocco di contenuto:
<bs:bsui-field-group variant="card">
<bs:bsui-field-group-title text="Account settings" />
<bs:bsui-field-group-description text="Manage your account preferences." />
<bs:bsui-field-group-content>
<bs:bsui-field>
<bs:bsui-field-label text="Display name" />
<bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
</bs:bsui-field>
<bs:bsui-field>
<bs:bsui-field-label text="Email" />
<bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
</bs:bsui-field>
</bs:bsui-field-group-content>
</bs:bsui-field-group>
disabled="true" sul gruppo usa il comportamento nativo del fieldset per disabilitare
i controlli del modulo. Lo stile della scheda non modifica la variante predefinita.
Separatore della barra degli strumenti
Posizionate bsui/toolbar-separator tra gli elementi della barra degli strumenti. Segue orientation del contenitore principale: una barra degli strumenti orizzontale mostra un separatore verticale a tutta altezza, mentre una barra verticale mostra un separatore orizzontale a tutta larghezza.
I separatori si estendono fino ai bordi interni della barra degli strumenti senza modificare l'altezza dei controlli. Una barra degli strumenti orizzontale scorre quando il contenuto supera la larghezza disponibile.
Il modello a livelli
È quando le superfici si sovrappongono che le librerie di componenti di solito mostrano i loro limiti. I componenti inclusi seguono poche regole, pensate per chi realizza interfacce reali.
I modali vengono trasferiti nel body
Quando si apre una finestra di dialogo, una finestra di avviso o un pannello laterale, il popup e il backdrop vengono spostati in document.body; un commento segnaposto indica dove reinserirli alla chiusura. Il portaling libera il modale da qualsiasi overflow, trasform o contesto di sovrapposizione antenato. L'apertura blocca anche lo scorrimento della pagina: il blocco usa un conteggio di riferimenti condiviso da tutti i componenti overlay e compensa la larghezza della barra di scorrimento per evitare spostamenti della pagina. Il backdrop si trova a z-index: 50, il popup a 51, il focus passa al popup, il tasto Tab resta al suo interno e, alla chiusura, il focus torna al trigger.
Le finestre modali si sovrappongono. Aprendo una finestra di dialogo da un'altra finestra di dialogo, questa viene aggiunta a un unico stack condiviso: solo la finestra più esterna mostra lo sfondo oscurato, mentre quelle dietro a quella in primo piano si rimpiccioliscono e fanno capolino. Lo stack determina una proprietà personalizzata --bs-ui-nested-dialogs su ogni popup sullo sfondo, così lo spostamento e la scala aumentano a ogni livello, e l'elemento padre adatta la propria altezza a quella del figlio, in modo che i livelli facciano capolino in modo uniforme. Alla chiusura, tutto viene ripristinato in ordine inverso, un livello alla volta.
Quando una finestra modale si chiude, lo stato attivo torna al suo elemento di attivazione, quello giusto. Un helper condiviso getAnchor individua il pulsante di sistema all'interno dell'elemento che funge da trigger, così lo stato attivo torna al controllo visibile anziché a un contenitore invisibile.
La finestra modale in primo piano non viene mai trasformata
L'effetto di sovrapposizione trasforma solo le finestre di dialogo sullo sfondo. La finestra modale in primo piano rimane volutamente non trasformata, perché un elemento trasformato diventa il blocco contenitore per i discendenti position: fixed, compromettendo ogni popup flottante aperto al suo interno.
Questa regola permette all'intero modello di sovrapposizione di funzionare in modo coerente. Tutti i livelli flottanti si posizionano con coordinate fisse, che si riferiscono al viewport solo se non interviene alcun antenato trasformato:
- Il menu e la casella combinata calcolano la propria posizione rispetto al trigger con la strategia
fixeddi Floating UI, aprendosi sotto di esso e capovolgendosi o spostandosi quando manca spazio nel viewport. - Il selettore fa lo stesso quando non è stata selezionata alcuna opzione. Se invece è già presente una selezione, allinea il popup in modo che l'opzione selezionata si trovi direttamente sopra il trigger, mantenendolo entro il viewport, come fanno i selettori nativi su macOS.
- Il menu contestuale si apre alle coordinate
clientX/clientYdel puntatore.
Poiché la finestra modale in primo piano non è trasformata, tutti questi elementi si ancorano correttamente ai rispettivi trigger all'interno di una finestra di dialogo, una finestra di dialogo di avviso o un pannello a scomparsa, a qualsiasi livello di annidamento. I popup non sanno di trovarsi dentro una finestra modale e non devono saperlo.
Escape chiude prima il livello più interno
Premendo Escape si chiude un solo livello alla volta, dall'interno verso l'esterno:
- Per prima si chiude un livello flottante aperto (una casella di riepilogo di un selettore, un menu, un popover o un popup per date o numeri di telefono) e lo stato attivo torna al suo trigger. Il selettore interrompe la propagazione dell'evento e i gestori della finestra modale non intervengono quando è aperto un livello flottante, così la finestra di dialogo sottostante non rileva quella pressione del tasto.
- Poi si chiude la finestra modale in primo piano.
- Se ci sono più finestre modali sovrapposte, ogni ulteriore pressione di Escape ne rimuove una dallo stack.
La chiusura segue una regola precisa, non è casuale. Una finestra di dialogo visualizzata con dismissable="false" ignora sia Escape sia i clic sullo sfondo. E bsui/alert-dialog risponde a Escape come una qualsiasi finestra modale, ma ignora volutamente i clic sullo sfondo: lo scopo di questo schema è richiedere una scelta esplicita, evitando chiusure accidentali. I clic sullo sfondo chiudono una normale finestra di dialogo, poiché dismissable è impostato su true per impostazione predefinita.
Un modulo in una finestra di dialogo
Questo schema mette alla prova tutte le regole precedenti: un trigger apre una finestra modale, che contiene un modulo con convalida, al cui interno si trova un selettore flottante.
<bs:bsui-dialog>
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
<bs:bsui-dialog-backdrop />
<bs:bsui-dialog-popup>
<bs:bsui-dialog-header>
<bs:bsui-dialog-title content="Invite a teammate" />
<bs:bsui-dialog-description content="They receive an email with a join link." />
</bs:bsui-dialog-header>
<bs:bsui-dialog-content>
<bs:bsui-form block="team/invite" successMessage="Invitation sent.">
<bs:bsui-field name="email">
<bs:bsui-field-label text="Email" />
<bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
<bs:bsui-field-error />
</bs:bsui-field>
<bs:bsui-field name="role">
<bs:bsui-field-label text="Role" />
<bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
<bs:bsui-select-trigger />
<bs:bsui-select-popup>
<bs:bsui-select-option value="viewer" label="Viewer" />
<bs:bsui-select-option value="editor" label="Editor" />
<bs:bsui-select-option value="admin" label="Admin" />
</bs:bsui-select-popup>
</bs:bsui-select>
</bs:bsui-field>
<bs:bsui-space size="2" />
<bs:bsui-button label="Send invite" />
</bs:bsui-form>
</bs:bsui-dialog-content>
<bs:bsui-dialog-footer>
<bs:bsui-dialog-close label="Cancel" />
</bs:bsui-dialog-footer>
</bs:bsui-dialog-popup>
</bs:bsui-dialog>
Ogni tag e attributo sopra è essenziale: il trigger inoltra al pulsante di sistema, il titolo e la descrizione ricevono content, i campi hanno i nomi che il modulo serializza e required="true" viene convertito in un vero valore booleano dal parser dei tag.
Cosa fa ogni store durante l'esecuzione
bsui/dialog inserisce {"open":false,"dismissable":true} nel contesto sul server. Al clic sul trigger viene eseguito actions.open: il popup e lo sfondo oscurato vengono aggiunti al body tramite portal, lo scorrimento viene bloccato compensando la barra di scorrimento, il popup si anima per 150ms, lo stato attivo passa al primo elemento selezionabile e il tasto Tab scorre gli elementi al suo interno. Le aree dell'intestazione, del contenuto e del piè di pagina si distanziano usando i token di spaziatura delle finestre modali.
bsui/select attende nel modulo insieme alla sua casella di riepilogo hidden. Facendo clic sul trigger si attiva context.open, la casella di riepilogo viene posizionata con coordinate fisse rispetto al viewport e, poiché defaultValue="editor" è già selezionato, il popup si allinea in modo che Editor si trovi direttamente sopra il trigger. I tasti freccia, Home, End e la digitazione anticipata spostano l'opzione attiva; con Invio o un clic si seleziona un'opzione; Tab e i clic all'esterno chiudono il popup senza selezionare nulla. Il testo visibile del trigger si aggiorna tramite data-wp-text="state.displayValue", mentre il campo <input name="role"> nascosto mantiene il valore aggiornato tramite data-wp-bind--value="state.selectedValue", che verrà poi serializzato dal modulo. Tutto si ancora correttamente all'interno della finestra di dialogo perché la finestra modale in primo piano non è trasformata.
bsui/form intercetta l'invio. L'elemento bsui/button in fondo al modulo genera un semplice elemento button senza attributo type, quindi per impostazione predefinita di HTML è il controllo di invio del modulo; il pulsante Annulla si trova nel piè di pagina, fuori dall'elemento form, e non può inviare nulla. Al momento dell'invio, lo store serializza i FormData del modulo e li trasmette tramite il API dati del blocco indicato in block, creando qui una riga nello schema del database del blocco team/invite. Gli errori di convalida vengono restituiti per ciascun campo: ogni bsui/field porta il proprio name, viene contrassegnato come non valido, sposta il colore del contorno di messa a fuoco su quello di errore e mostra il messaggio nell'avviso bsui/field-error. In caso di successo, il corpo del modulo viene nascosto e viene mostrato successMessage, entrambi tramite data-wp-bind--hidden.
I livelli si chiudono in ordine. Con la casella di riepilogo aperta, Escape la chiude e riporta lo stato attivo al trigger del selettore; con la pressione successiva, Escape chiude la finestra di dialogo e riporta lo stato attivo su Invita un collaboratore. Un clic sullo sfondo chiude la finestra di dialogo perché dismissable è rimasto al valore predefinito. La chiusura sblocca lo scorrimento e rimuove il popup dal portal, riportandolo nella sua posizione nel documento.
Incollando lo stesso markup in una pagina basata su file, questo viene sincronizzato come blocchi nativi; la stessa composizione realizzata nell'editor viene visualizzata in modo interattivo nell'area di lavoro, perché ogni comportamento descritto sopra è gestito da direttive e store caricati in entrambi i contesti.
Cosa mantiene funzionali queste interazioni
Le interazioni descritte sopra non sono convenzioni, ma invarianti garantite dalla libreria in ogni contesto di visualizzazione: ogni etichetta usa la stessa tipografia, ogni popup modale condivide la stessa superficie e oscura la pagina sottostante, i popup flottanti restano ancorati al trigger mentre la pagina scorre ed Escape chiude un solo livello alla volta, dall'interno verso l'esterno. Queste garanzie valgono nel frontend e nell'area di lavoro dell'editor, con i token predefiniti o quelli del tema, perciò una composizione che funziona in un contesto si comporta allo stesso modo anche negli altri.
Esempi interattivi
Le composizioni di questa pagina mostrano la grammatica; /ui/examples è il frasario. Raccoglie composizioni visualizzate e interattive in tre livelli: combinazioni che dimostrano un'interazione tra due o tre componenti, schemi di prodotto riconoscibili realizzati con alcuni componenti e mini app complete assemblate come i componenti vengono forniti nei prodotti reali. La pagina di ciascun componente in /ui include altri esempi pratici, da un campo con etichetta a un calendario dietro un popover.
Il modello basato su direttive e store su cui sono costruiti i componenti UI e come usarlo nei vostri blocchi.