apiVersion (Block API)

Définition : apiVersion est la propriété des métadonnées qui indique la version du contrat Block API utilisée par un bloc. Elle influence notamment les conventions d’enveloppe, les supports et l’intégration de l’éditeur.

Comprendre et utiliser

À quoi cela sert ?

Elle guide WordPress pour interpréter les déclarations du bloc selon un contrat précis. Cela facilite les migrations et l’adoption progressive des évolutions de l’éditeur.

Comment cela fonctionne ?

Les versions 1, 2 et 3 ne correspondent pas aux numéros de version de WordPress. La version 3, introduite avec WordPress 6.3, prend en compte l’environnement d’édition en iframe.

Dans quel contexte l’utiliser ?

Pour un bloc neuf, vérifier la documentation de la version cible et utiliser la version de Block API recommandée. Après migration, tester l’édition et les styles dans les environnements concernés.

Cas concret : ATOOLPHA

ATOOLPHA prépare un bloc intégré à l’éditeur récent : son manifeste déclare apiVersion 3 et les fichiers de style adaptés à ce mode d’édition.

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.

{"apiVersion":3,"name":"atoolpha/notice","title":"Notice","category":"text"}

Décryptage de l’exemple

La propriété numérique apiVersion signale le contrat de compatibilité du type. Ce fragment ne suffit pas à lui seul pour rendre un bloc ; il représente un manifeste minimal d’étude.

Résultat attendu

WordPress peut appliquer les conventions correspondant à cette version lorsqu’il enregistre et instancie ce type sur une installation compatible.

Atelier pratique de vérification

Créer un bloc minimal en apiVersion 3 et vérifier son comportement dans l’éditeur de la version WordPress disponible. Comparer les classes d’enveloppe et les styles chargés dans l’espace éditorial. Noter les différences liées à l’iframe et éviter de confondre numéro d’API, version de WordPress et version du plugin.

Précautions et limites

Ne pas incrémenter apiVersion comme une version métier de plugin. Une migration doit inclure des tests de styles et de DOM d’édition, notamment lorsque l’éditeur utilise une iframe.

Contrôle avant intégration dans un plugin

Consigner apiVersion séparément de la version du plugin dans le registre technique. Vérifier l’affichage des anciens blocs et les styles sous iframe avant toute migration d’API sur un site existant.

À ne pas confondre

apiVersion règle le contrat Block API ; version dans block.json peut décrire la version propre au bloc ; les versions du Core sont encore distinctes.

Diagnostic et dépannage avancés

En cas de styles absents uniquement dans l’éditeur, contrôler l’isolation iframe et la déclaration des styles d’éditeur au lieu de rétrograder apiVersion sans diagnostic.