registerPlugin( 'export-json', { render: MonPlugin } ); — cette ligne, posée dans le fichier d’entrée d’une extension, suffit à préparer le terrain pour ajouter une action personnalisée dans un menu que les rédacteurs connaissent déjà : le menu Options accessible via les trois points verticaux au-dessus de chaque bloc sélectionné.
Ce menu contient par défaut des actions comme « Copier », « Dupliquer » ou « Créer un modèle ». Plutôt que d’ajouter un bouton de plus dans la barre d’outils du bloc, déjà chargée sur certains projets, PluginBlockSettingsMenuItem permet d’y glisser une action supplémentaire : dupliquer avec des réglages précis, exporter la structure du bloc en JSON, ou déclencher une validation métier propre à l’agence.
Pourquoi ne pas simplement ajouter un bouton dans BlockControls
BlockControls convient parfaitement aux actions fréquentes qu’un rédacteur doit atteindre en un clic pendant l’édition : alignement, style, mise en forme du texte. Une action plus ponctuelle, utilisée occasionnellement, encombre inutilement cette barre déjà dense si elle y est ajoutée. Le menu Options, lui, est justement l’endroit prévu pour les actions secondaires : il reste discret tant qu’on ne l’ouvre pas, et les rédacteurs savent déjà où le chercher.
Un menu partagé, pas un menu par bloc
Point important : ce menu est un seul et même composant partagé par l’éditeur, pas une instance propre à chaque bloc. Un PluginBlockSettingsMenuItem enregistré une fois s’affiche dans le menu Options de tous les blocs correspondant à son filtre, qu’il y en ait un ou cinquante sur la page.
Mise en place étape par étape
- Créer (ou réutiliser) un fichier JavaScript chargé dans l’éditeur via
enqueue_block_editor_assets. - Importer
PluginBlockSettingsMenuItemdepuis@wordpress/edit-postetregisterPlugindepuis@wordpress/plugins. - Définir la propriété
allowedBlockspour restreindre l’action aux blocs concernés, ou l’omettre pour qu’elle apparaisse partout. - Écrire la fonction
onClick, qui ne reçoit aucun argument utile : elle lit elle-même la sélection courante avecselect( 'core/block-editor' ).getSelectedBlockClientIds(). - Enregistrer le composant avec
registerPluginet vérifier son apparition dans le menu Options d’un bloc ciblé.
Le code complet du plugin
Voici un exemple qui ajoute une action « Exporter en JSON » aux blocs Groupe et Colonnes. Le fichier source est compilé avec @wordpress/scripts, qui déclare les dépendances de l’éditeur de lui-même :
import { registerPlugin } from '@wordpress/plugins';
import { PluginBlockSettingsMenuItem } from '@wordpress/edit-post';
import { select } from '@wordpress/data';
import { store as blockEditorStore } from '@wordpress/block-editor';
import { __ } from '@wordpress/i18n';
function nettoyer( blocs ) {
return blocs.map( ( { name, attributes, innerBlocks } ) => ( {
name,
attributes,
innerBlocks: nettoyer( innerBlocks ),
} ) );
}
function exporterSelection() {
const editeur = select( blockEditorStore );
const identifiants = editeur.getSelectedBlockClientIds();
const blocs = editeur.getBlocksByClientId( identifiants ).filter( Boolean );
const contenu = JSON.stringify( nettoyer( blocs ), null, 2 );
const fichier = new Blob( [ contenu ], { type: 'application/json' } );
const adresse = URL.createObjectURL( fichier );
const lien = document.createElement( 'a' );
lien.href = adresse;
lien.download = 'blocs.json';
lien.click();
URL.revokeObjectURL( adresse );
}
function MonPlugin() {
return (
<PluginBlockSettingsMenuItem
allowedBlocks={ [ 'core/group', 'core/columns' ] }
label={ __( 'Exporter en JSON', 'export-json' ) }
onClick={ exporterSelection }
/>
);
}
registerPlugin( 'export-json', { render: MonPlugin } );Trois choix méritent d’être expliqués. D’abord, la fonction de nettoyage retire les identifiants internes propres à la session d’édition : deux exports du même bloc produisent ainsi un fichier identique, ce qui permet de les comparer. Ensuite, le code lit la sélection dans le magasin de l’éditeur au moment du clic, plutôt que de compter sur un argument : quelle que soit la façon dont la fonction de rappel est appelée selon la version de l’éditeur, la sélection réelle est toujours disponible par ce chemin. Enfin, la fonction registerPlugin reçoit un nom unique, en minuscules et en tirets, qui identifie l’extension dans l’éditeur.
Cibler les bons blocs avec allowedBlocks
La propriété allowedBlocks attend un tableau de noms de blocs. L’action n’apparaît dans le menu que si tous les blocs sélectionnés figurent dans cette liste : sélectionnez un Groupe et un Paragraphe en même temps, et l’entrée disparaît. Ce comportement est voulu, car une action conçue pour un type de bloc a rarement un sens sur un autre. Omettre la propriété rend l’action disponible pour tous les blocs, y compris ceux que vous n’aviez pas prévus : c’est rarement souhaitable pour une action qui manipule des attributs précis.
Les autres propriétés utiles sont icon pour associer un pictogramme, small pour afficher l’icône seule avec l’étiquette en infobulle, et role si le comportement de l’entrée doit être annoncé autrement par les lecteurs d’écran, par exemple avec la valeur menuitemcheckbox pour une option qui s’active et se désactive.
Un cas concret : partager des mises en page entre deux sites
Une agence maintient deux sites qui partagent des sections de page, des groupes mêlant titre, image et bouton. Le menu « Créer un motif » existe, mais il enregistre la section dans le site courant : pour la transporter, il faut passer par l’import et l’export des motifs, une démarche que les rédacteurs évitent. Avec l’entrée « Exporter en JSON », ils sélectionnent le groupe, ouvrent le menu Options, et récupèrent un fichier qu’un second plugin, installé sur l’autre site, réimporte avec createBlock() et insertBlocks(). L’action tient dans le menu, sans alourdir la barre d’outils, et ne concerne que les blocs où elle a un sens.
Une barre d’outils doit contenir ce qu’on fait dix fois par heure ; le menu Options, ce qu’on fait dix fois par mois.
Les pièges à connaître
- Enregistrer deux plugins avec le même nom : le second est refusé, avec un simple message d’erreur dans la console du navigateur.
- Lire la sélection en dehors du clic, au moment du rendu : le composant se réaffiche alors à chaque changement de sélection, sans raison.
- Importer le composant depuis un autre paquet que celui indiqué par la documentation de votre version de WordPress : l’emplacement des composants d’extension de l’éditeur a déjà changé par le passé, et peut changer encore. Vérifiez la version installée.
- Oublier de charger le script uniquement dans l’éditeur :
enqueue_block_editor_assetsest le bon point d’accroche, paswp_enqueue_scripts. - Produire une action destructrice sans confirmation : un rédacteur qui ouvre ce menu par curiosité ne s’attend pas à une modification irréversible.
Quand ne pas utiliser ce composant
Si l’action concerne le document entier (publier, prévisualiser, vérifier un champ), elle a sa place dans la barre latérale ou dans un panneau de pré-publication, pas dans un menu propre au bloc. Si elle modifie l’apparence du bloc et s’utilise souvent, une variation de style ou un contrôle de barre d’outils est plus accessible. Et si elle doit s’exécuter automatiquement, par exemple à la sauvegarde, elle relève d’un filtre ou d’un abonnement au magasin de données, pas d’un clic.
Tester l’intégration
Après compilation, ouvrez l’éditeur, sélectionnez un bloc ciblé, puis cliquez sur les trois points : l’entrée doit figurer dans le menu, avec les actions fournies par l’éditeur. Sélectionnez ensuite plusieurs blocs, dont un non autorisé, et vérifiez qu’elle disparaît. Terminez avec le clavier seul : le menu doit rester navigable à la flèche et l’entrée doit s’activer avec la touche Entrée.
Conclusion
PluginBlockSettingsMenuItem offre une sortie propre aux actions secondaires des blocs. Un seul enregistrement suffit pour tous les blocs visés, le filtre allowedBlocks garde l’entrée pertinente, et la lecture de la sélection dans le magasin rend le code indépendant des détails d’appel. Gardez le menu pour les actions occasionnelles, et laissez la barre d’outils aux gestes fréquents.
