告別短代碼地獄！資深工程師手把手教你打造 Gutenberg 自訂區塊，釋放 WordPress 編輯器的真正潛力

哈囉，我是浪花科技的資深工程師 Eric。寫了這麼多年的 WordPress，我看過各種光怪陸離的後台。最讓我頭痛的，莫過於那種充滿了 [shortcode attr='value'] 的編輯器畫面。對客戶來說，這簡直是天書；對我們工程師來說，要嘛是自己寫的忘了怎麼用，要嘛是接手別人的專案，光是搞懂這些短代碼就得花上半天。

傳統的 TinyMCE 編輯器加上一堆 Meta Box 欄位，雖然能解決問題，但內容跟設定是完全分離的，編輯體驗非常破碎。使用者在文章主體打完字，還要捲到下面去填寫一堆欄位，根本無法即時預覽最終效果。這也是為什麼 Gutenberg（區塊編輯器）的出現，對 WordPress 來說是一場彻頭彻尾的革命。

今天，我不是要來跟你談 Gutenberg 有多好用，而是要帶你更進一步，成為區塊的「創造者」。我們要一起動手，進行一場 Gutenberg Block 自訂區塊開發，打造一個專屬於你自己網站的區塊。準備好了嗎？泡杯咖啡，打開你的編輯器，讓我們一起告別短代碼地獄！

為何要拋棄短代碼 (Shortcode)？Gutenberg 自訂區塊的時代來臨

我知道，有些老派的工程師可能會覺得：「短代碼不好嗎？我用得很習慣啊！」習慣歸習慣，但我們得承認，它真的不是一個對使用者友善的設計。想像一下，你的客戶興高采烈地想要編輯一個「團隊成員」頁面，結果打開來看到的是一堆 [team_member name='Eric' role='Engineer']...[/team_member]，他們大概只會想打電話給你。

相較之下，Gutenberg 自訂區塊提供了無與倫比的優勢：

• 所見即所得 (WYSIWYG)： 這是最大的賣點。使用者在後台編輯器裡看到的，幾乎就是前台訪客看到的樣子。可以直接在區塊內打字、換照片，即時預覽，體驗非常流暢。
• 可重複使用的元件： 每個區塊都是一個獨立、可重複使用的元件。你可以在任何頁面、任何文章中插入你做的「作者簡介」區塊，而不用每次都複製貼上一堆 HTML 或短代碼。
• 結構化資料： 區塊不只是存一堆 HTML，它是以結構化的方式（通常是 JSON 格式）儲存資料。這代表著資料是乾淨、有語意的，未來要做資料遷移、API 輸出，甚至是結合 AI 應用都更有彈性。
• 現代化的開發體驗： Gutenberg 的底層是 React，這意味著你可以使用現代 JavaScript 的所有工具和生態系來開發，這對工程師來說，絕對比在那邊拼湊 PHP 和 jQuery 字串來得舒服多了。

簡單來說，學會 Gutenberg Block 自訂區塊開發，不只是跟上潮流，更是提升你交付的網站品質、改善客戶編輯體驗的關鍵一步。

開發前的軍火庫：你需要準備什麼？

俗話說「工欲善其事，必先利其器」。在我們開始寫程式碼之前，得先把環境準備好。別擔心，不會太複雜，但這些是現代 WordPress 開發的基礎建設，絕對值得你花點時間熟悉。

• 本地 WordPress 開發環境： 拜託不要再用 FTP 直接改線上檔案了！你需要一個穩定的本地環境。我個人強力推薦使用 Docker，如果你還不熟悉，可以參考我們寫的「WordPress Docker 容器化部署終極教學」，一次搞定。
• Node.js 和 npm： 這是 JavaScript 的世界。你需要安裝 Node.js，它會順便幫你安裝 npm (Node Package Manager)。這是用來管理我們開發時會用到的各種 JavaScript 套件的工具。
• 基本的命令列操作知識： 我們會需要用終端機 (Terminal) 來下一些指令，例如安裝套件、啟動開發模式等。不用怕，都是些很簡單的指令。
• 一點點 JavaScript (ES6+) 和 React 基礎： 你不需要是 React 大神，但至少要看得懂 JSX 語法、知道什麼是 component 和 props。如果完全沒接觸過，這會是你踏入 React 世界的絕佳機會！

現代 WordPress 開發的瑞士刀：@wordpress/scripts

過去要開發 Gutenberg 區塊，光是設定 Webpack、Babel 這些打包編譯工具就夠讓人頭痛了。幸好，WordPress 官方團隊佛心地推出了一個叫做 @wordpress/scripts 的套件。你可以把它想像成一個「懶人包」，它把所有繁瑣的設定都處理好了，我們只需要專注在撰寫區塊的邏輯本身。

