Aller au contenu

useBlockProps

Par défaut, Gutenberg doit créer une enveloppe autour des blocs pour les rendre interactifs dans l’éditeur. Cela peut poser problème pour certains types de blocs, comme les conteneurs ou les colonnes, car leur balisage diffère alors entre l’éditeur et le frontend. Le hook useBlockProps permet de désigner un élément du modèle de bloc comme élément racine, assurant ainsi la parité du balisage entre l’éditeur et le frontend.

Utilisation

Ajoutez simplement l’attribut useBlockProps à l’élément racine de votre bloc.

PHP
<div useBlockProps class="my-class">
  <!--
  This element will be rendered
  as the root element of your block
  in Gutenberg.
  -->
</div>

Blockstudio combine automatiquement les classes et les attributs de l’éditeur (classes d’alignement, etc.) avec ceux définis dans les modèles de bloc. get_block_wrapper_attributes est utilisé en interne à cette fin.

Le filtre blockstudio/blocks/components/use_block_props/render est appliqué à l’enveloppe dans les parcours de rendu du frontend et de l’éditeur. Les classes ajoutées par un thème ou une intégration propre à une instance apparaissent donc sur le canevas de l’éditeur ainsi que dans le balisage enregistré du frontend.

Résultat :

HTML
<div class="my-class wp-block-your-block-name alignright">
</div>

Points à prendre en compte

Blockstudio empêche la navigation par lien dans l’éditeur de blocs, notamment avec target="_blank", les clics avec modificateur, les clics du milieu et l’activation au clavier. Les événements de clic parviennent toujours à Gutenberg, les clics ordinaires sélectionnent donc le bloc. RichText reste modifiable. Cela s’applique avec ou sans useBlockProps, y compris à une ancre utilisée comme élément racine du bloc.

Les liens de l’interface publique et les commandes du menu contextuel du navigateur ne changent pas. Vous n’avez pas besoin de supprimer les liens des modèles ni de conditionner le comportement selon $isEditor.

Élément racine

Comme un modèle de bloc ne peut comporter qu’un seul élément racine, il doit en avoir un seul lorsque vous utilisez useBlockProps. Par exemple, le code suivant ne fonctionnera pas et Gutenberg créera une enveloppe autour du modèle.

PHP
<div useBlockProps>
  First root element.
</div>
<span>
  Second root element.
</span>

useBlockProps ne peut être utilisé qu’une seule fois par modèle de bloc.

Signe @

Blockstudio convertit le modèle de bloc en code React valide dans Gutenberg à l’aide de html-react-parser. La limitation est que le caractère @ ne peut pas être utilisé dans un nom d’attribut HTML.

Des bibliothèques comme Alpine.js utilisent les caractères @ pour définir des directives sur les éléments HTML.

PHP
<button useBlockProps @click="console.log('hi')">
  Click me
</button>

Dans Gutenberg, cet attribut @click sera supprimé de l’élément. (Il fonctionnera toujours sur le frontend, bien sûr.)

Pour contourner ce problème, vous pouvez utiliser la syntaxe alternative fournie par Alpine.js.

PHP
<button useBlockProps x-on:click="console.log('hi')">
  Click me
</button>

Ce qui précède fonctionnera dans Gutenberg et sur le frontend.

Classes du corps du canevas

Lorsque assets.reset.enabled est actif, Blockstudio copie également dans le canevas de l’éditeur les classes assainies renvoyées par le filtre body_class de WordPress. Ainsi, les sélecteurs du thème comme .brand-a .site-card fonctionnent aux deux endroits.

Filtrez la liste finale des classes lorsque l’éditeur a besoin d’un ensemble plus restreint :

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

Ce filtre ne contrôle que les classes copiées dans le canevas de l’éditeur. Il ne modifie pas les classes du corps sur le frontend.