block.json

Définition : Le fichier block.json décrit les métadonnées d’un bloc WordPress : identité, attributs, supports et chemins de ressources. Il sert de référence commune à l’enregistrement côté serveur et côté éditeur.

Comprendre et utiliser

À quoi cela sert ?

Il réduit les divergences entre le PHP et le JavaScript. WordPress peut lire ses propriétés pour enregistrer le type, charger les ressources pertinentes et exposer des informations cohérentes aux outils.

Comment cela fonctionne ?

Le champ name suit la forme namespace/nom. Les propriétés editorScript, script, style ou render désignent des ressources ; apiVersion décrit le contrat de l’API et non la version du plugin.

Dans quel contexte l’utiliser ?

Adopter block.json pour un nouveau bloc maintenable, notamment lorsqu’il doit être publié sur WordPress.org ou partager ses assets entre plusieurs écrans.

Cas concret : ATOOLPHA

Dans une extension ATOOLPHA, créer un bloc Note et réserver un dossier contenant block.json, le code compilé de l’éditeur et, si nécessaire, un fichier de rendu PHP.

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.

{"$schema":"https://schemas.wp.org/trunk/block.json","apiVersion":3,"name":"atoolpha/note","title":"Note ATOOLPHA","category":"text","attributes":{"message":{"type":"string","default":""}},"editorScript":"file:./index.js"}

Décryptage de l’exemple

La référence file:./index.js suppose qu’un fichier compilé existe à côté du JSON. Le schéma $schema permet aux éditeurs compatibles de proposer une validation et une assistance.

Résultat attendu

Après compilation et registration par le serveur, WordPress connaît les propriétés déclarées et peut charger le script de l’éditeur.

Atelier pratique de vérification

Dans un dossier de démonstration, créer block.json puis déposer volontairement une mauvaise valeur de name. Corriger l’erreur, construire les assets et vérifier le résultat de register_block_type(). Renommer ensuite le script annoncé dans editorScript pour observer pourquoi le registre du bloc peut être présent alors que son interface échoue.

Précautions et limites

Ne pas pointer vers src/index.js non compilé si le code emploie JSX ou des imports ES non pris en charge tels quels par votre déploiement. Générer les assets via l’outillage adapté.

Contrôle avant intégration dans un plugin

Contrôler que le fichier est inclus dans le paquet distribué, que tous les chemins file: sont exacts et que les traductions prévues sont disponibles. Mettre les ressources compilées sous contrôle de version avec le manifeste.

À ne pas confondre

block.json est un manifeste de bloc ; ce n’est ni theme.json, qui configure notamment les styles du thème, ni le fichier package.json de l’outillage JavaScript.

Diagnostic et dépannage avancés

En cas de bloc absent, contrôler le chemin réellement enregistré dans register_block_type(), la présence du build/index.js et la console du navigateur.