它提供了幾個核心指令，像是 npm run build 可以幫你把 React 的 JSX 程式碼編譯成瀏覽器看得懂的普通 JavaScript，而 npm run start 則會啟動一個開發模式，當你修改程式碼並存檔時，它會自動重新編譯，超級方便！

實戰開始：從零到一打造你的第一個「作者簡介」區塊

理論說再多，不如親手做一次。接下來，我們就來一步步打造一個簡單但實用的「作者簡介」區塊，它會有作者頭像、姓名、職稱和簡介四個欄位。

Step 1: 建立你的外掛與初始化專案

首先，在你的 WordPress 網站的 wp-content/plugins 資料夾下，建立一個新的資料夾，例如 roamer-author-block。在裡面建立一個同名的 PHP 檔案 roamer-author-block.php，並加入 WordPress 外掛的標頭資訊：

<?php
/**
 * Plugin Name: Roamer Author Block
 * Description: A custom Gutenberg block for displaying an author's bio.
 * Version: 1.0.0
 * Author: Eric @ Roamer Tech
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}

接著，打開你的終端機，切換到這個資料夾路徑下，執行以下指令來初始化專案並安裝 @wordpress/scripts：

npm init -y
npm install @wordpress/scripts --save-dev

然後打開剛產生的 package.json 檔案，加入 scripts 的設定：

{
  "name": "roamer-author-block",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@wordpress/scripts": "^27.9.0"
  }
}

Step 2: 區塊的核心大腦 – `block.json`

現在的開發流程，官方強烈建議使用 block.json 檔案來定義你的區塊。這是一個 metadata 檔案，告訴 WordPress 關於這個區塊的一切。在你的外掛資料夾裡，建立一個 src 資料夾，並在裡面新增一個 block.json 檔案：

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "roamer-tech/author-block",
  "version": "1.0.0",
  "title": "作者簡介",
  "category": "widgets",
  "icon": "admin-users",
  "description": "一個顯示作者頭像、姓名、職稱和簡介的區塊。",
  "supports": {
    "html": false
  },
  "attributes": {
    "name": {
      "type": "string",
      "source": "html",
      "selector": ".author-name"
    },
    "title": {
      "type": "string",
      "source": "html",
      "selector": ".author-title"
    },
    "bio": {
      "type": "string",
      "source": "html",
      "selector": ".author-bio"
    }
  },
  "editorScript": "file:./index.js"
}

囉嗦一下，這裡的 `attributes` 非常重要，它定義了這個區塊有哪些可編輯的資料，以及這些資料要如何從儲存的 HTML 中讀取出來。

Step 3: 註冊你的區塊 (PHP)

回到我們的 roamer-author-block.php 檔案，加入註冊區塊的程式碼。現在有了 block.json，事情變得很簡單：

function roamer_tech_register_author_block() {
    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'roamer_tech_register_author_block' );

注意到了嗎？我們指向的是 `build` 資料夾，而不是 `src`。這是因為 @wordpress/scripts 會將 `src` 裡面的原始碼編譯後，放到 `build` 資料夾中。

Step 4: 撰寫編輯器端的邏輯 (`edit.js`)

這是最核心的部分。在 src 資料夾下建立 `index.js`, `edit.js`, 和 `save.js` 三個檔案。

首先是 `index.js`，它是整個區塊的進入點：

import { registerBlockType } from '@wordpress/blocks';
import './style.scss'; // 如果你有樣式的話
import Edit from './edit';
import save from './save';
import metadata from './block.json';

registerBlockType( metadata.name, {
	/**
	 * @see ./edit.js
	 */
	edit: Edit,

	/**
	 * @see ./save.js
	 */
	save,
} );

接著是 `edit.js`，它定義了區塊在後台編輯器中的樣子和行為：

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

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

	return (
		<div { ...blockProps }>
			<RichText
				tagName="h3"
				className="author-name"
				placeholder="請輸入姓名"
				value={ name }
				onChange={ ( newName ) => setAttributes( { name: newName } ) }
			/>
			<RichText
				tagName="p"
				className="author-title"
				placeholder="請輸入職稱"
				value={ title }
				onChange={ ( newTitle ) => setAttributes( { title: newTitle } ) }
			/>
			<RichText
				tagName="p"
				className="author-bio"
				placeholder="請輸入簡介"
				value={ bio }
				onChange={ ( newBio ) => setAttributes( { bio: newBio } ) }
			/>
		</div>
	);
}

我們使用了 WordPress 核心提供的 `RichText` 元件，它能讓我們建立可編輯的文字區域。

Step 5: 決定前端顯示的樣貌 (`save.js`)

