如何使用區塊API擴充套件WordPress核心區塊

2018 年，WordPress 在 5.0 版本中引入了 Gutenberg 編輯器，帶來了一種使用“區塊”構建頁面和帖子的新方法。起初，這些區塊非常基本，但經過多年的發展，它們已經提供了更大的靈活性和更好的編輯體驗。

不過，有時區塊並不能完全滿足你的需求。也許你想刪除某些功能、新增新功能、預設應用特定樣式，或者讓某些設定更容易訪問。在這種情況下，從頭開始建立一個自定義區塊似乎是一個不錯的選擇，但老實說，這對於一些小的調整來說實在是太麻煩了。如果能修改已經存在的區塊，豈不是更簡單？

這就是 Blocks API 的用武之地。本文將介紹如何使用 Blocks API 擴充套件 WordPress 核心區塊，並提供可用於實際專案的實用示例。

瞭解WordPress區塊API

WordPress 區塊 API 是區塊編輯器的基礎，允許開發人員建立、修改和擴充套件塊。API 提供了與區塊互動的多種方式。您可以

• 修改區塊設定 – 更改區塊屬性、預設值和行為。
• 新增或移除區塊支援 – 啟用或停用排版、顏色和間距等功能。
• 注入自定義控制元件 – 在區塊設定面板中新增新選項。
• 建立區塊變體 – 製作現有區塊的預配置版本，加快內容建立速度。

WordPress 中的每個區塊，無論是段落區塊、圖片區塊還是按鈕區塊，都由儲存在 block.json 檔案中的一組屬性和設定來定義。該檔案包含有關塊的後設資料，包括其名稱、類別、預設屬性和支援的功能。

WordPress允許您使用 PHP 或 JavaScript 修改這些值，但本文將解釋如何使用塊API中的過濾鉤子。這可以確保您的修改在伺服器上註冊，而不需要呼叫額外的JavaScript檔案。

例如，如果您想啟用或停用塊的某些功能，最好的方法是使用 PHP 中的 register_block_type_args 過濾器。這種方法可以動態調整區塊設定，而無需直接修改block.json檔案。

修改區塊支援

WordPress 區塊帶有預定義的支援，可以控制編輯器的選項。有些區塊，如圖片區塊（core/image），預設啟用了雙色調濾鏡，允許使用者應用顏色疊加。

帶有雙色調濾鏡的 WordPress 影像區塊。

然而，儘管媒體和文字區塊（core/media-text）允許使用者插入圖片，但它並不支援雙色調。這意味著，雖然您可以在獨立的影像塊中應用雙色調濾鏡，但當影像被放置在媒體和文字區塊中時，您就無法應用雙色調濾鏡了。

不支援雙色調的媒體和文字區塊

由於“媒體和文字”區塊可以包含圖片，因此啟用雙色調過濾器是合理的。我們可以透過修改 supports 陣列並指定正確的 CSS 選擇器來啟用雙色調濾鏡，這樣過濾器就能正確應用了。我們可以使用 PHP 中的 register_block_type_args 過濾器啟用它。

將以下程式碼新增到主題的 functions.php 檔案中：

重要提示：如果您要將此新增到主題的 functions.php 檔案中，最好在子主題中新增，以防主題更新時丟失更改。

function enable_duotone_for_media_text_block($args, $block_type) {
// Only modify the Media & Text block
if ( 'core/media-text' === $block_type ) {
$args['supports'] ??= [];
$args['supports']['filter'] ??= [];
$args['supports']['filter']['duotone'] = true;
$args['selectors'] ??= [];
$args['selectors']['filter'] ??= [];
$args['selectors']['filter']['duotone'] = '.wp-block-media-text .wp-block-media-text__media';
}
return $args;
}
add_filter('register_block_type_args', 'enable_duotone_for_media_text_block', 10, 2);

上面的程式碼在 supports 陣列中啟用了雙色過濾器，並定義了正確的 CSS 選擇器，以便將雙色效果應用到 Media & Text 塊中的圖片。add_filter() 函式使用 10 作為優先順序（過濾器執行時），並使用 2 來指定傳遞的引數數（$args,$block_type ）。

儲存檔案並重新載入後，您將在“過濾器”部分看到可用的 Duotone 控制元件。

啟用雙色調濾鏡

使用 register_block_type_args 為媒體和文字塊啟用雙色調是動態修改區塊行為的有效方法。不過，WordPress還提供了另一種修改區塊設定的方法：使用 block_type_metadata  覆蓋區塊後設資料。

這兩種方法都可以自定義區塊，但它們在區塊註冊過程的不同階段起作用。

