WordPress嘅古騰堡區塊編輯器（Gutenberg Block Editor）徹底改變咗內容創建嘅方式，將頁面構建嘅靈活性同控制權直接交到編輯者手中。對於開發者嚟講，呢個意味住一個全新嘅、以 React 同現代 JavaScript 為核心嘅開發範式。本文將會深入探討點樣從零開始創建自定義區塊，並進階到開發動態區塊、應用區塊變體等高級主題，旨在為你提供一份全面嘅實戰開發指南。
理解區塊編輯器嘅核心架構
古騰堡編輯器並唔係一個單一嘅整體應用，而係一個由多個獨立套件（Packages）組成嘅生態系統。理解其架構係進行有效開發嘅基礎。
編輯器同數據層嘅分離
編輯器界面本身同 WordPress 嘅數據層係分開嘅。核心嘅 @wordpress/editor 套件提供咗編輯器嘅 UI 組件，而 @wordpress/data 套件就實現咗類似 Redux 嘅狀態管理。咁樣分開令開發者可以專注喺區塊嘅視圖同互動邏輯，數據持久化就由 WordPress 嘅核心機制自動處理。
推薦閱讀 掌握 WordPress 自訂文章類型：從創建到發布嘅完整實戰指南。
區塊嘅註冊同生命週期
每個區塊都需要透過 registerBlockType 函數進行註冊。呢個函數接受兩個參數：區塊嘅唯一名稱（例如 my-plugin/my-custom-block）同一個包含區塊所有配置資訊嘅物件。
註冊之後，區塊會經歷初始化、渲染、編輯、保存等生命週期。開發者主要透過定義 edit 同埋 save 兩個關鍵函數去控制區塊喺編輯器同前端嘅表現。
從零開始創建你第一個自定義區塊
我哋會創建一個簡單嘅「高亮提示」區塊，等用家可以加一個有背景色同標題嘅提示框。
設定開發環境同基礎檔案
首先，確保你嘅開發環境已經準備好。你需要 Node.js 同埋 npm 環境。喺插件目錄下創建一個新插件文件夾，例如 my-custom-blocks。喺呢個文件夾入面，創建以下核心文件：
- my-custom-blocks.php （插件主文件）
- package.json (用嚟管理 Node 依賴同埋構建腳本)
- src/ 目錄（用於存放源代碼）
- build/ 目錄（構建工具輸出目錄，由 WordPress 讀取）
在 package.json 中，配置構建腳本並引入 @wordpress/scripts 包，佢可以極大地簡化 Webpack、Babel 等工具嘅配置。
{
"name": "my-custom-blocks",
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
"devDependencies": {
"@wordpress/scripts": "^26.0.0"
}
}喺插件主檔案 my-custom-blocks.php 入面，你需要用 register_block_type 函數嚟話畀 WordPress 知從 build 目錄載入區塊嘅資產。
推薦閱讀 WordPress 主題開發指南:從零開始打造高效能自訂主題。
<?php
/**
* Plugin Name: My Custom Blocks
*/
function my_custom_blocks_register_block() {
register_block_type( __DIR__ . '/build/highlight-box' );
}
add_action( 'init', 'my_custom_blocks_register_block' );編寫區塊嘅 JavaScript 源代碼
在 src 喺目錄下創建 highlight-box/index.js 檔案。呢個係區塊嘅主入口檔案。
import { registerBlockType } from '@wordpress/blocks';
import { RichText, useBlockProps, InspectorControls, ColorPalette } from '@wordpress/block-editor';
import { PanelBody, PanelRow } from '@wordpress/components';
registerBlockType('my-custom-blocks/highlight-box', {
title: '高亮提示框',
icon: 'warning', // 从 Dashicons 中选择
category: 'design',
attributes: {
title: {
type: 'string',
source: 'html',
selector: '.highlight-title',
},
content: {
type: 'string',
source: 'html',
selector: '.highlight-content',
},
backgroundColor: {
type: 'string',
default: '#fff3cd',
},
},
edit: ({ attributes, setAttributes }) => {
const blockProps = useBlockProps();
const { title, content, backgroundColor } = attributes;
const onChangeTitle = (newTitle) => {
setAttributes({ title: newTitle });
};
const onChangeContent = (newContent) => {
setAttributes({ content: newContent });
};
const onChangeBackgroundColor = (newColor) => {
setAttributes({ backgroundColor: newColor });
};
return (
<>
<inspectorcontrols>
<panelbody title="顏色設定">
<panelrow>
<colorpalette
value="{backgroundColor}"
onchange="{onChangeBackgroundColor}"
/>
</panelrow>
</panelbody>
</inspectorcontrols>
<div {...blockprops} style="{{" backgroundcolor, padding: '20px', borderradius: '5px' }}>
<richtext
tagname="h3"
classname="highlight-title"
onchange="{onChangeTitle}"
value="{title}"
placeholder="输入标题..."
/>
<richtext
tagname="p"
classname="highlight-content"
onchange="{onChangeContent}"
value="{content}"
placeholder="输入提示内容..."
/>
</div>
</>
);
},
save: ({ attributes }) => {
const blockProps = useBlockProps.save();
const { title, content, backgroundColor } = attributes;
return (
<div {...blockprops} style="{{" backgroundcolor, padding: '20px', borderradius: '5px' }}>
<RichText.Content tagName="h3" className="highlight-title" value={title} />
<RichText.Content tagName="p" className="highlight-content" value={content} />
</div>
);
},
});運行 npm start 開始開發模式（監聽檔案變化）或者 npm run build 進行生產構建。之後喺 WordPress 編輯器入面，你就可以喺「設計」分類下面搵到同用到呢個「高亮提示框」區塊喇。
進階開發：動態區塊同伺服器端渲染
靜態區塊嘅內容會直接保存喺文章內容入面。不過對於需要實時數據（例如最新文章列表、用戶資訊）嘅區塊，我哋就需要創建動態區塊。動態區塊喺保存嘅時候只會儲存一啲屬性（例如文章數量），前端顯示嘅時候就會透過 PHP 模板動態生成內容。
將靜態區塊轉為動態區塊
首先，修改區塊嘅註冊配置，將 save 函數改為返回 null，並加入一個 render_callback 屬性。
// 在 registerBlockType 的配置对象中
save: () => {
return null; // 动态区块不在内容中保存 HTML
},跟住，喺 PHP 嗰邊更新註冊代碼，指定渲染回調函數。
function my_custom_blocks_register_dynamic_block() {
register_block_type( __DIR__ . '/build/latest-posts', [
'render_callback' => 'my_custom_blocks_render_latest_posts'
] );
}
add_action( 'init', 'my_custom_blocks_register_dynamic_block' );
function my_custom_blocks_render_latest_posts( $attributes ) {
$posts = get_posts( [
'posts_per_page' => $attributes['numberOfPosts'] ?? 5,
] );
if ( empty( $posts ) ) {
return '<p>暫時冇文章。</p>';
}
$output = '<ul class="wp-block-my-custom-blocks-latest-posts">';
foreach ( $posts as $post ) {
$output .= sprintf(
'<li><a href="/yue/%s/">%s</a></li>',
esc_url( get_permalink( $post ) ),
esc_html( get_the_title( $post ) )
);
}
$output .= '</ul>';
return $output;
}用區塊模板檔案進行渲染
對於更加複雜嘅動態區塊，建議用模板檔案。喺插件目錄建立 templates/latest-posts.php，將上面嘅渲染邏輯搬入呢個檔案。然後喺 render_callback 入面用 ob_get_clean 同埋 include 嚟載入模板，咁樣令 PHP 同 HTML 邏輯更清晰、易於維護。
推薦閱讀 WooCommerce 插件使用教程：由安裝設定到店鋪營運完整指南。
進階主題同埋最佳實踐
掌握咗基礎同動態區塊之後，以下主題可以幫你開發出更強大、更專業嘅區塊。
實現區塊嘅變體功能
區塊變體（Block Variations）容許你基於一個基礎區塊創建多個預設樣式或者配置。例如，為「高亮提示框」創建「成功」、「警告」、「錯誤」等變體。
import { registerBlockVariation } from '@wordpress/blocks';
registerBlockVariation('my-custom-blocks/highlight-box', [
{
name: 'success',
title: '成功提示',
icon: 'yes-alt',
attributes: {
title: '操作成功',
backgroundColor: '#d4edda',
},
isDefault: false,
},
{
name: 'error',
title: '错误警告',
icon: 'dismiss',
attributes: {
title: '发生错误',
backgroundColor: '#f8d7da',
},
},
]);利用區塊樣式同編輯器樣式
使用 registerBlockStyle 函數可以為區塊加上唔同嘅視覺樣式，用家可以喺側邊欄切換。同時，用 add_editor_style 可以確保編輯器入面嘅預覽同前端樣式保持一致，提供所見即所得嘅體驗。
效能優化同代碼分割
隨住區塊增多，將所有JavaScript打包到一個檔案會影響加載效能。可以利用 @wordpress/dependency-extraction-webpack-plugin（已經包含喺 @wordpress/scripts 入面）確保正確聲明對WordPress套件嘅外部依賴。對於大型外掛，可以考慮按需加載或者代碼分割技術。
摘要
古騰堡區塊編輯器嘅開發係一個融合咗現代前端技術（React, JSX, Webpack）同傳統WordPress PHP知識嘅過程。從理解其架構開始，透過建立靜態區塊掌握核心API，再進階到動態區塊處理動態數據，最後透過區塊變體、樣式等高級功能提升用戶體驗同開發效率。遵循最佳實踐，例如清晰嘅代碼組織、效能優化同充分嘅國際化準備，你將能夠構建出強大、可維護且用戶友好嘅自訂區塊，充分釋放古騰堡編輯器嘅潛力。
常見問題
開發古騰堡區塊必須使用 React 嗎？
係嘅，目前古騰堡編輯器嘅官方開發方式完全基於 React。雖然理論上可以用其他框架，但 WordPress 核心提供嘅所有組件、鉤子同工具都圍繞 React 生態構建，用其他框架會帶嚟極大嘅複雜性同兼容性問題。
點樣為我嘅區塊添加自定義側邊欄控件？
你可以用 <code>InspectorControls</code> 組件。喺區塊嘅 edit 喺函數入面，將佢同主預覽內容一齊傳返出去。喺 <code>InspectorControls</code> 內部，你可以用 <code>PanelBody</code>、<code>TextControl</code>、<code>SelectControl</code>、<code>RangeControl</code></code> 等来自 @wordpress/components` 呢個包嘅組件嚟整豐富嘅設定介面。
動態區塊同靜態區塊喺效能上有咩分別？
靜態區塊嘅 HTML 內容直接保存喺數據庫嘅帖子內容入面，所以前端加載速度好快，但係就唔可以包含動態數據。動態區塊喺渲染嗰陣需要執行 PHP 代碼查詢數據庫，所以會有少少效能開銷，但係就可以提供實時數據。對於唔常變嘅內容，可以考慮用靜態區塊配合定期緩存策略；對於需要高度實時性嘅內容，就一定要用動態區塊。
我係咪可以喺傳統嘅小工具區域或者文章元框入面用區塊？
可以，呢個叫做「區塊小工具」同埋「區塊元框」。由 WordPress 5.8 開始，小工具區域都完全由古騰堡區塊編輯器驅動。你亦都可以用 register_block_type 的 widget_types 參數（或者相關 API）嚟令區塊喺小工具編輯器入面可以用到。對於文章元框，可以用 `register_post_meta API 並結合區塊嚟創建更直觀嘅元數據編輯界面。
下一步應該點做?
延伸閱讀及實用知識
以下內容與本文主題相關,適合進一步閱讀。一般而言,最好由與你目前問題最緊密相關的文章開始,然後逐步擴展到周邊主題。