Creare pagine con i blocchi

In questa pagina

Un campo blocks memorizza una composizione di pagina ordinata. Ogni elemento registra un tipo di blocco, una versione dello schema conservata, una chiave stabile e i campi dichiarati da quella versione. Gli editor aggiungono e riordinano i blocchi nell’editor dei contenuti. La route Astro associa ogni tipo di blocco a un componente.

Definire i tipi di blocco

Definisci i tipi di blocco prima del campo della collezione che li usa. Un seed conserva ogni versione numerata e il puntatore currentVersion attivo.

Il seed seguente definisce i blocchi Hero e Feature grid, quindi li rende disponibili in un campo layout di 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
          }
        }
      ]
    }
  ]
}

Il selettore dei blocchi elenca i tipi di blocco nell’ordine di allowedTypes, raggruppati per category, e mostra la description e l’icon di ciascun tipo. Imposta icon sul nome di un’icona Phosphor, come sparkle o chart-bar; gli editor la vedono anche su ogni blocco nell’editor dei contenuti. Un tipo di blocco senza icona, o con un nome che non corrisponde a un’icona Phosphor, mostra un’icona di blocco generica.

Se in seguito rimuovi un tipo consentito, EmDash lo sposta nell’elenco retiredTypes, gestito dal server. I blocchi esistenti restano modificabili, ma gli editor non possono aggiungere né duplicare quel tipo.

Assegnare i nomi ai campi per il layout dell’editor

Un blocco aperto nell’editor dei contenuti mostra prima il suo contenuto: testo, rich text, foto ed elenchi, ciascuno sotto la propria etichetta. Seguono le impostazioni come righe con l’etichetta accanto al valore, poi una riga Advanced. L’editor colloca ogni campo in base al suo tipo e al suo slug, non alla sua etichetta, e mostra ogni etichetta così com’è scritta. Queste convenzioni cambiano la posizione di un campo:

  • Campi link. Un campo url, o un campo string il cui slug termina con _url, _link o _href, ottiene una riga di impostazioni.
  • Pulsanti. Un campo string chiamato {base}_label, {base}_text o {base} condivide una riga con un campo link chiamato {base}_url, {base}_link o {base}_href. La riga prende l’etichetta del campo di testo. Nell’Hero qui sopra, link_label e link_url condividono una riga con l’etichetta «Link label».
  • Didascalie. Un campo string chiamato {image}_caption si trova sotto il campo image chiamato {image}, come photo_caption sotto photo.
  • ID della sezione. Un campo chiamato anchor_id va nella riga Advanced.
  • Titolo principale. Il primo campo string o text il cui slug contiene la parola headline, heading, title o statement viene disegnato più grande, come titolo principale del blocco. Un campo il cui slug contiene la parola label, eyebrow, kicker o tag non è mai il titolo principale. Gli slug vengono divisi in parole ai trattini bassi, quindi section_heading conta e subheadline no. Quando nessun campo corrisponde, il primo campo string o text del blocco è il titolo principale, a meno che il suo slug contenga una di quelle parole escluse.

Un campo repeater all’interno di un blocco prende la sua forma dai suoi sottocampi:

  • Elenco a digitazione rapida. Un elenco con esattamente un sottocampo, di tipo string o url, mostra ogni elemento come riga con elenco puntato. Invio aggiunge una riga, e incollando più righe si aggiunge un elemento per riga. Un elenco di nomi di clienti rientra in questa forma.
  • Tabella. Un elenco con fino a tre sottocampi, ciascuno di tipo string, url, number, integer, select o image, e al massimo una image, mostra una riga per elemento e una colonna per sottocampo. Un elenco di statistiche con un valore e un’etichetta rientra in questa forma.
  • Elementi espandibili. Ogni altro elenco mostra ogni elemento come riga che si apre per modificarne i sottocampi. Un elemento aperto dispone i suoi sottocampi con le regole precedenti, tranne che nessun sottocampo viene disegnato come titolo principale né va in una riga Advanced, una foto ottiene una riga di impostazioni e {image}_caption è un normale campo di testo.

