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 campostringil cui slug termina con_url,_linko_href, ottiene una riga di impostazioni. - Pulsanti. Un campo
stringchiamato{base}_label,{base}_texto{base}condivide una riga con un campo link chiamato{base}_url,{base}_linko{base}_href. La riga prende l’etichetta del campo di testo. Nell’Hero qui sopra,link_labelelink_urlcondividono una riga con l’etichetta «Link label». - Didascalie. Un campo
stringchiamato{image}_captionsi trova sotto il campoimagechiamato{image}, comephoto_captionsottophoto. - ID della sezione. Un campo chiamato
anchor_idva nella riga Advanced. - Titolo principale. Il primo campo
stringotextil 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, quindisection_headingconta esubheadlineno. Quando nessun campo corrisponde, il primo campostringotextdel 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
stringourl, 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,selectoimage, e al massimo unaimage, 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.
-
Crea la versione incompatibile tramite l’API dello schema o MCP. Mantienila inattiva.
-
Aggiorna il renderer in modo che gestisca sia la versione conservata sia quella nuova. Distribuisci il renderer.
-
Attiva la nuova versione. I nuovi blocchi la usano dopo l’attivazione.
-
Migra esplicitamente i blocchi memorizzati con
migrateBlocks: true. Conserva il_keydi ogni blocco mentre modifichi_versione 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.