ブロックでページを構築する

このページ

blocks フィールドは、順序付けられたページのコンポジションを保存します。各項目には、ブロックタイプ、保持されているスキーマバージョン、安定したキー、そのバージョンで宣言されたフィールドが記録されます。エディターは、コンテンツエディターでブロックを追加したり並べ替えたりします。Astro ルートは、各ブロックタイプをコンポーネントにマッピングします。

ブロックタイプを定義する

ブロックタイプは、それを使用するコレクションフィールドより前に定義します。シードは、番号付きのすべてのバージョンと、アクティブな currentVersion ポインターを保持します。

次のシードは Hero と Feature grid のブロックを定義し、それらを Pages の layout フィールドで使えるようにします。

{
  "$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
          }
        }
      ]
    }
  ]
}

ブロックピッカーは、ブロックタイプを allowedTypes の順に category ごとにグループ化して一覧表示し、各タイプの description と icon を表示します。icon には、sparkle や chart-bar など、Phosphor アイコンの名前を設定します。エディターはコンテンツエディターの各ブロックでもこのアイコンを見ます。アイコンのないブロックタイプや、Phosphor アイコンに一致しない名前のブロックタイプには、汎用のブロックアイコンが表示されます。

許可されたタイプを後から削除すると、EmDash はそれをサーバー管理の retiredTypes リストに移動します。既存のブロックは引き続き編集できますが、エディターはそのタイプを追加したり複製したりできません。

エディターのレイアウトに合わせてフィールドに名前を付ける

コンテンツエディターで開いたブロックには、まずそのコンテンツが表示されます。テキスト、リッチテキスト、写真、リストが、それぞれのラベルの下に並びます。続いて設定が、ラベルを値の横に置いた行として表示され、その後に Advanced 行が来ます。エディターは、ラベルではなくフィールドのタイプとスラッグに基づいて各フィールドを配置し、すべてのラベルを記述どおりに表示します。次の規則によって、フィールドの配置先が変わります。

  • リンクフィールド。 url フィールド、またはスラッグが _url、_link、_href で終わる string フィールドは、設定行になります。
  • ボタン。 {base}_label、{base}_text、{base} という名前の string フィールドは、{base}_url、{base}_link、{base}_href という名前のリンクフィールドと 1 つの行を共有します。この行にはテキストフィールドのラベルが使われます。上の Hero では、link_label と link_url が「Link label」というラベルの 1 行を共有します。
  • キャプション。 {image}_caption という名前の string フィールドは、{image} という名前の image フィールドの下に配置されます。たとえば photo の下の photo_caption です。
  • セクション ID。 anchor_id という名前のフィールドは、Advanced 行に入ります。
  • 見出し。 スラッグに headline、heading、title、statement のいずれかの単語を含む最初の string または text フィールドは、ブロックの見出しとして大きく表示されます。スラッグに label、eyebrow、kicker、tag のいずれかの単語を含むフィールドが見出しになることはありません。スラッグはアンダースコアで単語に分割されるため、section_heading は該当しますが、subheadline は該当しません。どのフィールドも該当しない場合は、スラッグにそれらの除外語が含まれていない限り、ブロックの最初の string または text フィールドが見出しになります。

ブロック内の repeater フィールドは、サブフィールドによって形が決まります。

  • 入力リスト。 サブフィールドが string または url タイプの 1 つだけであるリストでは、各項目が箇条書きの行として表示されます。Enter で行を追加でき、複数行を貼り付けると 1 行につき 1 項目が追加されます。クライアント名のリストがこの形に当てはまります。
  • テーブル。 サブフィールドが最大 3 つで、それぞれ string、url、number、integer、select、image のいずれかのタイプであり、image が多くても 1 つのリストでは、項目ごとに 1 行、サブフィールドごとに 1 列が表示されます。値とラベルを持つ統計のリストがこの形に当てはまります。
  • 展開可能な項目。 それ以外のすべてのリストでは、各項目がサブフィールドを編集するために開く行として表示されます。開いた項目は、上記の規則でサブフィールドを配置しますが、どのサブフィールドも見出しとして表示されたり Advanced 行に入ったりしないこと、写真は設定行になること、{image}_caption が通常のテキストフィールドになることが異なります。