Il titolo di un elemento è il suo primo sottocampo string che non sia né un campo link né il testo di un pulsante, oppure il suo primo sottocampo text. Un elemento chiuso mostra il suo titolo, seguito da al massimo due dei suoi altri valori string. Quando sono tutti vuoti, mostra invece l’inizio del suo primo altro valore text. Nel Feature grid qui sopra, items viene mostrato come elementi espandibili intitolati da title. Aggiungere un quarto sottocampo, o un sottocampo text, al tipo di blocco di una tabella trasforma l’elenco in elementi espandibili.

Queste regole sono suggerimenti di layout al meglio delle possibilità e possono cambiare in una release successiva. Influiscono solo sul modo in cui l’editor dispone il modulo, e un campo che non corrisponde a nessuna di esse ottiene una riga propria.

Creare i componenti Astro

Ogni componente riceve value, index e blockKey. Il valore include _type, _version e _key, quindi un componente può restringere le versioni conservate quando lo schema del suo blocco evolve.

Il componente Hero legge ogni valore visualizzato dal blocco memorizzato:

---
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>

Crea un componente per ogni tipo consentito. Il componente controlla il markup e lo stile; il valore del blocco fornisce contenuti e media.

Renderizzare la composizione

Usa defineBlockComponents per richiedere un componente per ogni _type dell’unione di campi generata. Passa quella mappa a <Blocks> nella route della pagina.

---
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> non esegue query di contenuto, schema, media o rete. Renderizza l’array fornito nell’ordine memorizzato. Un componente di blocco può eseguire una query applicativa esplicita quando ha bisogno di altri dati.

Gestire un componente mancante

Durante lo sviluppo, un tipo non mappato produce un segnaposto visibile e un avviso nella console. Il segnaposto riporta il nome del _type ma non stampa il valore del blocco memorizzato.

In produzione, un tipo non mappato renderizza il componente fallback se fornito. Altrimenti non produce alcun output:

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

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

Rilascia il supporto del renderer prima di abilitare o attivare un tipo di blocco usato dai contenuti di produzione.

Modificare lo schema di un blocco

Le modifiche compatibili emendano la versione attiva. Aggiungere un campo facoltativo, aggiungere un valore predefinito o allentare la validazione mantiene lo stesso numero di versione. I blocchi memorizzati ricevono i valori predefiniti la prossima volta che vengono scritti.

Una modifica incompatibile crea una versione inattiva. Rimuovere un campo, cambiare il tipo di un campo, aggiungere un campo obbligatorio o restringere la validazione sono modifiche incompatibili.

  1. Crea la versione incompatibile tramite l’API dello schema o MCP. Mantienila inattiva.

  2. Aggiorna il renderer in modo che gestisca sia la versione conservata sia quella nuova. Distribuisci il renderer.

  3. Attiva la nuova versione. I nuovi blocchi la usano dopo l’attivazione.

  4. Migra esplicitamente i blocchi memorizzati con migrateBlocks: true. Conserva il _key di ogni blocco mentre modifichi _version e i suoi campi specifici della versione.

Le vecchie versioni restano disponibili per revisioni, bozze, tracciamento dei media e contenuti memorizzati. I tipi di blocco e le versioni conservate non hanno un’operazione di eliminazione definitiva.

Campi annidati supportati

Le definizioni dei blocchi supportano string, text, url, number, integer, boolean, datetime, select, multiSelect, portableText, image, file e repeater.

Riferimenti, JSON, slug, blocchi annidati, widget personalizzati, indici fisici, unicità e localizzazione per sottocampo non sono supportati all’interno di una definizione di blocco. Un campo blocks non può essere obbligatorio, univoco, ricercabile, indicizzato né avere un widget di campo personalizzato.

Per le regole esatte sulla validazione dei campi e sui valori memorizzati, consulta il riferimento del campo blocks. Per il comportamento dei conflitti e dell’esportazione dei seed, consulta File seed.