Construire des pages avec des blocs

Sur cette page

Un champ blocks stocke une composition de page ordonnée. Chaque élément consigne un type de bloc, une version de schéma conservée, une clé stable et les champs déclarés par cette version. Les éditeurs ajoutent et réordonnent les blocs dans l’éditeur de contenu. La route Astro associe chaque type de bloc à un composant.

Définir les types de blocs

Définissez les types de blocs avant le champ de collection qui les utilise. Un seed conserve chaque version numérotée ainsi que le pointeur currentVersion actif.

Le seed suivant définit les blocs Hero et Feature grid, puis les met à disposition dans un champ layout de Pages :

{
  "$schema": "https://emdashcms.com/seed.schema.json",
  "version": "1",
  "blockTypes": [
    {
      "slug": "hero",
      "label": "Hero",
      "description": "A heading, body text and an image",
      "icon": "sparkle",
      "category": "Layout",
      "currentVersion": 1,
      "versions": [
        {
          "version": 1,
          "fields": [
            { "slug": "heading", "label": "Heading", "type": "string", "required": true },
            { "slug": "body", "label": "Body", "type": "portableText" },
            { "slug": "image", "label": "Image", "type": "image" },
            { "slug": "link_label", "label": "Link label", "type": "string" },
            { "slug": "link_url", "label": "Link URL", "type": "url" }
          ]
        }
      ]
    },
    {
      "slug": "feature_grid",
      "label": "Feature grid",
      "description": "A heading and a grid of features",
      "icon": "squares-four",
      "category": "Layout",
      "currentVersion": 1,
      "versions": [
        {
          "version": 1,
          "fields": [
            { "slug": "heading", "label": "Heading", "type": "string" },
            {
              "slug": "items",
              "label": "Items",
              "type": "repeater",
              "validation": {
                "subFields": [
                  { "slug": "title", "label": "Title", "type": "string", "required": true },
                  { "slug": "description", "label": "Description", "type": "text" }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "collections": [
    {
      "slug": "pages",
      "label": "Pages",
      "fields": [
        { "slug": "title", "label": "Title", "type": "string", "required": true },
        {
          "slug": "layout",
          "label": "Layout",
          "type": "blocks",
          "validation": {
            "allowedTypes": ["hero", "feature_grid"],
            "maxItems": 20
          }
        }
      ]
    }
  ]
}

Le sélecteur de blocs liste les types de bloc dans l’ordre de allowedTypes, regroupés par category, et affiche la description et l’icon de chaque type. Définissez icon sur le nom d’une icône Phosphor, comme sparkle ou chart-bar ; les éditeurs la voient aussi sur chaque bloc dans l’éditeur de contenu. Un type de bloc sans icône, ou dont le nom ne correspond à aucune icône Phosphor, affiche une icône de bloc générique.

Si vous retirez plus tard un type autorisé, EmDash le déplace vers la liste retiredTypes, gérée par le serveur. Les blocs existants restent modifiables, mais les éditeurs ne peuvent ni ajouter ni dupliquer ce type.

Nommer les champs pour la mise en page de l’éditeur

Un bloc ouvert dans l’éditeur de contenu affiche d’abord son contenu : texte, texte enrichi, photos et listes, chacun sous son libellé. Les réglages suivent sous forme de lignes avec le libellé à côté de la valeur, puis une ligne Advanced. L’éditeur place chaque champ selon son type et son slug, et non selon son libellé, et affiche chaque libellé tel qu’il est écrit. Ces conventions modifient l’emplacement d’un champ :

  • Champs de lien. Un champ url, ou un champ string dont le slug se termine par _url, _link ou _href, obtient une ligne de réglages.
  • Boutons. Un champ string nommé {base}_label, {base}_text ou {base} partage une ligne avec un champ de lien nommé {base}_url, {base}_link ou {base}_href. La ligne reprend le libellé du champ de texte. Dans le Hero ci-dessus, link_label et link_url partagent une ligne intitulée « Link label ».
  • Légendes. Un champ string nommé {image}_caption se place sous le champ image nommé {image}, par exemple photo_caption sous photo.
  • ID de section. Un champ nommé anchor_id va dans la ligne Advanced.
  • Titre principal. Le premier champ string ou text dont le slug contient le mot headline, heading, title ou statement est affiché en plus grand, comme titre principal du bloc. Un champ dont le slug contient le mot label, eyebrow, kicker ou tag n’est jamais le titre principal. Les slugs sont découpés en mots aux tirets bas ; section_heading compte donc, mais pas subheadline. Quand aucun champ ne correspond, le premier champ string ou text du bloc est le titre principal, sauf si son slug contient l’un de ces mots exclus.

Un champ repeater à l’intérieur d’un bloc prend sa forme à partir de ses sous-champs :

  • Liste à saisie rapide. Une liste avec exactement un sous-champ, de type string ou url, affiche chaque élément sous forme de ligne à puce. Entrée ajoute une ligne, et coller plusieurs lignes ajoute un élément par ligne. Une liste de noms de clients correspond à cette forme.
  • Tableau. Une liste avec jusqu’à trois sous-champs, chacun de type string, url, number, integer, select ou image, et au plus une image, affiche une ligne par élément et une colonne par sous-champ. Une liste de statistiques avec une valeur et un libellé correspond à cette forme.
  • Éléments dépliables. Toute autre liste affiche chaque élément sous forme de ligne qui s’ouvre pour modifier ses sous-champs. Un élément ouvert dispose ses sous-champs selon les règles ci-dessus, sauf qu’aucun sous-champ n’est affiché comme titre principal ni placé dans une ligne Advanced, qu’une photo obtient une ligne de réglages et que {image}_caption est un champ de texte ordinaire.

Le titre d’un élément est son premier sous-champ string qui n’est ni un champ de lien ni le texte d’un bouton, ou sinon son premier sous-champ text. Un élément fermé affiche son titre, suivi d’au plus deux de ses autres valeurs string. Quand elles sont toutes vides, il affiche à la place le début de sa première autre valeur text. Dans le Feature grid ci-dessus, items s’affiche sous forme d’éléments dépliables intitulés par title. Ajouter un quatrième sous-champ, ou un sous-champ text, au type de bloc d’un tableau transforme la liste en éléments dépliables.

Ces règles sont des indications de mise en page au mieux et peuvent changer dans une version ultérieure. Elles n’affectent que la façon dont l’éditeur organise le formulaire, et un champ qui ne correspond à aucune d’elles obtient sa propre ligne.

Créer les composants Astro

Chaque composant reçoit value, index et blockKey. La valeur inclut _type, _version et _key, de sorte qu’un composant puisse restreindre les versions conservées lorsque le schéma de son bloc évolue.

Le composant Hero lit chaque valeur affichée à partir du bloc stocké :

---
import { sanitizeHref } from "emdash";
import { Image, PortableText, type BlockComponentProps } from "emdash/ui";
import type { PageLayoutBlock } from "../../../emdash-env";

type HeroBlock = Extract<PageLayoutBlock, { _type: "hero" }>;
type Props = BlockComponentProps<HeroBlock>;

const { value } = Astro.props;
---

<section class="hero">
  <div>
    <h1>{value.heading}</h1>
    {value.body && <PortableText value={value.body} />}
    {value.link_url && <a href={sanitizeHref(value.link_url)}>{value.link_label}</a>}
  </div>
  {value.image && <Image image={value.image} />}
</section>

Créez un composant pour chaque type autorisé. Le composant contrôle le balisage et le style ; la valeur du bloc fournit le contenu et les médias.

Afficher la composition

Utilisez defineBlockComponents pour exiger un composant pour chaque _type de l’union de champs générée. Passez cette table à <Blocks> dans la route de la page.

---
import { decodeSlug, getEmDashEntry } from "emdash";
import { Blocks, defineBlockComponents } from "emdash/ui";
import type { PageLayoutBlock } from "../../../emdash-env";
import FeatureGrid from "../../components/blocks/FeatureGrid.astro";
import Hero from "../../components/blocks/Hero.astro";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: page, cacheHint } = await getEmDashEntry("pages", slug);
if (!page) return Astro.rewrite("/404");
Astro.cache.set(cacheHint);

const components = defineBlockComponents<PageLayoutBlock>({
  hero: Hero,
  feature_grid: FeatureGrid,
});
---

<Blocks value={page.data.layout} components={components} />

<Blocks> n’exécute aucune requête de contenu, de schéma, de médias ou réseau. Il affiche le tableau fourni dans l’ordre stocké. Un composant de bloc peut effectuer une requête applicative explicite lorsqu’il a besoin d’autres données.

Gérer un composant manquant

Pendant le développement, un type non associé produit un espace réservé visible et un avertissement dans la console. L’espace réservé indique le _type, mais n’affiche pas la valeur du bloc stocké.

En production, un type non associé affiche le composant fallback s’il est fourni. Sinon, il n’affiche rien :

---
import MissingBlock from "../../components/blocks/MissingBlock.astro";
---

<Blocks value={page.data.layout} components={components} fallback={MissingBlock} />

Publiez la prise en charge du moteur de rendu avant d’activer un type de bloc utilisé par le contenu de production.

Modifier le schéma d’un bloc

Les changements compatibles modifient la version active. Ajouter un champ facultatif, ajouter une valeur par défaut ou assouplir la validation conserve le même numéro de version. Les blocs stockés reçoivent les valeurs par défaut la prochaine fois qu’ils sont écrits.

Un changement incompatible crée une version inactive. Supprimer un champ, changer le type d’un champ, ajouter un champ obligatoire ou durcir la validation sont des changements incompatibles.

  1. Créez la version incompatible via l’API de schéma ou MCP. Gardez-la inactive.

  2. Mettez à jour le moteur de rendu pour qu’il gère à la fois la version conservée et la nouvelle version. Déployez le moteur de rendu.

  3. Activez la nouvelle version. Les nouveaux blocs l’utilisent après l’activation.

  4. Migrez explicitement les blocs stockés avec migrateBlocks: true. Conservez le _key de chaque bloc tout en modifiant _version et ses champs propres à la version.

Les anciennes versions restent disponibles pour les révisions, les brouillons, le suivi des médias et le contenu stocké. Les types de blocs et les versions conservées n’ont pas d’opération de suppression définitive.

Champs imbriqués pris en charge

Les définitions de blocs prennent en charge string, text, url, number, integer, boolean, datetime, select, multiSelect, portableText, image, file et repeater.

Les références, le JSON, les slugs, les blocs imbriqués, les widgets personnalisés, les index physiques, l’unicité et la localisation par sous-champ ne sont pas pris en charge dans une définition de bloc. Un champ blocks ne peut pas lui-même être obligatoire, unique, interrogeable, indexé, ni se voir attribuer un widget de champ personnalisé.

Pour les règles exactes de validation des champs et des valeurs stockées, consultez la référence du champ blocks. Pour le comportement des conflits et de l’export des seeds, consultez Fichiers seed.