面向 WordPress 開發者的 EmDash

EmDash 將熟悉的 WordPress 概念——文章、頁面、分類法、選單、小工具和媒體庫——帶入現代化的 Astro 技術堆疊。您的內容管理知識可以直接遷移。

保持熟悉的內容

您從 WordPress 了解的概念在 EmDash 中都是一流的功能：

Collections 的工作方式類似於自訂文章類型——定義您的內容結構，在模板中查詢它
分類法 的工作方式相同——分層（如類別）和扁平（如標籤）
選單支援拖放排序和巢狀項目
小工具區域 用於側邊欄和動態內容區域
媒體庫 支援上傳、組織和圖片管理
管理介面 內容編輯者無需接觸程式碼即可使用

不同的地方

實作方式改變了，但思維模型保持不變：

TypeScript 而非 PHP

模板是 Astro 元件。語法更清晰，但概念相同：輸出 HTML 的伺服器程式碼。

內容 API 而非 WP_Query

像 getEmDashCollection() 這樣的查詢函數取代了 WP_Query。不需要 SQL，只需函數呼叫。

基於檔案的路由

src/pages/ 中的檔案變成 URL。無需記憶重寫規則或模板層次結構。

元件而非模板部分

匯入並使用元件。與 get_template_part() 相同的想法，更好的組織方式。

快速參考

WordPress	EmDash	說明
自訂文章類型	Collections	透過管理介面或 API 定義
`WP_Query`	`getEmDashCollection()`	過濾器、限制、分類法查詢
`get_post()`	`getEmDashEntry()`	傳回條目或 null
類別/標籤	分類法	保留層次結構支援
`register_nav_menus()`	`getMenu()`	一流的選單支援
`register_sidebar()`	`getWidgetArea()`	一流的小工具區域
`bloginfo('name')`	`getSiteSetting("title")`	網站設定 API
`the_content()`	`<PortableText />`	結構化內容渲染
短代碼	Portable Text 區塊	自訂元件
`add_action/filter()`	外掛程式鉤子	`content:beforeSave` 等
`wp_options`	`ctx.kv`	鍵值儲存
佈景主題目錄	`src/` 目錄	元件、版面配置、頁面
`functions.php`	`astro.config.mjs` + EmDash 設定	建置和執行時期設定

內容 API

查詢 Collections

WordPress 查詢使用 WP_Query 或輔助函數。EmDash 使用類型化的查詢函數。

WordPress

<?php
$posts = new WP_Query([
  'post_type' => 'post',
  'posts_per_page' => 10,
  'post_status' => 'publish',
  'category_name' => 'news',
]);

while ($posts->have_posts()) :
$posts->the_post();
?>

  <h2><?php the_title(); ?></h2>
  <?php the_excerpt(); ?>
<?php endwhile; ?>

EmDash

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts", {
status: "published",
limit: 10,
where: { category: "news" },
});

---

{posts.map((post) => (

  <article>
    <h2>{post.data.title}</h2>
    <p>{post.data.excerpt}</p>
  </article>
))}

取得單個條目

以下範例透過識別碼取得條目並渲染它，在 WordPress 和 EmDash 中：

WordPress

<?php
$post = get_post($id);
?>
<article>
  <h1><?php echo $post->post_title; ?></h1>
  <?php echo apply_filters('the_content', $post->post_content); ?>
</article>

EmDash

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

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) return Astro.redirect("/404");
---

<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>

模板層次結構

WordPress 使用模板層次結構來選擇哪個檔案渲染頁面。Astro 使用明確的基於檔案的路由。

WordPress 模板	EmDash 等效項
`index.php`	`src/pages/index.astro`
`single.php`	`src/pages/posts/[slug].astro`
`single-{type}.php`	`src/pages/{type}/[slug].astro`
`page.php`	`src/pages/pages/[slug].astro`
`archive.php`	`src/pages/posts/index.astro`
`archive-{type}.php`	`src/pages/{type}/index.astro`
`category.php`	`src/pages/categories/[slug].astro`
`tag.php`	`src/pages/tags/[slug].astro`
`search.php`	`src/pages/search.astro`
`404.php`	`src/pages/404.astro`
`header.php` / `footer.php`	`src/layouts/Base.astro`
`sidebar.php`	`src/components/Sidebar.astro`

模板部分 → 元件

WordPress 模板部分變成 Astro 元件：

WordPress

// 在模板中：
get_template_part('template-parts/content', 'post');

// template-parts/content-post.php：

<article class="post">
  <h2><?php the_title(); ?></h2>
  <?php the_excerpt(); ?>
</article>

EmDash

---
const { post } = Astro.props;
---

<article class="post">
	<h2>{post.data.title}</h2>
	<p>{post.data.excerpt}</p>
</article>

下面的頁面匯入該元件並為每篇文章渲染它：