`save.js` 函式的作用是，根據你傳入的 `attributes`，回傳一段最終要儲存到資料庫的 HTML。這個函式必須是「純粹的」，也就是說，同樣的輸入永遠要得到同樣的輸出。

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

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

	return (
		<div { ...blockProps }>
			<RichText.Content tagName="h3" className="author-name" value={ name } />
			<RichText.Content tagName="p" className="author-title" value={ title } />
			<RichText.Content tagName="p" className="author-bio" value={ bio } />
		</div>
	);
}

Step 6: 萬事俱備，只欠編譯

回到你的終端機，在你的外掛根目錄下執行：

npm run build

這個指令會讀取 `src` 資料夾裡的檔案，編譯後產生一個 `build` 資料夾，裡面會有瀏覽器看得懂的 JS 和 CSS。現在，去你的 WordPress 後台啟用「Roamer Author Block」這個外掛，然後新增一篇文章，你應該就能在區塊選擇器中找到我們剛剛建立的「作者簡介」區塊了！

另一條康莊大道：ACF Blocks

看到這裡，你可能會覺得：「天啊，要學 React 還要搞懂這麼多東西，太難了吧！」別急著放棄。如果你對 PHP 比較熟悉，但又想享受區塊編輯器的好處，那麼 ACF Pro 提供的 ACF Blocks 功能就是你的救星。

ACF Blocks 讓你用 PHP 和大家熟悉的 ACF 欄位來定義一個區塊，而不需要寫任何一行 JavaScript。它的運作模式是：

• 優點： 開發速度快，特別是對於那些主要是顯示資料的靜態區塊。你可以直接在 PHP 樣板檔案中用 `get_field()` 來取得資料，跟你開發佈景主題的體驗非常類似。
• 缺點： 它的後台編輯體驗是透過一個表單彈窗來輸入，而不是直接在區塊上進行「即時編輯」，沉浸感稍差。另外，因為每次區塊渲染都需要一次 AJAX 請求，在非常複雜的頁面上，效能可能會略遜於原生的 React 區塊。

怎麼選？我的建議是，如果你的區塊需要複雜的互動、即時預覽（例如一個輪播、一個可以拖拉調整大小的圖表），那麼花時間學習原生的 React 開發是值得的。但如果你的需求只是做一個「團隊成員卡片」、「客戶見證」這種相對靜態的內容區塊，那 ACF Blocks 絕對是一個高效、務實的選擇，我們在ACF 終極指南中有更深入的介紹。

工程師的囉嗦時間：常見陷阱與最佳實踐

開發自訂區塊有幾個坑，我先幫你踩了，希望你不要再掉進去：

• 絕對不要隨意修改 `save.js` 的輸出： 一旦你的區塊已經在網站上被使用，如果你修改了 `save` 函式回傳的 HTML 結構，會導致所有舊的區塊在後台顯示「此區塊包含非預期的或無效的內容」錯誤。這是一個大災難。如果真的需要修改，你必須學習如何撰寫「棄用 (Deprecation)」邏輯，讓 WordPress 知道如何將舊的結構轉換成新的。
• 保持區塊的單一職責： 不要試圖做一個萬能的「超級區塊」，那只會讓設定變得異常複雜。讓每個區塊專注做好一件事。需要組合功能時，應該使用區塊的「內部區塊 (InnerBlocks)」功能。
• 善用核心元件庫： WordPress 提供了一系列的 UI 元件庫（`@wordpress/components`），例如按鈕、下拉選單、顏色選擇器等等。盡量使用這些核心元件，可以讓你的區塊後台介面和 WordPress 整體風格保持一致。
• 安全！安全！安全！： 雖然是在 JavaScript 中操作，但最終資料還是會存到資料庫並顯示在前端。對於任何使用者可輸入的內容，都要抱持著懷疑的態度，做好該有的清理（Sanitization）和跳脫（Escaping）。

從短代碼的混沌，到區塊編輯器的秩序，Gutenberg Block 自訂區塊開發無疑是現代 WordPress 開發者的必修課。它不僅能讓你打造出更專業、更易於維護的網站，更能徹底改變你與客戶之間的協作模式。今天我們只做了一個簡單的範例，但這已經為你打開了一扇通往無限可能的大門。希望這篇文章能成為你踏上這趟旅程的起點。

延伸閱讀

• 不只是文章和頁面！解放 WordPress 潛能，用 Custom Post Type 打造獨一無二的網站結構
• 別再被版型綁架！ACF 終極指南：用客製化欄位打造 WordPress 夢幻後台
• 告別手動 FTP 上傳地獄！用 GitHub Actions 打造 WordPress 自動化部署流程，優雅又高效！

如果你在開發自訂區塊時遇到了瓶頸，或是希望為你的企業網站打造一套專屬、高效的內容編輯系統，卻不知道從何下手？浪花科技團隊擁有豐富的 WordPress 深度客製化開發經驗，我們樂於協助你解決各種技術難題。歡迎點擊這裡，填寫表單與我們聯繫，讓我們一起打造出更強大的 WordPress 網站！