# Les attributs de blocs Gutenberg : type, source et valeur par défaut expliqués

> html, attribute, query, meta… chaque source d'attribut a un rôle précis. Voici comment les choisir sans se tromper, exemples de code à l'appui.

- Auteur : Clément Hadrot
- Publié le : 2020-05-14
- Mis à jour le : 2020-05-14
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/attributs-blocs-gutenberg-type-source-valeur-par-defaut/

## L’essentiel

- Comprendre la différence entre attribut parsé et attribut sourcé
- Choisir entre html, attribute, query et meta selon le besoin
- Éviter les pièges classiques de valeur par défaut

Quand on débute avec l'API des blocs, on a vite envie d'entasser toutes ses données dans un unique attribut de type `string`, quitte à parser soi-même le HTML plus tard. C'est une mauvaise idée : Gutenberg dispose d'un système d'attributs bien plus fin, capable d'extraire automatiquement une valeur depuis le balisage sauvegardé, sans qu'on ait à écrire la moindre ligne de parsing.

Cet article détaille chaque source d'attribut disponible dans `registerBlockType` : `html`, `attribute`, `query`, `text` (une variante d'`html` peu documentée), et `meta` pour lier un attribut à un champ personnalisé. On verra aussi pourquoi le choix du type et de la valeur par défaut n'est jamais un détail anodin.

## Comment fonctionne le sourcing d'attributs

Quand vous déclarez un bloc, chaque entrée de l'objet `attributes` peut préciser une `source`. Sans `source`, Gutenberg stocke la valeur directement dans le commentaire HTML délimiteur du bloc (par exemple `<!-- wp:wpmoderne/citation {"auteur":"Victor Hugo"} /-->`). Avec une `source`, en revanche, la valeur est **extraite du HTML sauvegardé** par `save()`, au moment où l'article est rechargé dans l'éditeur.

Cette distinction change tout : un attribut sans `source` vit dans les métadonnées JSON du commentaire de bloc (invisible en front-end classique), tandis qu'un attribut avec `source` vit dans le balisage HTML lui-même, ce qui le rend lisible même si l'on affiche l'article sans passer par WordPress.

## La source « html » : le cas le plus courant

C'est la source que l'on utilise pour tout contenu texte enrichi (avec du gras, des liens, etc.), généralement de pair avec le composant `RichText`. Elle prend une option `selector` qui cible l'élément dont on veut récupérer le `innerHTML`.

```
attributes: {
    citation: {
        type: 'string',
        source: 'html',
        selector: 'blockquote',
    },
    auteur: {
        type: 'string',
        source: 'html',
        selector: 'cite',
        default: '',
    },
},
```

> L'essentiel à retenir : Comprendre la différence entre attribut parsé et attribut sourcé ; Choisir entre html, attribute, query et meta selon le besoin ; Éviter les pièges classiques de valeur par défaut

Dans `save()`, il faut impérativement que le HTML produit contienne bien un `<blockquote>` et un `<cite>`, faute de quoi l'extraction échouera silencieusement et l'attribut reviendra à sa valeur par défaut à la réouverture. C'est l'un des pièges les plus fréquents : modifier la structure de `save()` sans mettre à jour le `selector` correspondant.

## La source « attribute » : cibler un attribut HTML précis

Utile quand la donnée n'est pas du texte mais la valeur d'un attribut HTML — une URL d'image, un `alt`, une classe CSS. On combine `selector` et `attribute` :

```
attributes: {
    url: {
        type: 'string',
        source: 'attribute',
        selector: 'img',
        attribute: 'src',
    },
    alt: {
        type: 'string',
        source: 'attribute',
        selector: 'img',
        attribute: 'alt',
        default: '',
    },
},
```

C'est exactement la mécanique employée par le bloc Image natif pour récupérer l'URL et le texte alternatif depuis la balise `<img>` sauvegardée. Sans cette source, il faudrait dupliquer l'URL dans les métadonnées JSON du bloc en plus du HTML, ce qui crée deux sources de vérité désynchronisables.

## La source « query » : extraire une liste d'éléments

Quand un bloc contient plusieurs occurrences d'un même sous-élément — les images d'une galerie, les lignes d'une liste —, la source `query` permet de récupérer un tableau d'objets, chacun construit à partir d'un sous-ensemble de sources.

