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 可复用块