Block API

Définition : La Block API regroupe les interfaces de WordPress servant à déclarer, configurer, éditer et afficher des blocs. Elle organise les attributs, les rendus, les supports et la compatibilité.

Comprendre et utiliser

À quoi cela sert ?

Elle fixe un contrat technique entre le bloc, l’éditeur et le serveur. Ce contrat permet à un plugin de proposer des contrôles cohérents avec l’interface WordPress sans réinventer un éditeur.

Comment cela fonctionne ?

Les métadonnées définissent l’identité et les capacités ; edit traite l’expérience d’édition ; save ou le rendu serveur définissent la sortie. D’autres API gèrent le contexte, les transformations et les variations.

Dans quel contexte l’utiliser ?

Utiliser les API documentées pour maintenir une extension sur plusieurs versions. Les mécanismes du paquet Gutenberg non stabilisés ne doivent pas être considérés comme des garanties de compatibilité.

Cas concret : ATOOLPHA

Un plugin peut exposer un bloc « Alerte » avec une couleur configurable, une zone de texte et un rendu cohérent sur la page publique.

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/alert","title":"Alerte","category":"text","supports":{"color":{"text":true,"background":true}}}

Décryptage de l’exemple

Les métadonnées associent une identité, une version d’API et des supports d’interface. L’exemple reste volontairement une définition partielle : il faut fournir les fichiers d’édition et de rendu.

Résultat attendu

L’éditeur peut exposer les options demandées après enregistrement du type et chargement de son implémentation, selon les capacités activées du thème.

Atelier pratique de vérification

Prendre un bloc simple et documenter séparément son identité, son interface edit et sa sortie save. Modifier une seule propriété supports, recharger l’éditeur et observer les contrôles ajoutés. Vérifier ensuite si la propriété influencera le balisage sauvegardé. Noter quelles versions du Core ont été utilisées pendant l’essai.

Précautions et limites

Vérifier la compatibilité réelle de chaque propriété de Block API avec le WordPress cible ; éviter de copier des exemples liés à une version de développement sans contrôler les prérequis.

Contrôle avant intégration dans un plugin

Conserver la version de Core utilisée pour tester les supports activés. Vérifier que les propriétés de l’enveloppe sont propagées au rendu et ne pas promouvoir une API expérimentale comme stable sans référence documentaire.

À ne pas confondre

La Block API documente les contrats de blocs ; la REST API expose des ressources HTTP et ne remplace pas le cycle d’édition des blocs.

Diagnostic et dépannage avancés

Lorsqu’une option de bloc n’apparaît pas, vérifier simultanément les propriétés supports, theme.json et l’autorisation de l’éditeur avant de modifier le JavaScript.