wp.blocks.unregisterBlockType retire un bloc de l’inserteur côté JavaScript

wp.blocks.unregisterBlockType( 'formulaires-pro/carrousel-avis' ) : cette seule ligne, placée dans un script d’éditeur chargé au bon moment, suffit à faire disparaître un bloc de l’inserteur, sans passer par le moindre filtre PHP. Cette approche, moins connue que le filtre allowed_block_types_all traité par ailleurs, se manie côté client, avec l’API JavaScript exposée par le module @wordpress/blocks.

Ce billet se concentre sur le désenregistrement côté JavaScript, utile en particulier quand la restriction ne dépend d’aucun contexte serveur (type de contenu, capacité de l’utilisateur) mais doit simplement s’appliquer partout où l’éditeur se charge. Il ne revient pas en détail sur le filtre PHP, réservé aux restrictions qui dépendent du contexte d’édition.

Pourquoi agir côté JavaScript plutôt que côté PHP

Le filtre allowed_block_types_all agit avant même le chargement du JavaScript de l’éditeur : il convient bien à une restriction qui dépend du type de contenu ou du rôle de l’utilisateur. Désenregistrer un bloc via wp.blocks.unregisterBlockType répond à un besoin différent : retirer un bloc, ou une seule de ses variations, de façon identique partout, en s’appuyant sur l’API native de l’éditeur plutôt que sur une liste blanche construite manuellement côté serveur.

Désenregistrer un bloc entier

( function( wp ) {
    var blocsARetirer = [
        'formulaires-pro/carrousel-avis',
        'formulaires-pro/compteur-visiteurs'
    ];

    wp.domReady( function() {
        blocsARetirer.forEach( function( nomDeBloc ) {
            wp.blocks.unregisterBlockType( nomDeBloc );
        } );
    } );
} )( window.wp );

L’appel à wp.domReady() garantit que le script s’exécute une fois l’éditeur prêt, après que tous les blocs, y compris ceux fournis par des extensions tierces, ont déjà été enregistrés. Appeler unregisterBlockType trop tôt, avant l’enregistrement du bloc visé, échoue silencieusement : la fonction ne retourne rien d’utilisable et le bloc reste disponible.

Retirer seulement une variation, pas le bloc entier

Certains blocs du cœur, comme core/embed ou core/social-link, se déclinent en plusieurs variations qui partagent le même nom de bloc technique. Retirer une seule variation, sans toucher aux autres, se fait avec unregisterBlockVariation, en précisant le nom du bloc parent et le nom exact de la variation :

wp.domReady( function() {
    wp.blocks.unregisterBlockVariation( 'core/embed', 'tiktok' );
    wp.blocks.unregisterBlockVariation( 'core/social-link', 'mastodon' );
} );

Le reste des variations du même bloc, elles, restent disponibles normalement dans l’inserteur : cette granularité fine n’a pas d’équivalent simple côté allowed_block_types_all, qui raisonne au niveau du nom de bloc complet, pas de ses variations internes.

Charger ce script uniquement dans l’éditeur

Ce script ne doit jamais être chargé sur le site public : il n’a de sens que dans l’éditeur de blocs. L’accroche correcte passe par enqueue_block_editor_assets, avec une dépendance explicite sur wp-blocks et wp-dom-ready :

add_action( 'enqueue_block_editor_assets', function() {
    wp_enqueue_script(
        'agence-retrait-blocs',
        get_theme_file_uri( 'assets/js/retrait-blocs.js' ),
        array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
        filemtime( get_theme_file_path( 'assets/js/retrait-blocs.js' ) ),
        true
    );
} );

• La dépendance à wp-blocks garantit que wp.blocks existe déjà au moment de l’exécution du script.
• Le numéro de version basé sur filemtime() évite qu’un navigateur serve une version mise en cache après une modification du script.
• Un script chargé via ce point d’ancrage ne s’exécute que dans l’éditeur, jamais sur les pages publiques du site.

Ce que cette méthode ne permet pas

Le désenregistrement côté JavaScript ne dépend d’aucun contexte serveur : impossible, par cette seule méthode, de retirer un bloc uniquement sur un type de contenu précis ou selon la capacité de l’utilisateur connecté, sans ajouter une condition supplémentaire côté PHP pour décider de charger, ou non, le script d’éditeur. Quand la restriction doit varier selon ce type de contexte, le filtre allowed_block_types_all, traité par ailleurs, reste la voie la plus directe.

Sur nos projets, la règle qui tranche entre les deux approches est simple : une restriction identique partout se code en JavaScript, une restriction qui dépend du contexte se code en PHP.

En résumé

Retirer un bloc entier ou une seule de ses variations depuis un script d’éditeur, avec unregisterBlockType et unregisterBlockVariation, offre une granularité que le filtre PHP n’atteint pas toujours, au prix d’un chargement de script à bien cibler sur l’éditeur uniquement. Les deux méthodes se complètent plus qu’elles ne se concurrencent, selon que la restriction dépend ou non du contexte d’édition.