告別複製貼上！Gutenberg 自訂區塊開發聖經：從 React 到 block.json，打造你的現代化編輯器體驗

嗨，我是浪花科技的資深工程師 Eric。寫了這麼多年的 WordPress，我看著它從一個單純的部落格平台，演變成一個功能強大的 CMS。而這其中最具革命性的變化，莫過於 Gutenberg 編輯器的誕生。剛開始，很多開發者（包括我）都對它有點抗拒，畢竟我們習慣了傳統編輯器和靈活的 Meta Box。但說真的，當你真正投入 Gutenberg 自訂區塊開發 的世界後，你會發現一片新大陸，一片充滿無限可能性的新大陸。

還在用 Shortcode 短代碼讓客戶輸入複雜的參數嗎？還在用 ACF 做出一個個欄位，卻無法在後台預覽最終效果嗎？這些都已經是「上個世代」的作法了。現在的 WordPress 體驗，核心就是「區塊」。今天，就讓我這個有點囉嗦的工程師，帶你從零開始，一步步架設現代化的開發環境，理解 Gutenberg 區塊的核心概念，並親手打造一個屬於你自己的自訂區塊。準備好了嗎？泡杯咖啡，我們開始動手！

為何要投資時間學習 Gutenberg 自訂區塊開發？

在我們一頭栽進程式碼之前，我想先聊聊「為什麼」。為什麼我們需要拋棄熟悉的短代碼和傳統 Meta Box，擁抱這個以 React 為基礎的新世界？這不是為了追逐潮流，而是為了解決過去長久以來的痛點。

告別 Shortcode 語法地獄

你一定有過這種經驗：為客戶做了一個功能，要用短代碼 [my_slider speed="500" dots="true"] 這樣的語法來呼叫。結果客戶不是打錯字，就是忘了哪個參數，電話就來了。Gutenberg 區塊直接將這些設定項變成側邊欄的視覺化選項，使用者只需要點擊、輸入，就能在編輯器中即時看到效果。這對使用者體驗的提升是巨大的，也大幅減少了我們後續維護和客服的成本。

所見即所得 (WYSIWYG) 的終極進化

傳統編輯器雖然也號稱 WYSIWYG，但碰到複雜的排版或動態內容時，往往後台看到的跟前台渲染出來的完全是兩回事。Gutenberg 的核心理念就是讓編輯體驗盡可能地接近前台的最終樣貌。透過自訂區塊，我們可以精準控制在編輯器內的樣式和互動，讓內容創作者能夠充滿信心地進行排版，而不是儲存後到前台看一眼，再切回後台修改，無限循環。

模組化與可重用性：打造你的內容樂高

把每一個內容單元都視為一個獨立的「區塊」，就像樂高積木一樣。你可以打造一個「公司團隊成員」區塊、一個「客戶見證」區塊、或是一個「產品特色」區塊。這些區塊一旦開發完成，就可以在網站的任何頁面中重複使用，甚至組合成更複雜的「區塊版型」。這種模組化的思維，讓內容管理變得前所未有的高效與彈性。

工欲善其事：架設現代化 Gutenberg 開發環境

好了，說服了自己之後，我們來動手做正事。要進行現代化的 Gutenberg 自訂區塊開發，你需要準備一些工具。別怕，雖然聽起來很「前端工程師」，但 WordPress 官方已經幫我們把最複雜的部分都打包好了。

• Node.js 與 npm： 這是現代 JavaScript 開發的基石。你需要它來管理專案的相依套件和執行編譯指令。請確保你安裝了 Node.js 的 LTS (長期支援) 版本。
• @wordpress/scripts： 這是 WordPress 官方推出的開發工具包，它整合了 Webpack、Babel、ESLint 等所有你需要的工具。你完全不需要自己去設定那些複雜的 config 檔，真香！

萬事俱備後，打開你的終端機 (Terminal)，切換到你的 WordPress 外掛目錄 (wp-content/plugins)，然後執行以下指令：

npx @wordpress/create-block my-first-block

這個指令會做幾件事：

1. 建立一個名為 my-first-block 的資料夾。
2. 下載所有需要的開發套件。
3. 產生一個立即可用的基礎區塊範本檔案結構。

沒錯，就是這麼簡單。一個指令，你的開發環境就搭好了。這時候去 WordPress 後台啟用這個名為「My First Block」的外掛，你就能在編輯器中找到它了。

拆解你的第一個自訂區塊：從 block.json 開始

讓我們來看看 @wordpress/create-block 幫我們產生了哪些檔案。其中最重要的，就是那個名為 block.json 的檔案。我稱之為區塊的身分證。

block.json 是 Gutenberg 區塊的 metadata 核心。WordPress 透過讀取這個檔案來了解你的區塊叫什麼名字、有什麼屬性、需要載入哪些檔案等等。一個基本的 block.json 看起來像這樣：

{
    "$schema": "https://schemas.wp.org/wp/6.2/block.json",
    "apiVersion": 2,
    "name": "create-block/my-first-block",
    "version": "0.1.0",
    "title": "My First Block",
    "category": "widgets",
    "icon": "smiley",
    "description": "Example block scaffolded with Create Block tool.",
    "supports": {
        "html": false
    },
    "textdomain": "my-first-block",
    "editorScript": "file:./build/index.js",
    "editorStyle": "file:./build/index.css",
    "style": "file:./build/style-index.css"
}

