使用區塊建構頁面

本頁內容

blocks 欄位儲存一個有序的頁面組合。每一項都會記錄區塊類型、保留的 schema 版本、穩定的 key,以及該版本所宣告的欄位。編輯者在內容編輯器中新增區塊並調整順序。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 設定為 Phosphor 圖示的名稱,例如 sparkle 或 chart-bar;編輯者在內容編輯器中也會在每個區塊上看到它。沒有圖示,或名稱與 Phosphor 圖示不相符的區塊類型,會顯示通用的區塊圖示。

如果你之後移除了某個允許的類型,EmDash 會把它移到由伺服器管理的 retiredTypes 清單中。現有區塊仍然可以編輯,但編輯者無法新增或複製該類型。

為編輯器版面配置命名欄位

內容編輯器中展開的區塊會先顯示其內容:文字、富文字、照片和清單,每項都位於各自標籤之下。接著是設定,以標籤位於值旁邊的列顯示,最後是一個 Advanced 列。編輯器根據欄位的類型和 slug(而非標籤)來放置每個欄位,並按原樣顯示每個標籤。以下慣例會改變欄位的位置:

  • 連結欄位。 url 欄位,或 slug 以 _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 列中。
  • 標題。 slug 中含有 headline、heading、title 或 statement 這些詞的第一個 string 或 text 欄位,會以較大的字級顯示,作為區塊的標題。slug 中含有 label、eyebrow、kicker 或 tag 這些詞的欄位永遠不會成為標題。slug 會在底線處拆分為單字,因此 section_heading 符合條件,而 subheadline 不符合。沒有欄位相符時,區塊的第一個 string 或 text 欄位就是標題,除非它的 slug 含有上述被排除的詞。

區塊內的 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,因此當區塊 schema 演進時,元件可以縮小保留的版本範圍。

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> 不會執行任何內容、schema、媒體或網路查詢。它依儲存的順序算繪所提供的陣列。當某個區塊元件需要其他資料時,它可以執行明確的應用程式查詢。

處理缺少的元件

在開發期間,未對應的類型會產生一個可見的預留位置和一則主控台警告。預留位置會顯示 _type 的名稱,但不會列印已儲存的區塊值。

在正式環境中,未對應的類型會在提供了 fallback 元件時算繪該元件,否則不算繪任何輸出:

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

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

在啟用或啟動正式內容所使用的區塊類型之前,請先發布算繪器的支援。

變更區塊 schema

相容的變更會修訂目前生效的版本。新增選用欄位、新增預設值或放寬校驗,都會維持相同的版本號。已儲存的區塊會在下次寫入時取得預設值。

破壞性變更會建立一個未啟動的版本。移除欄位、變更欄位類型、新增必填欄位或收緊校驗,都屬於破壞性變更。

  1. 透過 schema API 或 MCP 建立破壞性版本。讓它保持未啟動狀態。

  2. 更新算繪器,使其同時處理保留的版本和新版本。部署算繪器。

  3. 啟動新版本。啟動之後,新區塊會使用它。

  4. 使用 migrateBlocks: true 明確遷移已儲存的區塊。在變更 _version 及其特定於版本的欄位時,保留每個區塊的 _key。

舊版本仍然可用於修訂、草稿、媒體追蹤和已儲存的內容。區塊類型和保留的版本沒有硬刪除操作。

支援的巢狀欄位

區塊定義支援 string、text、url、number、integer、boolean、datetime、select、multiSelect、portableText、image、file 和 repeater。

區塊定義內部不支援參照、JSON、slug、巢狀區塊、自訂小工具、實體索引、唯一性以及依子欄位的在地化。blocks 欄位本身不能設為必填、唯一、可搜尋、可索引,也不能指定自訂欄位小工具。

有關確切的欄位校驗和已儲存值的規則,請參閱 blocks 欄位參考。有關種子衝突和匯出行為,請參閱 Seed 檔案。