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
相容的變更會修訂目前生效的版本。新增選用欄位、新增預設值或放寬校驗,都會維持相同的版本號。已儲存的區塊會在下次寫入時取得預設值。
破壞性變更會建立一個未啟動的版本。移除欄位、變更欄位類型、新增必填欄位或收緊校驗,都屬於破壞性變更。
-
透過 schema API 或 MCP 建立破壞性版本。讓它保持未啟動狀態。
-
更新算繪器,使其同時處理保留的版本和新版本。部署算繪器。
-
啟動新版本。啟動之後,新區塊會使用它。
-
使用
migrateBlocks: true明確遷移已儲存的區塊。在變更_version及其特定於版本的欄位時,保留每個區塊的_key。
舊版本仍然可用於修訂、草稿、媒體追蹤和已儲存的內容。區塊類型和保留的版本沒有硬刪除操作。
支援的巢狀欄位
區塊定義支援 string、text、url、number、integer、boolean、datetime、select、multiSelect、portableText、image、file 和 repeater。
區塊定義內部不支援參照、JSON、slug、巢狀區塊、自訂小工具、實體索引、唯一性以及依子欄位的在地化。blocks 欄位本身不能設為必填、唯一、可搜尋、可索引,也不能指定自訂欄位小工具。
有關確切的欄位校驗和已儲存值的規則,請參閱 blocks 欄位參考。有關種子衝突和匯出行為,請參閱 Seed 檔案。