ToolsPanel : un menu Réinitialiser range mieux vos options qu’un empilement

La documentation du paquet @wordpress/components présente ToolsPanel comme un composant « conçu pour remplacer l’empilement de contrôles dans InspectorControls, en permettant de masquer les réglages optionnels et de les réinitialiser individuellement ». Concrètement, ce composant répond à un problème que rencontrent tous les blocs qui accumulent des réglages avancés au fil des versions : un panneau latéral qui s’allonge sans fin, où chaque nouvelle option ajoute une ligne supplémentaire, jusqu’à rendre le panneau difficile à parcourir.

Ce tutoriel détaille comment migrer un panneau de réglages classique, construit avec un empilement de PanelBody et de contrôles simples, vers un ToolsPanel qui distingue les réglages essentiels des réglages optionnels.

Étape 1 : identifier les réglages réellement optionnels

Avant toute migration technique, il faut distinguer les réglages qu’un rédacteur consulte à chaque usage du bloc (par exemple l’alignement) de ceux qu’il ne touche que rarement (une couleur d’accent personnalisée, un espacement fin). Cette distinction guide directement la structure du ToolsPanel à venir.

Étape 2 : structurer le panneau avec ToolsPanelItem

import { ToolsPanel, ToolsPanelItem } from '@wordpress/components';

function ReglagesBloc( { attributes, setAttributes } ) {
    const { couleurAccent, espacementFin } = attributes;

    return (
        <ToolsPanel label="Réglages avancés" resetAll={ () => {
            setAttributes( { couleurAccent: undefined, espacementFin: undefined } );
        } }>
            <ToolsPanelItem
                label="Couleur d'accent"
                hasValue={ () => !! couleurAccent }
                onDeselect={ () => setAttributes( { couleurAccent: undefined } ) }
            >
                <ColorPalette
                    value={ couleurAccent }
                    onChange={ ( valeur ) => setAttributes( { couleurAccent: valeur } ) }
                />
            </ToolsPanelItem>

            <ToolsPanelItem
                label="Espacement fin"
                hasValue={ () => !! espacementFin }
                onDeselect={ () => setAttributes( { espacementFin: undefined } ) }
            >
                <RangeControl
                    label="Espacement fin"
                    value={ espacementFin }
                    onChange={ ( valeur ) => setAttributes( { espacementFin: valeur } ) }
                />
            </ToolsPanelItem>
        </ToolsPanel>
    );
}

Chaque ToolsPanelItem déclare sa propre logique de présence (hasValue) et de réinitialisation (onDeselect), ce qui permet au composant parent de savoir, sans logique supplémentaire à écrire, quelles options afficher par défaut et lesquelles proposer dans le menu.

Étape 3 : le menu qui liste les options masquées

Une fois cette structure en place, un bouton représentant trois points apparaît en en-tête du panneau, ouvrant un menu qui liste chaque ToolsPanelItem non actuellement affiché. Cliquer sur une entrée de ce menu affiche le contrôle correspondant, sans avoir à faire défiler un panneau surchargé pour le retrouver.

Étape 4 : tester la réinitialisation globale

Le bouton « Réinitialiser tout », déclenché par la fonction resetAll passée au composant ToolsPanel, doit remettre chaque attribut concerné à sa valeur par défaut. Un test manuel consiste à régler plusieurs options, cliquer sur ce bouton, puis vérifier que le rendu du bloc revient bien à son état initial, sans attribut orphelin conservé en mémoire.

Ce que ce composant change concrètement

• Un panneau qui comptait auparavant huit contrôles visibles simultanément n’en affiche plus que trois ou quatre par défaut, les autres restant accessibles via le menu.
• Chaque option masquée peut être réintroduite individuellement, sans devoir rouvrir un panneau entier de réglages avancés séparé.
• La réinitialisation devient uniforme d’un bloc à l’autre, puisque le composant impose la même mécanique partout où il est utilisé.

Limites observées lors de la migration

Migrer un panneau existant demande de réécrire chaque contrôle en ToolsPanelItem, ce qui représente un effort réel sur un bloc qui compte déjà une dizaine de réglages. Sur un bloc neuf, en revanche, partir directement sur cette structure ne coûte rien de plus qu’un empilement classique de PanelBody, avec un bénéfice immédiat pour l’utilisateur final.

Sur nos blocs les plus riches en options, migrer vers ToolsPanel a réduit de façon nette le nombre de tickets de support liés à « je ne retrouve plus le réglage que j’avais modifié la semaine dernière ».

En résumé

ToolsPanel ne remplace pas InspectorControls, il en réorganise le contenu interne pour distinguer réglages courants et réglages avancés. Dès qu’un panneau dépasse cinq ou six contrôles, la migration mérite d’être envisagée, avec un gain d’usage tangible pour tout rédacteur qui manipule le bloc régulièrement.