블록으로 페이지 만들기

이 페이지

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라는 이름의 링크 필드와 한 행을 공유합니다. 이 행은 텍스트 필드의 레이블을 사용합니다. 위 Hero에서는 link_label과 link_url이 “Link label”이라는 레이블의 한 행을 공유합니다.
  • 캡션. {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 유형 하나뿐인 목록은 각 항목을 글머리 기호가 있는 줄로 표시합니다. Enter를 누르면 줄이 추가되고, 여러 줄을 붙여 넣으면 줄마다 항목이 하나씩 추가됩니다. 고객 이름 목록이 이 형태에 해당합니다.
  • 표. 하위 필드가 최대 세 개이고 각각 string, url, number, integer, select, image 유형이며 image가 많아야 하나인 목록은 항목마다 한 행, 하위 필드마다 한 열로 표시합니다. 값과 레이블이 있는 통계 목록이 이 형태에 해당합니다.
  • 펼칠 수 있는 항목. 그 밖의 모든 목록은 각 항목을 하위 필드를 편집하기 위해 펼쳐지는 행으로 표시합니다. 펼쳐진 항목은 위의 규칙으로 하위 필드를 배치하되, 어떤 하위 필드도 헤드라인으로 표시되거나 Advanced 행에 들어가지 않고, 사진은 설정 행을 받으며, {image}_caption은 일반 텍스트 필드라는 점이 다릅니다.

항목의 제목은 링크 필드도 버튼의 텍스트도 아닌 첫 번째 string 하위 필드이며, 없으면 첫 번째 text 하위 필드입니다. 닫힌 항목은 제목과 함께 다른 string 값을 최대 두 개까지 표시합니다. 그 값이 모두 비어 있으면 대신 다른 첫 번째 text 값의 앞부분을 표시합니다. 위 Feature grid에서 items는 title을 제목으로 하는 펼칠 수 있는 항목으로 표시됩니다. 표 형태 블록 유형에 네 번째 하위 필드나 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에 대해 컴포넌트를 하나씩 요구할 수 있습니다. 그 맵을 페이지 라우트의 <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 필드 레퍼런스를 참조하세요. 시드 충돌과 내보내기 동작은 시드 파일을 참조하세요.