Crie páginas com blocos

Nesta página

Um campo blocks armazena uma composição de página ordenada. Cada item registra um tipo de bloco, uma versão de esquema retida, uma chave estável e os campos declarados por essa versão. Os editores adicionam e reordenam blocos no editor de conteúdo. A rota do Astro mapeia cada tipo de bloco para um componente.

Defina os tipos de bloco

Defina os tipos de bloco antes do campo de coleção que os usa. Um seed preserva cada versão numerada e o ponteiro currentVersion ativo.

O seed a seguir define os blocos Hero e Feature grid e depois os disponibiliza em um campo 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
          }
        }
      ]
    }
  ]
}

O seletor de blocos lista os tipos de bloco na ordem de allowedTypes, agrupados por category, e mostra a description e o icon de cada tipo. Defina icon como o nome de um ícone do Phosphor, como sparkle ou chart-bar; os editores também o veem em cada bloco no editor de conteúdo. Um tipo de bloco sem ícone, ou com um nome que não corresponde a um ícone do Phosphor, mostra um ícone de bloco genérico.

Se você remover um tipo permitido mais tarde, o EmDash o move para a lista retiredTypes, gerenciada pelo servidor. Os blocos existentes continuam editáveis, mas os editores não podem adicionar nem duplicar esse tipo.

Nomeie os campos para o layout do editor

Um bloco aberto no editor de conteúdo mostra primeiro o seu conteúdo: texto, rich text, fotos e listas, cada um sob o seu rótulo. As configurações vêm em seguida, como linhas com o rótulo ao lado do valor, e depois uma linha Advanced. O editor posiciona cada campo pelo seu tipo e slug, não pelo rótulo, e mostra cada rótulo como foi escrito. Estas convenções mudam onde um campo vai:

  • Campos de link. Um campo url, ou um campo string cujo slug termina em _url, _link ou _href, recebe uma linha de configurações.
  • Botões. Um campo string chamado {base}_label, {base}_text ou {base} compartilha uma linha com um campo de link chamado {base}_url, {base}_link ou {base}_href. A linha usa o rótulo do campo de texto. No Hero acima, link_label e link_url compartilham uma linha com o rótulo “Link label”.
  • Legendas. Um campo string chamado {image}_caption fica abaixo do campo image chamado {image}, como photo_caption abaixo de photo.
  • ID da seção. Um campo chamado anchor_id vai na linha Advanced.
  • Título principal. O primeiro campo string ou text cujo slug tem a palavra headline, heading, title ou statement é desenhado maior, como o título principal do bloco. Um campo cujo slug tem a palavra label, eyebrow, kicker ou tag nunca é o título principal. Os slugs são divididos em palavras nos sublinhados, então section_heading conta e subheadline não. Quando nenhum campo corresponde, o primeiro campo string ou text do bloco é o título principal, a menos que o slug dele tenha uma dessas palavras excluídas.

Um campo repeater dentro de um bloco assume sua forma a partir de seus subcampos:

  • Lista de digitação. Uma lista com exatamente um subcampo, do tipo string ou url, mostra cada item como uma linha com marcador. Enter adiciona uma linha, e colar várias linhas adiciona um item por linha. Uma lista de nomes de clientes se encaixa nesse formato.
  • Tabela. Uma lista com até três subcampos, cada um do tipo string, url, number, integer, select ou image, e no máximo uma image, mostra uma linha por item e uma coluna por subcampo. Uma lista de estatísticas com um valor e um rótulo se encaixa nesse formato.
  • Itens expansíveis. Qualquer outra lista mostra cada item como uma linha que se abre para editar seus subcampos. Um item aberto organiza seus subcampos com as regras acima, exceto que nenhum subcampo é desenhado como título principal nem vai em uma linha Advanced, uma foto recebe uma linha de configurações e {image}_caption é um campo de texto comum.

O título de um item é o seu primeiro subcampo string que não seja um campo de link nem o texto de um botão ou, caso contrário, o seu primeiro subcampo text. Um item fechado mostra o seu título, seguido de até dois dos seus outros valores string. Quando todos estão vazios, ele mostra o início do seu primeiro outro valor text. No Feature grid acima, items aparece como itens expansíveis intitulados por title. Adicionar um quarto subcampo, ou um subcampo text, ao tipo de bloco de uma tabela transforma a lista em itens expansíveis.

Estas regras são dicas de layout de melhor esforço e podem mudar em uma versão futura. Elas afetam apenas como o editor organiza o formulário, e um campo que não corresponde a nenhuma delas recebe uma linha própria.

Crie os componentes Astro

Cada componente recebe value, index e blockKey. O valor inclui _type, _version e _key, de modo que um componente possa restringir as versões retidas quando o esquema do seu bloco evoluir.

O componente Hero lê cada valor exibido a partir do bloco armazenado:

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

Crie um componente para cada tipo permitido. O componente controla a marcação e o estilo; o valor do bloco fornece o conteúdo e a mídia.

Renderize a composição

Use defineBlockComponents para exigir um componente para cada _type da união de campos gerada. Passe esse mapa para <Blocks> na rota da página.

---
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ão executa consultas de conteúdo, esquema, mídia ou rede. Ele renderiza o array fornecido na ordem armazenada. Um componente de bloco pode fazer uma consulta explícita da aplicação quando precisar de outros dados.

Lide com um componente ausente

Durante o desenvolvimento, um tipo não mapeado produz um placeholder visível e um aviso no console. O placeholder nomeia o _type, mas não imprime o valor do bloco armazenado.

Em produção, um tipo não mapeado renderiza o componente fallback, quando fornecido. Caso contrário, não produz nenhuma saída:

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

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

Publique o suporte do renderizador antes de habilitar ou ativar um tipo de bloco usado pelo conteúdo de produção.

Altere o esquema de um bloco

Alterações compatíveis emendam a versão ativa. Adicionar um campo opcional, adicionar um valor padrão ou afrouxar a validação mantém o mesmo número de versão. Os blocos armazenados recebem os padrões na próxima vez em que forem gravados.

Uma alteração incompatível cria uma versão inativa. Remover um campo, alterar o tipo de um campo, adicionar um campo obrigatório ou restringir a validação são alterações incompatíveis.

  1. Crie a versão incompatível pela API de esquema ou pelo MCP. Mantenha-a inativa.

  2. Atualize o renderizador para tratar tanto a versão retida quanto a nova versão. Faça o deploy do renderizador.

  3. Ative a nova versão. Os novos blocos a usam após a ativação.

  4. Migre explicitamente os blocos armazenados com migrateBlocks: true. Preserve o _key de cada bloco enquanto altera _version e seus campos específicos da versão.

As versões antigas continuam disponíveis para revisões, rascunhos, rastreamento de mídia e conteúdo armazenado. Os tipos de bloco e as versões retidas não têm uma operação de exclusão definitiva.

Campos aninhados suportados

As definições de bloco suportam string, text, url, number, integer, boolean, datetime, select, multiSelect, portableText, image, file e repeater.

Referências, JSON, slugs, blocos aninhados, widgets personalizados, índices físicos, unicidade e localização por subcampo não são suportados dentro de uma definição de bloco. Um campo blocks em si não pode ser obrigatório, único, pesquisável, indexado nem receber um widget de campo personalizado.

Para as regras exatas de validação de campos e de valores armazenados, consulte a referência do campo blocks. Para o comportamento de conflitos e de exportação de seeds, consulte Arquivos seed.