這裡面定義了區塊的名稱 (name)、標題 (title)、分類 (category)、圖示 (icon)，以及最重要的：它告訴 WordPress，這個區塊在編輯器中需要載入的 JavaScript 是 build/index.js，樣式是 build/index.css。

React 雙核心：深入 Edit 與 Save 元件

接下來，我們把目光移到 src 資料夾。你會看到幾個關鍵的 JS 檔案，其中 edit.js 和 save.js 是區塊的靈魂。

• edit.js： 這個檔案裡的 React 元件，決定了你的區塊「在編輯器裡長什麼樣子」。所有後台的互動、設定欄位的操作，都在這裡處理。
• save.js： 這個檔案裡的 React 元件，則決定了當使用者儲存文章時，這個區塊要「輸出什麼樣的 HTML 內容」到資料庫。

這是一個非常重要的概念分離。Edit 管後台，Save 管前台。

舉個例子，我們來做一個簡單的「資訊卡」區塊，可以讓使用者輸入標題和內容。

第一步：定義屬性 (Attributes)

首先，打開 block.json，加入 `attributes` 欄位來定義我們需要儲存的資料：

// ... 其他設定 ...
"attributes": {
    "title": {
        "type": "string",
        "source": "html",
        "selector": "h3"
    },
    "content": {
        "type": "string",
        "source": "html",
        "selector": "p"
    }
}
// ... 其他設定 ...

這裡我們定義了兩個屬性：`title` 和 `content`。`source: ‘html’` 和 `selector` 告訴 WordPress 如何從 `save.js` 產生的 HTML 中抓取和儲存資料。

第二步：打造編輯器體驗 (edit.js)

打開 src/edit.js，我們用 WordPress 提供的元件來建立輸入框：

import { useBlockProps, RichText } from '@wordpress/block-editor';

export default function Edit({ attributes, setAttributes }) {
    const blockProps = useBlockProps();
    const { title, content } = attributes;

    return (
        <div { ...blockProps }>
            <RichText
                tagName="h3"
                value={ title }
                onChange={ ( newTitle ) => setAttributes({ title: newTitle }) }
                placeholder="請輸入標題..."
            />
            <RichText
                tagName="p"
                value={ content }
                onChange={ ( newContent ) => setAttributes({ content: newContent }) }
                placeholder="請輸入內容..."
            />
        </div>
    );
}

這裡我們用了 RichText 元件，它提供了類似 Word 的編輯功能。當使用者輸入內容時，onChange 事件會觸發，並透過 setAttributes 函數更新區塊的資料。

第三步：定義儲存結構 (save.js)

最後，打開 src/save.js，定義最終要存到資料庫的 HTML 結構：

import { useBlockProps, RichText } from '@wordpress/block-editor';

export default function save({ attributes }) {
    const blockProps = useBlockProps.save();
    const { title, content } = attributes;

    return (
        <div { ...blockProps }>
            <RichText.Content tagName="h3" value={ title } />
            <RichText.Content tagName="p" value={ content } />
        </div>
    );
}

注意到了嗎？save 函數只負責根據傳入的 `attributes` 渲染出靜態的 HTML。這裡沒有 `onChange`，沒有 `setAttributes`，因為它不處理任何互動，只負責「輸出」。

從開發到部署：編譯與實戰

在你的終端機裡，my-first-block 資料夾下，執行：

npm start

這個指令會啟動一個監聽模式。現在，每當你修改並儲存 src 資料夾裡的任何檔案，@wordpress/scripts 就會自動幫你重新編譯，產生最新的 build 資料夾內容。你只需要在瀏覽器重新整理編輯器頁面，就能看到最新的變更。

當你開發完成，準備要將這個外掛部署到正式站時，只需要執行：

npm run build

這個指令會幫你產生最佳化、壓縮過的正式版檔案。然後你就可以把整個外掛資料夾（記得刪除 node_modules 資料夾，它非常大！）上傳到你的伺服器了。

看到這裡，你是不是覺得 Gutenberg 自訂區塊開發 其實沒有想像中那麼可怕？是的，它有學習曲線，你需要了解一點 React 和現代 JavaScript 的概念。但它帶來的價值——無論是對開發者效率的提升，還是對使用者體驗的革命——都是無可比擬的。這是一項值得所有 WordPress 開發者投資的技能。

這篇文章只是一個開始，我們介紹了最基礎的「靜態區塊」開發流程。但 Gutenberg 的世界遠不止於此，還有與後端資料庫互動的「動態區塊」、可以共享設定的「區塊樣式」、以及組合多個區塊的「區塊版型」。這些都等著你去探索！

---

延伸閱讀：

• Gutenberg 開發不只前端！資深工程師帶你打造「PHP 動態區塊」，後端資料隨你玩！
• 解鎖 WordPress 的隱藏力量：functions.php 終極實戰指南，讓你的網站秒變客製化神器！
• 別再把 WordPress 當部落格！資深工程師手把手 CPT 實戰，打造真正客製化的網站後台

在浪花科技，我們專注於打造高效、穩定且使用者體驗絕佳的 WordPress 解決方案。如果你正在尋找一個專業的技術團隊，來幫助你客製化網站功能、串接複雜的 API，或是優化網站效能，我們都非常樂意提供協助。我們不僅僅是寫程式，更是您數位轉型路上的技術夥伴。

準備好讓您的網站體驗更上一層樓了嗎？立即聯繫我們，讓我們的專業團隊為您量身打造最合適的解決方案！