---
import PostCard from "../components/PostCard.astro";
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts");
---

{posts.map((post) => <PostCard {post} />)}

選單

EmDash 擁有自動 URL 解析的一流選單支援：

WordPress

<?php
wp_nav_menu([
  'theme_location' => 'primary',
  'container' => 'nav',
]);
?>

EmDash

---
import { getMenu } from "emdash";

const menu = await getMenu("primary");
---

<nav>
  <ul>
    {menu?.items.map((item) => (
      <li>
        <a href={item.url}>{item.label}</a>
      </li>
    ))}
  </ul>
</nav>

選單透過管理介面、種子檔案或 WordPress 匯入建立。

小工具區域

小工具區域的工作方式類似於 WordPress 中的側邊欄：

WordPress

<?php if (is_active_sidebar('sidebar-1')) : ?>
  <aside>
    <?php dynamic_sidebar('sidebar-1'); ?>
  </aside>
<?php endif; ?>

EmDash

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

const sidebar = await getWidgetArea("sidebar");
---

{sidebar && (

  <aside>
    {sidebar.widgets.map((widget) => {
      if (widget.type === "content") {
        return <PortableText value={widget.content} />;
      }
      // 處理其他小工具類型
    })}
  </aside>
)}

網站設定

網站選項和自訂器設定對應到 getSiteSetting()：

WordPress	EmDash
`bloginfo('name')`	`getSiteSetting("title")`
`bloginfo('description')`	`getSiteSetting("tagline")`
`get_custom_logo()`	`getSiteSetting("logo")`
`get_option('date_format')`	`getSiteSetting("dateFormat")`
`home_url()`	`Astro.site`

下面的範例使用 getSiteSetting() 讀取單個設定：

import { getSiteSetting } from "emdash";

const title = await getSiteSetting("title");
const logo = await getSiteSetting("logo"); // 傳回 { mediaId, alt, url }

分類法

分類法在概念上的工作方式相同——分層（如類別）或扁平（如標籤）：

import { getTaxonomyTerms, getEntryTerms, getTerm } from "emdash";

// 取得所有類別
const categories = await getTaxonomyTerms("categories");

// 取得特定術語
const news = await getTerm("categories", "news");

// 取得文章的術語
const postCategories = await getEntryTerms("posts", postId, "categories");

鉤子 → 外掛程式系統

WordPress 鉤子（add_action、add_filter）變成 EmDash 外掛程式鉤子：

WordPress 鉤子	EmDash 鉤子	目的
`save_post`	`content:beforeSave`	在儲存前修改內容
`the_content`	PortableText 元件	轉換渲染的內容
`pre_get_posts`	查詢選項	過濾查詢
`wp_head`	版面配置 `<head>`	新增 head 內容
`wp_footer`	版面配置 `</body>` 之前	新增 footer 內容

EmDash 的優勢

類型安全

全面使用 TypeScript。Collections、查詢和元件都是完全類型化的，因此欄位名稱和傳回類型可以自動完成並在建置時檢查。

效能

預設靜態生成，需要時進行伺服器渲染。支援邊緣部署。

現代開發體驗

熱模組替換。基於元件的架構。現代工具（Vite、TypeScript、ESLint）。

基於 Git 的部署

程式碼和模板儲存在 git 中；內容儲存在資料庫中。透過推送程式碼進行部署。

預覽連結

EmDash 使用 HMAC 簽章權杖產生安全的預覽 URL。內容編輯者共享預覽連結以顯示草稿，以便審核者可以在不登入生產環境的情況下檢視。

隔離的外掛程式

EmDash 外掛程式在具有明確 API 的隔離上下文中執行。每個外掛程式只能存取它宣告的 API，因此外掛程式不會共享或覆蓋彼此的全域狀態。

內容編輯者體驗

內容編輯者使用類似於 wp-admin 的 EmDash 管理面板：

帶有最近活動的儀表板
帶有搜尋、過濾和批次操作的 Collection 清單
用於內容的富文字編輯器（Portable Text，而非 Gutenberg）
支援拖放上傳的媒體庫
支援拖放排序的選單建構器
用於側邊欄內容的小工具區域編輯器

編輯體驗很熟悉。底層技術是現代化的。

遷移路徑

EmDash 直接匯入 WordPress 內容：

從 WordPress 匯出（工具 → 匯出）
在 EmDash 的管理介面中上傳 .xml 檔案
將文章類型對應到 Collections
匯入內容和媒體

文章、頁面、分類法、選單和媒體都會轉移。Gutenberg 區塊轉換為 Portable Text。自訂欄位被分析和對應。

檢視 WordPress 遷移指南取得完整說明。

下一步

入門 — 設定您的第一個 EmDash 網站
查詢內容 — 深入了解內容 API
分類法 — 類別、標籤和自訂分類法
選單 — 導覽選單
從 WordPress 遷移 — 匯入現有內容