Sections

Sections 是可重複使用的內容區塊，編輯者可以透過斜線命令將其插入到任何內容中。將它們用於常見模式，如 CTA、推薦、功能網格或任何出現在多個頁面上的內容。

查詢 Sections

getSection

以下範例透過 slug 取得單一 section：

import { getSection } from "emdash";

const cta = await getSection("newsletter-cta");

if (cta) {
  console.log(cta.title);    // "Newsletter CTA"
  console.log(cta.content);  // PortableTextBlock[]
}

getSections

以下範例透過可選過濾器取得多個 sections：

import { getSections } from "emdash";

// Get all sections
const { items: all } = await getSections();

// Filter by source
const { items: themeSections } = await getSections({ source: "theme" });

// Search by title/keywords
const { items: results } = await getSections({ search: "newsletter" });

getSections 遵循標準分頁模式回傳 { items: Section[], nextCursor?: string }。

Section 結構

一個 section 具有以下形式：

interface Section {
  id: string;
  slug: string;
  title: string;
  description?: string;
  keywords: string[];
  content: PortableTextBlock[];
  previewUrl?: string;
  source: "theme" | "user" | "import";
  themeId?: string;
  createdAt: string;
  updatedAt: string;
}

來源類型

在內容中使用 Sections

編輯者使用富文字編輯器中的 /section 斜線命令插入 sections。

section 的 Portable Text 內容被複製到文件中。插入的內容是獨立的：編輯者可以自訂它，對 section 的後續變更不會影響已放置在內容中的副本。

建立 Sections

在管理介面中

1. 在管理側邊欄中導覽到 Sections

2. 點擊 New Section

3. 填寫：

   • Title - section 的顯示名稱
   • Slug - URL 識別碼（從標題自動產生）
   • Description - 編輯者的說明文字

4. 使用富文字編輯器新增內容

5. 可選擇設定關鍵字以便於發現

透過 Seed 檔案

以下 seed 檔案為主題定義了兩個 sections：

{
  "sections": [
    {
      "slug": "hero-centered",
      "title": "Centered Hero",
      "description": "Full-width hero with centered heading and CTA",
      "keywords": ["hero", "banner", "header"],
      "content": [
        {
          "_type": "block",
          "style": "h1",
          "children": [{ "_type": "span", "text": "Welcome to Our Site" }]
        },
        {
          "_type": "block",
          "children": [{ "_type": "span", "text": "Your tagline goes here." }]
        }
      ]
    },
    {
      "slug": "newsletter-cta",
      "title": "Newsletter CTA",
      "keywords": ["newsletter", "subscribe", "email"],
      "content": [
        {
          "_type": "block",
          "style": "h3",
          "children": [{ "_type": "span", "text": "Subscribe to our newsletter" }]
        }
      ]
    }
  ]
}

透過 WordPress 匯入

WordPress 可重複使用區塊（wp_block 文章類型）自動作為 sections 匯入：

• Source 設定為 "import"
• Gutenberg 內容轉換為 Portable Text

以程式方式呈現 Sections

以下範例在編輯器外部的伺服器端呈現 section 的內容：

---
import { getSection } from "emdash";
import { PortableText } from "emdash/ui";

const newsletter = await getSection("newsletter-cta");
---

{newsletter && (
  <aside class="cta-box">
    <PortableText value={newsletter.content} />
  </aside>
)}

管理介面功能

Sections 庫（/_emdash/admin/sections）提供：

• 帶有 section 預覽的網格檢視
• 按標題和關鍵字搜尋
• 按來源過濾
• 將 slug 快速複製到剪貼簿
• 編輯 section 內容和中繼資料
• 帶確認的刪除（對主題 sections 發出警告）

API 參考

getSection(slug)

透過 slug 取得 section。

參數：

• slug — section 的唯一識別碼（string）

回傳： Promise<Section | null>

getSections(options?)

使用可選過濾器列出 sections。

參數：

• options.source — 按來源過濾："theme"、"user" 或 "import"
• options.search — 搜尋標題、描述和關鍵字
• options.limit — 頁面大小（預設 50，最大 100）
• options.cursor — 來自前一個 nextCursor 的分頁游標

回傳： Promise<{ items: Section[]; nextCursor?: string }>

REST API

列出 Sections

列出 sections，可選擇按來源或搜尋詞過濾：

GET /_emdash/api/sections
GET /_emdash/api/sections?source=theme
GET /_emdash/api/sections?search=newsletter

取得 Section

透過 slug 取得單一 section：

GET /_emdash/api/sections/newsletter-cta

建立 Section

使用 POST 請求建立 section：

POST /_emdash/api/sections
Content-Type: application/json

{
  "slug": "my-section",
  "title": "My Section",
  "description": "Optional description",
  "keywords": ["keyword1", "keyword2"],
  "content": [...]
}

更新 Section

使用 PUT 請求更新 section：

PUT /_emdash/api/sections/my-section
Content-Type: application/json

{
  "title": "Updated Title",
  "content": [...]
}

刪除 Section

透過 slug 刪除 section：

DELETE /_emdash/api/sections/my-section

下一步

• 使用內容 - 了解富文字編輯器
• Widget Areas - 用於同步動態內容
• 內容匯入 - 匯入 WordPress 可重複使用區塊