項目のタイトルは、リンクフィールドでもボタンのテキストでもない最初の string サブフィールドです。なければ、最初の text サブフィールドです。閉じた項目には、タイトルに続いて、ほかの string 値が最大 2 つ表示されます。それらがすべて空の場合は、代わりにほかの最初の text 値の冒頭が表示されます。上の Feature grid では、items は title をタイトルとする展開可能な項目として表示されます。テーブルのブロックタイプに 4 つ目のサブフィールドや text サブフィールドを追加すると、リストは展開可能な項目に変わります。

これらの規則はベストエフォートのレイアウトのヒントであり、今後のリリースで変更される可能性があります。エディターがフォームを配置する方法にのみ影響し、どの規則にも一致しないフィールドは独立した行になります。

Astro コンポーネントを作成する

各コンポーネントは value、index、blockKey を受け取ります。値には _type、_version、_key が含まれるため、ブロックスキーマが進化するときに、コンポーネントは保持されているバージョンを絞り込めます。

Hero コンポーネントは、表示するすべての値を保存されたブロックから読み取ります。

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

許可されたタイプごとにコンポーネントを作成します。マークアップとスタイルはコンポーネントが制御し、コンテンツとメディアはブロックの値が提供します。

コンポジションをレンダリングする

defineBlockComponents を使用すると、生成されたフィールドのユニオン内のすべての _type に対して、コンポーネントを 1 つずつ必須にできます。そのマップをページルートの <Blocks> に渡します。

---
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> は、コンテンツ、スキーマ、メディア、ネットワークのクエリを一切実行しません。渡された配列を、保存された順序でレンダリングします。ブロックコンポーネントが他のデータを必要とする場合は、そのコンポーネントが明示的にアプリケーションのクエリを実行できます。

コンポーネントが見つからない場合の処理

開発中は、マッピングされていないタイプがあると、目に見えるプレースホルダーとコンソール警告が出力されます。プレースホルダーには _type の名前が表示されますが、保存されたブロックの値は出力されません。

本番環境では、マッピングされていないタイプは、fallback コンポーネントが指定されていればそれをレンダリングします。指定されていなければ、何も出力しません。

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

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

本番コンテンツで使用されるブロックタイプを有効化またはアクティブ化する前に、レンダラーのサポートをリリースしてください。

ブロックスキーマを変更する

互換性のある変更は、アクティブなバージョンを修正します。オプションのフィールドの追加、デフォルト値の追加、バリデーションの緩和では、バージョン番号は同じままです。保存済みのブロックには、次に書き込まれるときにデフォルト値が適用されます。

破壊的な変更は、非アクティブなバージョンを作成します。フィールドの削除、フィールドタイプの変更、必須フィールドの追加、バリデーションの厳格化は、破壊的な変更です。

  1. スキーマ API または MCP で、破壊的なバージョンを作成します。非アクティブのままにします。

  2. 保持されているバージョンと新しいバージョンの両方を処理できるように、レンダラーを更新します。レンダラーをデプロイします。

  3. 新しいバージョンをアクティブにします。アクティブ化の後、新しいブロックはそれを使用します。

  4. migrateBlocks: true を使って、保存済みのブロックを明示的に移行します。_version とそのバージョン固有のフィールドを変更するときも、各ブロックの _key は保持します。

古いバージョンは、リビジョン、下書き、メディアの追跡、保存済みのコンテンツのために引き続き利用できます。ブロックタイプと保持されているバージョンには、完全削除の操作はありません。

サポートされるネストされたフィールド

ブロック定義は、string、text、url、number、integer、boolean、datetime、select、multiSelect、portableText、image、file、repeater をサポートします。

ブロック定義の内部では、参照、JSON、スラグ、ネストされたブロック、カスタムウィジェット、物理インデックス、一意性、サブフィールドごとのローカライズはサポートされません。blocks フィールド自体は、必須、一意、検索可能、インデックス付きにすることも、カスタムのフィールドウィジェットを割り当てることもできません。

フィールドのバリデーションと保存される値のルールの詳細は、blocks フィールドのリファレンスを参照してください。シードの競合とエクスポートの動作については、シードファイルを参照してください。