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="/zh-hk/%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，再進階到動態區塊處理動態數據，最後通過區塊變體、樣式等高級功能提升用户體驗和開發效率。遵循最佳實踐，如清晰的代碼組織、性能優化和充分的國際化準備，你將能構建出強大、可維護且用户友好的自定義區塊，充分釋放古騰堡編輯器的潛力。
常见问题解答（FAQ）
開發古騰堡區塊必須使用 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 並結合區塊來創建更直觀的元數據編輯界面。
接下来，我该怎么做呢？
延伸阅读与实用知识
下方这些内容与本文主题相关，适合继续深入阅读。建议先从与你当前问题最相关的文章开始看起，然后再逐步扩展到相关主题，这样通常效果会更好。