例如，我們想調整段落塊（core/paragraph），使其只支援邊距調整並停用填充。一種方法是使用 register_block_type_args ：

function modify_paragraph_spacing_args($args, $block_type) {
if ($block_type === 'core/paragraph') {
$args['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $args;
}
add_filter('register_block_type_args', 'modify_paragraph_spacing_args', 10, 2);

這種方法在大多數情況下都很有效，但由於它是在區塊已註冊後才對其進行修改，因此有時會被後來修改同一區塊的其他外掛或主題所覆蓋。

在這種情況下，一種更有條理的方法是使用 block_type_metadata 直接覆蓋區塊的後設資料：

function mytheme_modify_paragraph_spacing($metadata) {
if ($metadata['name'] === 'core/paragraph') {
$metadata['supports']['spacing'] = [
'margin' => true,
'padding' => false
];
}
return $metadata;
}
add_filter('block_type_metadata', 'mytheme_modify_paragraph_spacing');

這兩種方法在本質上都沒有優劣之分，只是取決於你想在什麼時候修改區塊，以及你希望這種修改有多持久。

註冊區塊樣式

許多 WordPress 區塊都有預定義的樣式，使用者可以在編輯器中進行選擇。圖片區塊（core/image）就是一個很好的例子，它預設包含一個圓角樣式。然而，預設的圓角往往過於極端，使圖片看起來更像一個橢圓形，而不是一個風格整齊的元素。

預設圓角樣式

與手動調整每張圖片的邊框半徑相比，更好的方法是自定義圓角樣式，使其應用更精細的圓角半徑–也許可以新增一個微妙的陰影來營造現代感。這樣，使用者只需點選一個按鈕，就能應用精心設計的樣式，而無需每次都手動調整設定。

讓我們使用影像塊中的圓角樣式，對其進行自定義，使邊角略微變圓，而不是過度彎曲，並新增一個微妙的方框陰影，使其看起來更加精緻。

由於塊編輯器允許註冊和取消註冊塊樣式，因此我們可以刪除預設的圓角樣式，取而代之的是自定義版本。

具體方法如下：

function modify_image_block_rounded_style() {
// Remove the default "Rounded" style
unregister_block_style( 'core/image', 'rounded' );
// Register a new "Rounded" style with custom CSS
register_block_style(
'core/image',
array(
'name'         => 'rounded',
'label'        => __( 'Rounded', 'your-text-domain' ),
'inline_style' => '
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjust this value */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Optional shadow */
}
',
)
);
}
add_action( 'init', 'modify_image_block_rounded_style' );

該程式碼將預設的過於圓潤的樣式替換為精緻的版本，應用 border-radius: 20px; 使邊角更加柔和，並應用 box-shadow 使邊角得到微妙的提升。

精緻的圓角樣式

使用外部CSS檔案代替內聯樣式

雖然內聯樣式對於簡單樣式很有效，但對於可維護性來說並不理想。更好的方法是在外部 CSS 檔案中定義樣式，然後將其呼叫。

為此，請建立一個新的 CSS 檔案，例如，custom-block-styles.css，並將此新增到該檔案中：

/* Custom Rounded Image Block Style */
.wp-block-image.is-style-rounded img {
border-radius: 20px; /* Adjusted rounded corners */
box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1); /* Subtle shadow */
}

接下來，在functions.php 中呼叫 CSS 檔案：

function enqueue_custom_block_styles() {
wp_enqueue_style(
'custom-block-styles',
get_template_directory_uri() . '/css/custom-block-styles.css',
array(),
'1.0'
);
}
add_action('wp_enqueue_scripts', 'enqueue_custom_block_styles');
add_action('enqueue_block_editor_assets', 'enqueue_custom_block_styles');

現在，您可以不使用內聯樣式，而直接在 PHP 中嵌入 CSS 來註冊樣式：

register_block_style(
'core/image',
array(
'name'  => 'rounded',
'label' => __( 'Rounded', 'your-text-domain' ),
'style_handle' => 'custom-block-styles'
)
);

這樣，您就可以在不接觸 PHP 的情況下修改樣式。

註冊區塊變體

區塊變體可讓你建立具有自定義設定的預定義區塊版本，使使用者只需單擊一下就能更輕鬆地應用一致的設計。變體允許你插入一個已經應用了正確屬性、樣式或配置的塊，而不是每次都手動修改塊的設定。

WordPress 的一些核心區塊實際上就是這樣工作的。嵌入區塊並不是一個單獨的區塊，它是針對 YouTube、Twitter 和 Spotify 等不同平臺的一組變體。Row 區塊和 Stack 區塊也只是 Group 區塊的變體，每個塊都有不同的佈局設定。