```
attributes: {
    images: {
        type: 'array',
        source: 'query',
        selector: 'figure',
        query: {
            url: {
                type: 'string',
                source: 'attribute',
                selector: 'img',
                attribute: 'src',
            },
            legende: {
                type: 'string',
                source: 'html',
                selector: 'figcaption',
            },
        },
        default: [],
    },
},
```

Le `selector` de premier niveau cible chaque bloc répété (ici, chaque `<figure>`), et l'objet `query` décrit, pour chacun, comment extraire ses propres sous-valeurs. C'est la technique qu'utilise en interne le bloc Galerie natif.

## La source « meta » : lier un attribut à un champ personnalisé

Contrairement aux précédentes, la source `meta` ne lit rien dans le HTML du bloc : elle relie l'attribut à un champ personnalisé (*post meta*) de l'article, enregistré côté PHP avec `register_meta()`. C'est pratique pour partager une donnée entre plusieurs blocs, ou pour la rendre accessible à un thème classique en dehors du contenu du bloc.

```
<?php
function wpmoderne_register_meta() {
    register_post_meta( 'post', 'wpmoderne_note_lecture', array(
        'show_in_rest' => true,
        'single'       => true,
        'type'         => 'string',
        'default'      => '',
    ) );
}
add_action( 'init', 'wpmoderne_register_meta' );
```

```
attributes: {
    noteLecture: {
        type: 'string',
        source: 'meta',
        meta: 'wpmoderne_note_lecture',
    },
},
```

Attention : pour que le bloc puisse lire et écrire ce champ, il faut aussi que le composant appelle `withSelect`/`withDispatch` (ou le hook `useSelect`/`useDispatch` côté `@wordpress/data`) pour synchroniser l'attribut avec les métadonnées de l'article, l'attribut `source: meta` seul ne suffisant pas à créer cette liaison bidirectionnelle dans l'éditeur.

### Sans source : le stockage dans le commentaire de bloc

Pour tout ce qui relève d'un réglage d'interface — une couleur choisie dans un menu déroulant, une case à cocher, un nombre de colonnes —, on omet simplement `source`. La valeur part directement dans le JSON du commentaire délimiteur :

```
attributes: {
    colonnes: {
        type: 'number',
        default: 3,
    },
    alignementCentre: {
        type: 'boolean',
        default: false,
    },
},
```

## Bien choisir le type et la valeur par défaut

Le champ `type` suit le vocabulaire JSON Schema : `string`, `number`, `boolean`, `array`, `object`. Gutenberg s'en sert pour valider et caster la valeur extraite. Un piège classique : déclarer `type: 'number'` pour un attribut sourcé en `attribute` depuis un `data-*`, alors que tous les attributs HTML sont des chaînes de caractères — sans coercition explicite, on récupère parfois une chaîne là où l'on attend un nombre.

Quant à `default`, elle n'est utilisée que lorsque la source ne trouve rien à extraire (bloc fraîchement inséré, ou sélecteur introuvable). Ne comptez jamais sur elle pour « réinitialiser » un attribut existant : une fois que du HTML valide est présent, la valeur par défaut est ignorée au profit de la valeur extraite.

| Source | Origine de la donnée | Cas d'usage typique |
| --- | --- | --- |
| Aucune | JSON du commentaire de bloc | Réglages d'interface (couleur, nombre, booléen) |
| `html` | `innerHTML` d'un élément | Texte enrichi avec `RichText` |
| `attribute` | Valeur d'un attribut HTML | URL d'image, texte alternatif, classe CSS |
| `query` | Liste d'objets extraits par répétition | Galerie d'images, liste de témoignages |
| `meta` | Champ personnalisé de l'article | Donnée partagée entre plusieurs blocs |

> Testez toujours vos sources d'attributs en rechargeant la page après publication, pas seulement en prévisualisation : certaines erreurs d'extraction ne se révèlent qu'au passage par le HTML réellement enregistré en base.

## En résumé

Le choix d'une source d'attribut n'est jamais neutre : il détermine où vit la donnée (JSON du bloc, HTML sauvegardé, ou métadonnées de l'article), comment elle survit à une modification manuelle du contenu, et si elle reste lisible en dehors de l'éditeur. Une bonne règle de départ : utilisez `html` et `attribute` pour tout ce qui doit rester visible dans le balisage final, réservez l'absence de `source` aux réglages purement éditoriaux, et n'utilisez `meta` que lorsque la donnée doit vraiment vivre au niveau de l'article plutôt qu'au niveau du bloc.