@wordpress/components

Définition : @wordpress/components est la bibliothèque de composants d’interface WordPress : boutons, champs, panneaux et contrôles. Elle aide à construire des écrans cohérents avec l’administration et l’éditeur.

Comprendre et utiliser

À quoi cela sert ?

Elle évite de recréer des contrôles basiques avec des styles et comportements divergents. Elle reste une bibliothèque UI : ses composants ne sauvegardent pas automatiquement les données métier.

Comment cela fonctionne ?

TextControl, ToggleControl ou PanelBody reçoivent des valeurs et des callbacks. Dans un bloc, setAttributes() permet de relier un contrôle aux attributs édités.

Dans quel contexte l’utiliser ?

Employer cette bibliothèque pour les réglages d’un bloc ou les interfaces administratives créées en JavaScript, lorsque le comportement attendu est de modifier un état contrôlé.

Cas concret : ATOOLPHA

Pour un bloc « Encadré », proposer un interrupteur permettant d’activer ou non une bordure, sans obliger le rédacteur à taper une classe CSS.

Exemple de code commenté

Extrait documentaire : le contexte WordPress du plugin/éditeur et les dépendances décrites sont nécessaires ; ne pas coller dans le contenu d’une page.

const { ToggleControl } = wp.components;
const { createElement } = wp.element;
function BorderOption( { enabled, onChange } ) {
    return createElement( ToggleControl, {
        label: 'Afficher une bordure',
        checked: Boolean( enabled ),
        onChange,
    } );
}

Décryptage de l’exemple

Le contrôle reçoit son état par enabled et remonte un nouveau booléen via onChange. Le parent doit connecter ce callback à setAttributes() ou à une autre source d’état appropriée.

Résultat attendu

Le bouton affiche immédiatement la valeur reçue ; aucun réglage WordPress n’est enregistré tant que le composant parent ne le fait pas.

Atelier pratique de vérification

Brancher un ToggleControl sur un attribut booléen et noter son état après trois modifications. Couper ensuite sa mise à jour contrôlée pour observer le retour à une valeur antérieure. Réparer le flux de données, puis expliquer ce que les composants d’interface fournissent et ce qu’ils ne sauvegardent pas eux-mêmes.

Précautions et limites

Ne pas confondre composant contrôlé et validation des données. Vérifier les types de valeurs, les permissions et les traitements serveur lors de l’enregistrement réel.

Contrôle avant intégration dans un plugin

Tester l’accessibilité des champs, leur traduction et les états désactivés. Les contrôles visuels ne remplacent ni la validation serveur, ni le contrôle d’autorisation sur les données qu’ils modifient.

À ne pas confondre

@wordpress/components fournit des champs génériques ; InspectorControls choisit leur emplacement dans l’interface d’un bloc.

Diagnostic et dépannage avancés

Si un ToggleControl revient à son état initial après une modification, vérifier que la propriété checked est effectivement mise à jour après le callback.