這種方法保持了模組化，允許 WordPress 在使用共享底層結構的同時提供量身定製的體驗。

建立引言區塊的“推薦”變體

雖然 WordPress 沒有專門的“推薦”區塊，但“引言”區塊（core/quote）可用於此目的。我們可以定義“引言”區塊的“推薦”變體，而不是讓使用者手動新增圖片、對齊文字和格式化所有內容。

這種變體會自動包含一個圖片區塊、一個引用區塊和兩個段落區塊，分別用於標註人名和公司。這樣就能確保每篇推薦信都遵循相同的結構格式，而無需額外調整。

要在 WordPress 中註冊一個區塊變體，我們使用 JavaScript 中的 registerBlockVariation()。由於區塊變體是在客戶端處理的，因此我們需要呼叫一個 JavaScript 檔案來註冊我們的自定義推薦變體。

要實現這一點，請建立一個 JavaScript 檔案（如custom-block-variations.js ）來定義“引言”區塊的“推薦”變體。您可以在主題的 assets/js/ 目錄中建立該檔案，並新增以下程式碼：

wp.domReady(() => {
wp.blocks.registerBlockVariation(
'core/quote',
{
name: 'testimonial',
title: 'Testimonial',
description: 'A variation of the Quote block for testimonials.',
category: 'text',
attributes: {
className: 'is-style-testimonial',
},
innerBlocks: [
['core/image', { align: 'center', width: 100, height: 100 }],
['core/quote'],
['core/paragraph', { placeholder: 'Name', align: 'center', fontSize: 'medium', className: 'testimonial-name' }],
['core/paragraph', { placeholder: 'Company / Role', align: 'center', fontSize: 'small', className: 'testimonial-company' }]
],
scope: ['inserter'],
}
);
// Inject inline styles for the editor preview
const style = document.createElement('style');
style.innerHTML = `
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial p {
margin-bottom: 12px;
font-size: 1.1em;
}
.wp-block-quote.is-style-testimonial cite {
font-weight: bold;
display: block;
margin-top: 10px;
color: #0073aa;
}
.wp-block-quote.is-style-testimonial .wp-block-image {
display: flex;
justify-content: center;
margin: 0 auto 12px;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
`;
document.head.appendChild(style);
});

在上面的程式碼中，registerBlockVariation() 定義了“引語”區塊的“推薦”變體，預先載入了一個圖片區塊、一個“引語”區塊和兩個段落區塊，分別代表個人姓名和公司。圖片區塊以 100×100 畫素為中心，用於顯示統一的個人資料圖片，而引用語區塊則保持不變，作為推薦文字。

自定義類（is-style-testimonial）被應用於樣式設計，使塊具有淺色背景、微妙的陰影和居中的文字。去掉了預設的左邊框，圖片保持長寬比，邊角略呈圓角，看起來更有質感。

接下來，由於 JavaScript 檔案需要在區塊編輯器中載入，我們必須在 functions.php 中呼叫 JavaScript 檔案。

function enqueue_custom_block_variations() {
wp_enqueue_script(
'custom-block-variations',
get_template_directory_uri() . '/assets/js/custom-block-variations.js',
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
filemtime( get_template_directory() . '/assets/js/custom-block-variations.js' ),
true
);
}
add_action( 'enqueue_block_editor_assets', 'enqueue_custom_block_variations' );

這將確保“推薦”區塊的變化出現在區塊編輯器中。

JavaScript 程式碼可確保區塊在編輯器中顯示正確，但我們還需要在前端應用樣式，以便在釋出時正確顯示推薦語。在 functions.php 中新增以下程式碼

function register_testimonial_block_style() {
register_block_style(
'core/quote',
array(
'name'  => 'testimonial',
'label' => __( 'Testimonial', 'your-text-domain' ),
'inline_style' => '
.wp-block-quote.is-style-testimonial {
background-color: #f9f9f9;
padding: 24px;
border: none !important;
border-radius: 8px;
text-align: center;
font-size: 1.2em;
font-style: normal;
color: #333;
box-shadow: 0px 4px 10px rgba(0, 0, 0, 0.1);
display: flex;
flex-direction: column;
align-items: center;
}
.wp-block-quote.is-style-testimonial .wp-block-image img {
width: 100px;
height: 100px;
object-fit: cover;
border-radius: 12px;
}
.wp-block-quote.is-style-testimonial .testimonial-name {
font-weight: bold;
font-size: 1.2em;
margin-top: 12px;
color: #222;
}
.wp-block-quote.is-style-testimonial .testimonial-company {
font-size: 0.9em;
color: #555;
}
',
)
);
}
add_action( 'init', 'register_testimonial_block_style' );

