Composants
Composition
Les composants groupés UI sont conçus pour être assemblés, et non utilisés individuellement. Une liste de sélection s'ouvre dans une boîte de dialogue, un formulaire est validé dans un tiroir, un menu s'affiche dans une ligne de tableau. Cette page explique les mécanismes qui font fonctionner ces interactions : la structure des familles de composants, la manière dont les déclencheurs transmettent les propriétés des boutons, le rôle du API Interactivity en arrière-plan et le modèle de superposition qui permet aux éléments empilés de cohabiter harmonieusement.
Familles de composants composés
Un composant composé se compose d'un bloc racine et de blocs enfants. La racine détient l'état ; chaque enfant déclare sa place dans la famille à l'aide de parent et usesContext dans son block.json :
{
"name": "bsui/select-option",
"parent": ["bsui/select-popup"],
"usesContext": ["bsui/select"]
}
Les racines exposent une zone InnerBlocks comprenant une liste allowedBlocks et un template initial. Ainsi, l'insertion d'une boîte de dialogue dans l'éditeur crée son déclencheur, son arrière-plan et sa fenêtre contextuelle. La famille se comporte de la même façon, qu'elle soit composée dans l'éditeur, dans une page basée sur des fichiers ou dans des balises :
<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>
Les fenêtres contextuelles et les panneaux sont de véritables zones InnerBlocks, et non des emplacements à syntaxe spéciale. Un bsui/dialog-popup accepte les blocs imbriqués comme le ferait un bloc de groupe ; il est donc tout à fait courant d'y placer un formulaire, une liste de sélection ou une autre boîte de dialogue.
Données à plat ou enfants composés
Certaines familles acceptent leur contenu sous forme de données plutôt que d'enfants. La liste de sélection génère son propre déclencheur et sa propre boîte de liste lorsqu'on lui fournit un tableau options JSON, ce qui convient aux options issues de 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'],
]),
],
]);
Les deux formes produisent le même balisage et le même comportement à l'exécution. Utilisez des enfants lorsque la structure est définie à l'avance et options lorsqu'elle est calculée.
Transmission des propriétés du déclencheur
Les composants superposés s'ouvrent à partir d'un bouton, et ce bouton doit être celui du système. Plutôt que de réimplémenter un bouton dans chaque déclencheur, les blocs déclencheurs de bsui/dialog, bsui/alert-dialog, bsui/drawer, bsui/menu, bsui/popover, bsui/collapsible et bsui/tooltip intègrent bsui/button via un champ de bloc :
{
"blockstudio": {
"attributes": [
{
"id": "trigger",
"type": "block",
"block": "bsui/button",
"idStructure": "trigger_{id}"
}
]
}
}
Le idStructure déploie les champs du bouton sur le déclencheur avec le préfixe trigger_. Toutes les propriétés du bouton sont disponibles : 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" />
Dans le modèle du déclencheur, $a['trigger'] correspond au bouton entièrement rendu, qui conserve ainsi sa feuille de style et ses futures améliorations. À l'exécution, un utilitaire partagé transmet au bouton interne la configuration ARIA de l'enveloppe (aria-haspopup, aria-expanded, aria-controls, aria-describedby, aria-labelledby, id) et la synchronise au moyen d'un MutationObserver. Les technologies d'assistance voient ainsi un seul contrôle cohérent.
Le API Interactivity en arrière-plan
Chaque famille interactive est un magasin WordPress Interactivity API nommé d'après son bloc racine : bsui/dialog, bsui/select, bsui/form, bsui/tabs, et ainsi de suite. Trois conséquences en découlent.
L'état est initialisé côté serveur. Le modèle de la racine affiche son état initial sous forme de data-wp-context, directement à partir des attributs du bloc :
<div
data-wp-interactive="bsui/select"
data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
data-bsui-select-root
>
Le premier affichage est correct HTML, sans flash d'hydratation côté client ; les fenêtres contextuelles démarrent hidden et le même balisage fonctionne dans le canevas de l'éditeur, car le contexte ne dépend pas d'une étape d'état propre à l'interface frontale.
Le comportement est défini par des directives, et non par votre JavaScript. Les modèles relient le balisage aux magasins de manière déclarative. Une fois son PHP retiré, le déclencheur de la liste de sélection ne contient que des directives :
<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 achemine les événements vers des actions, data-wp-bind synchronise les attributs avec l'état calculé, data-wp-text affiche l'état sous forme de texte et data-wp-on-document--click permet aux éléments racines de se fermer lorsqu'on clique à l'extérieur. Composer des composants ne nécessite jamais d'écrire de gestionnaire d'événements : le magasin est fourni avec le bloc sous forme de module intégré.
Vos magasins peuvent se connecter à ces interfaces. Les contrôles de formulaire acceptent des expressions de directives comme attributs, et la syntaxe avec espace de noms du API Interactivity permet de les relier à n'importe quel magasin. onChange associe la gestion des changements à l'une de vos actions, checked lie l'état du contrôle au vôtre et bindText affiche un libellé dans un élément span data-wp-text lié à n'importe quel chemin d'état :
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />
bindText est disponible sur les éléments bsui/label, bsui/checkbox, bsui/switch, bsui/toggle et bsui/radio-group. Pour les cases à cocher, les interrupteurs et les boutons radio, il est transmis à l'élément d'étiquette partagé, afin que le texte piloté par l'état conserve exactement la typographie des libellés du système. Les listes de sélection et les autres champs déclenchent aussi un événement change propagé depuis leur racine, qui transmet la nouvelle valeur dans detail pour les intégrations plus générales.
Valeurs contrôlées
Laissez value ou checked non défini pour un contrôle qui gère lui-même sa valeur. Utilisez
defaultValue, defaultChecked ou defaultPressed de Toggle pour sa sélection initiale.
Un Toggle autonome gère les interactions à la souris et au clavier sans magasin de données client.
Pour contrôler un champ à partir de votre propre magasin, fournissez à la fois sa liaison et une
action onChange qui met à jour la valeur liée. value est un chemin de directive,
et non une valeur par défaut littérale. Input, Textarea, Password Input, Number Field, Slider,
Radio Group, Color Picker, Rating et Time Picker prennent en charge value.
Checkbox, Switch et Toggle utilisent plutôt checked.
Qualifiez les chemins avec l’espace de noms propriétaire, par exemple
my/settings::context.quantity ou my/settings::state.quantity. Les contrôles composés
ont leur propre espace de noms ; un chemin non qualifié désigne ce contrôle,
et non automatiquement le magasin parent. Les liaisons de valeur des contrôles composés acceptent les chemins
à points dans le contexte ou l’état, y compris les clés numériques de tableau, mais pas les expressions
JavaScript ni les appels de fonction.
Voici une liaison Number Field complète dans un bloc personnalisé avec la prise en charge de l’Interactivity API activée :
<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;
}
},
},
});
Définissez la valeur initiale par défaut correspondante pour le rendu côté serveur. Une fois l’interface hydratée,
les modifications du parent mettent à jour chaque instance liée, y compris pour zéro, faux et les valeurs vides.
Les champs de formulaire masqués de Checkbox et Switch suivent aussi leur liaison checked.
Les valeurs de Time Picker utilisent HH:MM au format 24 heures ou une chaîne vide.
Pour les gestionnaires natifs de Input, Textarea et Password Input, lisez
event.target.value ; les contrôles de valeur composés publient event.detail.value.
Les limites de Number Field sont facultatives : si min et max sont omis, le champ n’a pas de limites,
tandis que zéro explicitement défini reste une limite valide.
Select, Date Input, Phone Input et OTP Input publient les modifications via
onChange, mais n’exposent pas cette liaison contrôlée value. Utilisez leurs
propriétés par défaut documentées pour définir les valeurs initiales.
Composer à partir de vos propres blocs
La composition ne se limite pas aux pages. Les balises de bloc sont automatiquement rendues dans les modèles de bloc, de sorte qu'un bloc de projet peut émettre directement des composants bsui et les intégrer à sa propre structure :
<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>
Le même procédé fonctionne depuis PHP avec bs_block(), y compris pour l'imbrication via la clé content, comme indiqué dans la section Rendu par programmation. Dans les deux cas, la feuille de style et le magasin du composant sont chargés avec lui, et votre bloc reste une fine couche d'agencement reposant sur les éléments du système.
Pour disposer des composants côte à côte, bsui/stack est la ligne ou la colonne flex générique : direction, gap sur l'échelle d'espacement, align, justify et un commutateur wrap. Par défaut, les enfants gardent leur taille naturelle ; le commutateur grow les étire pour qu'ils occupent équitablement la longueur de la pile, ce qui permet à deux boutons de partager la largeur d'un pied de page au lieu de rester regroupés à une extrémité.
Groupes de champs et cartes
bsui/field-group génère un fieldset. La variante par défaut regroupe les champs associés
sans ajouter de surface. Utilisez variant="card" pour un cadre extérieur discret,
puis placez les champs dans bsui/field-group-content pour obtenir une surface de contenu en retrait. Gardez le titre et la description en dehors de ce bloc de contenu :
<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" du groupe utilise le comportement natif de fieldset pour désactiver
ses contrôles de formulaire. Le style de carte ne modifie pas la variante par défaut.
Séparateurs de barre d’outils
Placez bsui/toolbar-separator entre les éléments de la barre d’outils. Il suit orientation du parent : une barre d’outils horizontale affiche un séparateur vertical sur toute sa hauteur, tandis qu’une barre verticale affiche un séparateur horizontal sur toute sa largeur.
Les séparateurs s’étendent jusqu’aux bords intérieurs de la bordure de la barre d’outils sans modifier la hauteur des contrôles. Une barre d’outils horizontale défile lorsque son contenu dépasse la largeur disponible.
Modèle de superposition
Les surfaces empilées sont souvent le point faible des bibliothèques de composants. Les composants fournis suivent quelques règles simples, conçues pour les personnes qui créent de véritables interfaces.
Les modales sont ajoutées au corps de la page
À l'ouverture d'une boîte de dialogue, d'une boîte de dialogue d'alerte ou d'un tiroir, sa fenêtre contextuelle et son arrière-plan sont déplacés vers document.body ; un commentaire de remplacement indique où les replacer à la fermeture. Le déplacement hors de l'arborescence libère la modale du overflow de tout élément parent, de sa transformation ou de son contexte d'empilement. L'ouverture verrouille aussi le défilement de la page : le verrou est comptabilisé pour tous les composants superposés et compense la largeur de la barre de défilement afin d'éviter tout décalage de la page. L'arrière-plan se place à z-index: 50, la fenêtre contextuelle à 51 ; le focus passe dans la fenêtre, la touche Tab y reste confinée et la fermeture le rend au déclencheur.
Les modales s'empilent. Ouvrir une boîte de dialogue depuis une autre l'ajoute à une pile partagée : seule la boîte de dialogue la plus à l'extérieur affiche son arrière-plan, et celles qui se trouvent derrière la modale du dessus sont réduites et dépassent derrière elle. La pile définit une propriété personnalisée --bs-ui-nested-dialogs sur chaque popup d'arrière-plan, de sorte que le décalage et la réduction s'accentuent à chaque niveau. Le parent ajuste sa hauteur à celle de l'enfant afin que les couches dépassent uniformément. À la fermeture, tout est rétabli en sens inverse, une couche à la fois.
Lorsqu'une modale se ferme, le focus revient à son déclencheur et se place sur le bon élément. Un utilitaire partagé getAnchor trouve le bouton système à l'intérieur du conteneur du déclencheur, afin que le contrôle visible retrouve le focus plutôt qu'un conteneur invisible.
La modale supérieure n'est jamais transformée
Cet effet de profondeur ne transforme que les boîtes de dialogue d'arrière-plan. La modale supérieure reste volontairement sans transformation, car un élément transformé devient le bloc conteneur des descendants position: fixed, ce qui perturberait tous les popups flottants ouverts à l'intérieur.
C'est cette règle qui permet au modèle de superposition de fonctionner dans tous les cas. Toutes les couches flottantes se positionnent avec des coordonnées fixes, qui ne correspondent à la fenêtre d'affichage que si aucun ancêtre transformé ne s'interpose :
- Le menu et la combobox calculent leur position par rapport au déclencheur avec la stratégie
fixedde Floating UI : ils s'ouvrent en dessous et se retournent ou se décalent lorsque la fenêtre d'affichage manque d'espace. - Le sélecteur fait de même lorsqu'aucune option n'est sélectionnée. Si une option est déjà sélectionnée, il aligne plutôt son popup de sorte que l'option sélectionnée se trouve juste au-dessus du déclencheur, dans les limites de la fenêtre d'affichage, comme les sélecteurs natifs sur macOS.
- Le menu contextuel s'ouvre aux coordonnées
clientX/clientYdu pointeur.
Comme la modale supérieure n'est pas transformée, tous ces éléments s'ancrent correctement à leurs déclencheurs à l'intérieur d'une boîte de dialogue, d'une boîte de dialogue d'alerte ou d'un panneau latéral, quel que soit le niveau d'imbrication. Les popups n'ont pas besoin de savoir qu'ils se trouvent dans une modale.
La touche Échap ferme d'abord la couche la plus imbriquée
Une pression sur Échap ferme une seule couche, en partant de l'intérieur :
- Une couche flottante ouverte (la listbox d'un sélecteur, un menu, une fenêtre contextuelle, un popup de date ou de téléphone) se ferme d'abord et rend le focus à son déclencheur. Le sélecteur arrête la propagation de l'événement, et les gestionnaires de modale se désactivent également lorsqu'une couche flottante est ouverte : la boîte de dialogue en dessous ne reçoit donc jamais cette pression.
- La modale supérieure se ferme ensuite.
- Lorsque des modales sont empilées, chaque pression supplémentaire sur Échap en retire une de plus de la pile.
La fermeture suit une règle précise, elle n'est pas le fruit du hasard. Une boîte de dialogue rendue avec dismissable="false" ignore à la fois Échap et les clics sur l'arrière-plan. Et bsui/alert-dialog réagit à Échap comme toute modale, mais ignore volontairement les clics sur l'arrière-plan : ce modèle impose de faire un choix plutôt que de fermer par inadvertance. Un clic sur l'arrière-plan ferme une boîte de dialogue ordinaire, car dismissable vaut true par défaut.
Un formulaire dans une boîte de dialogue
Le modèle qui met simultanément à l'épreuve toutes les règles ci-dessus : un déclencheur ouvre une modale, qui contient un formulaire avec validation, lequel contient à son tour un sélecteur flottant.
<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>
Chaque balise et attribut ci-dessus est essentiel : le déclencheur transmet l'action au bouton système, le titre et la description reçoivent content, les champs portent les noms sérialisés par le formulaire, et required="true" est converti en véritable booléen par l'analyseur de balises.
Rôle de chaque store à l'exécution
bsui/dialog injecte {"open":false,"dismissable":true} dans le contexte côté serveur. Le clic sur le déclencheur exécute actions.open : le popup et son arrière-plan sont montés dans le body, le défilement est verrouillé avec compensation de la barre de défilement, le popup s'anime pendant 150 ms, le focus passe à son premier élément pouvant le recevoir et la touche Tab reste dans le popup. Les zones d'en-tête, de contenu et de pied de page s'espacent selon les tokens d'espacement des modales.
bsui/select attend dans le formulaire avec sa listbox hidden. Un clic sur le déclencheur inverse context.open, positionne la listbox avec des coordonnées fixes par rapport à la fenêtre d'affichage et, comme defaultValue="editor" est déjà sélectionné, aligne le popup pour que l'option Editor se trouve juste au-dessus du déclencheur. Les touches fléchées, Début, Fin et la saisie de texte déplacent l'option active ; Entrée ou un clic sélectionne une option ; Tab et les clics à l'extérieur ferment le popup sans sélectionner d'option. Le texte visible du déclencheur est mis à jour via data-wp-text="state.displayValue", et le champ <input name="role"> masqué suit la valeur via data-wp-bind--value="state.selectedValue", qui sera ensuite sérialisée par le formulaire. Tout cela s'ancre correctement dans la boîte de dialogue, car la modale supérieure n'est pas transformée.
bsui/form intercepte la soumission. Le bsui/button situé à la fin du formulaire affiche un élément button simple, sans attribut type ; il sert donc de commande d’envoi du formulaire par défaut selon HTML. Le bouton Annuler se trouve dans le pied de page, à l’extérieur de l’élément form, et ne peut rien envoyer. Lors de l’envoi, le magasin sérialise les FormData du formulaire et les transmet par le API de données du bloc nommé dans block, créant ici une ligne dans le team/invite schéma de base de données. Les erreurs de validation sont renvoyées champ par champ : chaque bsui/field reçoit son name, est signalé comme invalide, déplace l’anneau de focus vers la couleur destructive et affiche le message dans son alerte bsui/field-error. En cas de réussite, le corps du formulaire est masqué et le successMessage s’affiche, les deux par l’intermédiaire de data-wp-bind--hidden.
Les couches se ferment dans l'ordre. Lorsque la listbox est ouverte, Échap la ferme et redonne le focus au déclencheur du sélecteur ; la pression suivante sur Échap ferme la boîte de dialogue et redonne le focus à Invite teammate. Un clic sur l'arrière-plan ferme la boîte de dialogue, car dismissable a conservé sa valeur par défaut. La fermeture déverrouille le défilement et remet le popup à son emplacement dans le document.
Le même balisage, collé dans une page basée sur un fichier, est synchronisé sous forme de blocs natifs. La même composition, assemblée dans l'éditeur, s'affiche de manière interactive dans le canevas, car tous les comportements décrits reposent sur des directives et des stores chargés dans les deux contextes.
Ce qui garantit le bon fonctionnement de ces interfaces
Les interfaces décrites ci-dessus ne sont pas de simples conventions : la bibliothèque garantit ces invariants partout où elle effectue un rendu. Chaque libellé utilise une typographie identique, chaque popup modal partage la même surface et assombrit la page derrière lui, les popups flottants restent ancrés à leur déclencheur pendant le défilement de la page, et Échap ferme exactement une couche à la fois, de l'intérieur vers l'extérieur. Ces garanties s'appliquent à l'interface publique et au canevas de l'éditeur, avec les tokens par défaut ou ceux de votre thème. Une composition qui fonctionne dans un contexte fonctionne donc de la même manière dans les autres.
Exemples interactifs
Les compositions de cette page constituent la grammaire ; /ui/examples en est le guide d'expressions. Il rassemble des compositions rendues et interactives réparties en trois niveaux : des associations qui illustrent une interface entre deux ou trois composants, des modèles de produit reconnaissables construits à partir de quelques composants, et des mini-applications complètes assemblées comme les composants le sont dans de vrais produits. Chaque page de composant sur /ui propose ses propres exemples détaillés, du champ avec libellé au calendrier derrière une fenêtre contextuelle.
Le modèle de directives et de stores sur lequel reposent les composants UI, et comment l'utiliser dans vos propres blocs.