現在，每當使用者插入一個推薦語區塊時，它已經包含了圖片、引語、姓名和公司欄位，所有欄位都已預先格式化，並且樣式正確。這樣就不需要手動調整，確保每個推薦都遵循同樣簡潔和專業的結構。

推薦語區塊變體

這個區塊變體沒有強迫使用者從頭開始建立推薦信，而是提供了一個簡化的工作流程，在保持網站設計一致性的同時增強了內容建立能力。

高階用例：結合支援和樣式 API 建立品牌按鈕

既然您已經知道了每個 API 的功能和工作原理，我們為什麼不再進一步呢？與其單獨使用 Supports API 或 Styles API，我們可以一起使用它們來解決一個問題：保持設計的一致性，同時為使用者提供應用正確樣式的結構化方法。

讓我們考慮一個現實世界中的場景。一家公司希望其網站上的所有按鈕都嚴格遵循品牌準則。他們不希望使用者隨意選擇顏色、改變填充或應用時髦的排版。不過，他們也希望按鈕具有靈活性，因此使用者可以在兩種預先批准的按鈕樣式中進行選擇：

1. 主按鈕 – 主要的行動號召按鈕，採用純色背景和粗體樣式。
2. 副按鈕 -更微妙的勾勒按鈕，通常用於次要操作。

為此，我們需要

• 使用樣式 API 定義兩種按鈕樣式。
• 使用支援 API 刪除不必要的設定，確保使用者不會透過更改顏色、間距或排版來手動覆蓋品牌。

透過將這兩個 API 結合使用，我們既能提供結構化的選擇，又能防止使用者破壞設計系統。

Step 1：定義自定義按鈕樣式

首先在 functions.php 檔案中新增以下程式碼：

function register_custom_button_styles() {
register_block_style(
'core/button',
array(
'name'  => 'primary-button',
'label' => __( 'Primary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-primary-button .wp-block-button__link {
background-color: #4D4D4D;
color: #ffffff;
padding: 12px 24px;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: 2px 2px 6px rgba(0, 0, 0, 0.1);
}
',
)
);
register_block_style(
'core/button',
array(
'name'  => 'secondary-button',
'label' => __( 'Secondary Button', 'your-text-domain' ),
'inline_style' => '
.wp-block-button.is-style-secondary-button .wp-block-button__link {
background-color: transparent;
color: #4D4D4D;
padding: 12px 24px;
border: 1px solid #4D4D4D;
border-radius: 4px;
font-size: 1em;
font-weight: 500;
text-transform: none;
box-shadow: none;
}
',
)
);
}
add_action( 'init', 'register_custom_button_styles' );

現在，當使用者插入按鈕塊時，他們會看到主按鈕和副按鈕作為樣式選擇。

自定義按鈕樣式

主按鈕的背景是純深灰色，而次按鈕的背景是帶邊框的透明背景。兩個按鈕的填充、邊框半徑和字型樣式都保持一致，確保整個網站的專業外觀。

Step 2：限制按鈕定製

雖然按鈕樣式現在是預定義的，但使用者仍然可以使用 WordPress 的塊編輯器設定手動覆蓋它們。如果他們更改了顏色、襯墊或排版，按鈕就可能不再符合品牌準則。

我們可以使用支援 API 停用這些自定義選項，防止使用者進行意外更改。將此新增到 functions.php 中：

function restrict_button_customization($args, $block_type) {
if ($block_type === 'core/button') {
// Disable specific color settings (text, background, link)
$args['supports']['color'] = [
'text'       => false, 
'background' => false, 
'link'       => false,  
];
// Disable typography settings (font size, font weight, line height)
$args['supports']['typography'] = false;
// Disable spacing settings (padding, margin)
$args['supports']['spacing'] = false;
}
return $args;
}
add_filter('register_block_type_args', 'restrict_button_customization', 10, 2);

有了這一點：

• 使用者無法更改按鈕顏色，因此所有按鈕都必須符合品牌的配色方案。
• 刪除排版控制，保持文字格式一致。
• 間距調整被停用，使用者無法修改填充和邊距。

主按鈕樣式

現在，使用者不用再隨意建立按鈕樣式，只需在主樣式和次樣式之間進行選擇，從而保持設計的專業性和條理性。

小結

我們只是從表面上瞭解了 WordPress 區塊定製的可能性。WordPress 提供了大量的應用程式介面（API），可以輕鬆擴充套件和自定義區塊，讓開發人員可以定製編輯器體驗，同時保持結構合理和使用者友好。