WordPress開發人員需要了解的theme.json中的block屬性

WordPress 中引入的全站編輯（FSE）功能凸顯了theme.json檔案日益增長的重要性。現在，您需要了解全新的層次和結構，以及幫助您建立設計的各種屬性。特別是，如果你想建立具有獨特區塊的現代、靈活的 WordPress 主題，theme.json中的blocks屬性是必不可少的。

在本指南中，我們將探討theme.json中的blocks屬性的來龍去脈，這樣你就可以使用、設計和樣式化 Block，從而建立更加動態和可定製的 WordPress 體驗。

瞭解 theme.json 中的 block 屬性

在深入瞭解blocks屬性的複雜性之前，讓我們先了解一下它在theme.json和 WordPress 主題開發中的作用。

二〇二三主題的theme.json檔案

首先，theme.json是一個配置檔案，可讓您為主題定義全域性樣式和設定。通過這個“中心樞紐”，您可以控制主題外觀和行為的各個方面，包括排版、顏色和佈局選項。不過，它的功能遠不止為你提供程式化的外觀調整。

通過blocks屬性，你可以對單個區塊型別而不是整個網站進行細化控制。你可以為特定區塊定義預設樣式、設定和行為，從而確保整個主題的一致性和網站所有者的靈活性。

區塊屬性與全站編輯之間的關係

FSE 是一種以區塊為核心構建網站的更加視覺化的方法。在前端，您可以使用整個網站的大部分樣式和自定義選項：

WordPress 中完整的網站編輯介面

出於以下幾個原因，blocks屬性是theme.json檔案的重要組成部分：

• 它提供了定義區塊樣式和設定的標準化方法。
• 你可以從一個程式化的基礎上建立具有凝聚力的設計系統。
• 無需自定義CSS，就能更好地控制區塊的外觀。
• 該屬性可幫助你建立區塊模式和模板。

開發人員可以使用blocks屬性建立主題，充分利用完整的網站編輯功能。

如何構建區塊屬性（及其語法）

在結構和語法方面，blocks屬性提供了標準化的幫助。你總是將其巢狀在settings物件中：

{
"version": 3,
"settings": {
"blocks": {
"core/paragraph": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
]
…

上例定義了段落區塊的自定義字型大小。分解關鍵元件非常簡單：

• 你可以在settings物件下巢狀blocks屬性。
• 每個區塊型別都有一個名稱空間和名稱（此處為core/paragraph）。
• 然後在物件中指定區塊的設定。

這些設定包括全域性樣式的大部分設定。例如，它們可以包括排版、顏色、間距等。

配置全域性區塊設定

讓我們看看如何定義全域性設定，然後再看看這對 blocks 屬性有何影響。這樣，你就能在整個主題中建立起一致的設計基礎。

{
"version": 3,
"settings": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "13px"
},
{
"name": "Medium",
"slug": "medium",
"size": "20px"
}
…

在本例中，我們定義了所有區塊都可使用的全域性字型大小。在 WordPress 網站編輯器中，您可以在排版>元素 >文字頁面中找到這些選項：

網站編輯器中也可以訪問theme.json中的大部分排版設定

您在theme.json中定義的每種字型大小都與此處的大小選項之一相關：

您可以在theme.json檔案中設定字型大小預設

當然，還有很多其他方法可以從這裡定製主題。我們的想法是建立一個適用於 80% 使用情況的全域性設計。

使用blocks屬性，你可以覆蓋這些核心區塊樣式，以覆蓋最後的 20%。網站編輯器中的樣式螢幕還可以讓你自定義每個區塊的設計設定：

網站編輯器允許您編輯 WordPress 所有核心區塊的設定

這對終端使用者來說非常好，但對開發人員來說價值不大。我們的重點是使用theme.json來處理blocks屬性。

如何自定義單個區塊型別

雖然全域性設定對於保持一致性非常重要，但真正的威力在於blocks屬性的自定義範圍。通過這種細粒度的設定，你可以定製特定區塊的外觀和行為，使其與主題設計相匹配，就像網站編輯器一樣。

讓我們以自定義主題的標題區塊為例：

{
"version": 3,
"settings": {
"blocks": {
"core/heading": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "20px"
},
{
"name": "Medium",
"slug": "medium",
"size": "30px"
},
{
"name": "Large",
"slug": "large",
"size": "40px"
}
],
"fontWeight": "bold"
},
"color": {
"palette": [
{
"name": "Heading Primary",
"slug": "heading-primary",
"color": "#333333"
},
{
"name": "Heading Secondary",
"slug": "heading-secondary",
"color": "#666666"
}
]
…

您可以看到，這些屬性反映了您如何進行全域性更改。讓我們總結一下我們正在做的事情：

• 我們為標題定義了特定的字型大小，並將其分配給大小標籤。
• 所有標題的字型權重都是粗體。
• 這些標題還將獲得自定義調色盤。

這將確保我們的標題在整個設計中具有一致的外觀。當我們不知道終端使用者將如何使用這些元素時，我們還可以控制這些元素，這將進一步提高設計的一致性。

使用正確的名稱空間和標題組合

呼叫區塊型別時，使用正確的名稱空間和標題組合至關重要。否則，你的更改將無法應用到你想要針對的區塊。

每個區塊都有一個名稱空間和一個標題。WordPress 核心區塊通常使用core名稱空間。語段則是區塊的名稱：

…
"blocks": {
"core/image": {
…

如果需要知道某個區塊的標籤，可以檢視其特定的 block.json 檔案。你可以在 wp-includes/blocks 目錄中找到該檔案。這裡有多個資料夾，每個資料夾都包含一個 block.json 檔案。在每個資料夾中，區塊的名稱空間和標籤應位於檔案頂部附近：

block.json檔案將包含每個區塊的關鍵後設資料

如果瀏覽這些目錄，你會發現 wp-includes 目錄也有自己的 theme.json 檔案。雖然這可能看起來令人困惑，但解釋起來卻很簡單。

為什麼預設情況下主題.json檔案包含自定義區塊設定

WordPress自己的 theme.json 檔案初看起來可能很奇怪，因為它不是一個主題。不過，這並非偶然。主要原因是為了支援與舊版本 WordPress 的向後相容性。

例如，按鈕區塊設定了邊框半徑：

…
"blocks": {
"core/button": {
"border": {
"radius": true
}
},
…

其他區塊也會有類似的設定，以幫助不同版本的 WordPress 保持一致。但是，如果您沒有意識到這一點，就可能會造成問題。

如果你試圖定義全域性設定，卻不知道為什麼這些更改不適用於特定的區塊，那麼向後相容性可能就是答案。當然，你也可以在自己的 theme.json 檔案中覆蓋這些設定。

使用 theme.json 開發自定義區塊

theme.json 檔案非常適合自定義現有的區塊，但它的功能也可以擴充套件到自定義區塊的開發。您可以利用 theme.json 為任何自定義區塊定義預設樣式和設定。這可以幫助你實現與主題設計的無縫整合。

不過，首先你必須構建區塊本身。這超出了本文的討論範圍，但總的來說，有以下幾個方面：

• 為程式區塊搭建腳手架。這包括建立本地開發環境，併為整個程式區塊建立檔案結構。
• 更新 block.json 檔案。在此，您需要更改程式區塊標識並新增支援。後者是宣告支援特定 WordPress 功能的方法。例如，您可以處理對齊方式、實現錨欄位、使用各種排版設定等。
• 調整區塊的 JavaScript 檔案。index.js 和 edit.js 都需要程式碼來告訴WordPress區塊的功能，並讓它出現在網站編輯器中。

您可能還需要編輯 render.php、新增靜態渲染等一系列工作。此時，你可以像使用其他區塊一樣，對 theme.json 進行任何風格上的修改。現在，讓我們仔細看看 block.json 檔案。

block.json 檔案

這個檔案被 WordPress 開發團隊稱為在伺服器端和客戶端註冊區塊的標準方式。這裡包含的後設資料會告訴 WordPress 有關區塊型別及其支援檔案的所有資訊：

{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "my-plugin/notice",
"title": "Notice",
"category": "text",
"parent": [ "core/group" ],
"icon": "star",
"description": "Shows warning, error or success notices...",
"keywords": [ "alert", "message" ],
"version": "1.0.3",
"textdomain": "my-plugin",
"attributes": {
"message": {
"type": "string",
"source": "html",
"selector": ".message"
}
},
…

它類似於放在主題和外掛 PHP 檔案頂部的後設資料。雖然該檔案只使用 JSON 資料，但您仍然可以通過 PHP、JavaScript 和 CSS 共享程式碼：

…
"editorScript": "file:./index.js",
"script": "file:./script.js",
"viewScript": [ "file:./view.js", "example-shared-view-script" ],
"editorStyle": "file:./index.css",
"style": [ "file:./style.css", "example-shared-style" ],
"viewStyle": [ "file:./view.css", "example-view-style" ],
"render": "file:./render.php"
…

我們將在稍後的變體部分討論這個問題。在本節的最後，您需要了解如何在 WordPress 中將自定義區塊設定為預設值。有幾種方法可以實現這一點。經典的方法是註冊一個自定義文章型別，並在其中包含區塊。不過，還有其他一些方法。

例如，你可以更新現有的文章型別，新增一個區塊模板。下面是一個簡單的例子：

…
function load_post_type_patterns() {
// Define an initial pattern for the 'HypnoToad' post type
$post_type_object = get_post_type_object( 'hypnoToad' );
$post_type_object->template = array(
array(
'core/block',
…

還有一種方法是呼叫 default_content 鉤子，並使用標記定義區塊：

function toad_content( $content, $post ) {
if ( $post->post_type === 'hypnoToad' ) {
$content ='<!-- wp:columns -->
<div class="wp-block-columns"><!-- wp:column →
<div class="wp-block-column"><!-- wp:paragraph -->
<p></p>
<!-- /wp:paragraph --></div>
<!-- /wp:column -->
<!-- wp:column -->
<div class="wp-block-column"><!-- wp:paragraph -->
<p></p>
<!-- /wp:paragraph --></div>
<!-- /wp:column --></div>
<!-- /wp:columns -->';
}
return $content;
}
add_filter( 'default_content', 'toad_content', 10, 2 );

當然，您不會只使用 JSON、HTML 和 PHP。您還會使用其他語言來幫助設計和互動。好訊息是，WordPress 為您提供了一種簡便的方法。

為您的區塊使用自定義 CSS 屬性

使用 theme.json 中的現有屬性、元素屬性和物件，您可以實現很多功能，但這並不能涵蓋所有的使用情況。該檔案提供的 custom 屬性將幫助你建立相關的 CSS 屬性：

{
"version": 3,
"settings": {
"custom": {
"toad": "hypno"
}
}
}

在這裡，你需要給出一個鍵值對，它在前端會變成一個 CSS 變數：

body {
--wp--custom--toad: hypno;
}

請注意，變數將使用雙連字元來分隔其元素。一般情況下，你總是會看到--wp--custom--，然後在末尾標記關鍵字。有時，你會使用駝峰式大小寫定義變數和屬性：

{
"version": 3,
"settings": {
"custom": {
"hypnoToad": "active"
}
}
}

在這裡，WordPress 將使用連字元來分隔單詞：

body {
--wp--custom--hypno-toad: active;
}

有了 custom 屬性和 block.json，你就完全可以按照自己的想法來構建區塊，包括你可能想包含的任何變化。

快速瞭解區塊、樣式和區塊風格變體

在使用 blocks 屬性設計樣式之前，我們先來了解一下樣式的變化。你的設計有幾種不同的變化型別，而命名約定可能會讓你使用錯誤的型別來滿足自己的需求。下面是不同型別的細分：

• 區塊變體。如果您的區塊有替代版本（想想一個區塊會顯示使用者設定的許多自定義連結），這就是區塊變體。社交媒體區塊就是一個很好的例子。
• 樣式變體。這些是在全域性網站上使用的 theme.json 的替代版本。我們在此不做介紹，但大多數區塊主題都為各種調色盤和排版設定提供了這些版本。
• 區塊風格變體。它採用了風格變體的核心功能，讓你可以為區塊建立其他設計。

你可能想知道是使用區塊變體還是區塊風格變體；答案並不複雜。如果你想在 theme.json 中或使用 CSS 進行更改，那麼就建立一個區塊樣式變體。其他任何情況都需要使用區塊變體。

區塊變體

對於區塊樣式變化，你需要使用 JavaScript 進行註冊。在主題目錄中建立一個檔案是個好主意，但它可以放在任何地方。只需一行即可在 JavaScript 檔案中註冊變體：

const registerBlockVariation = ( blockName, variation )

對於blockName，你也需要在這裡指定名稱空間，就像使用 block 屬性一樣。在 variation 物件中，你將新增名稱、標題、描述、變體是否預設啟用等資訊。要在站點編輯器中載入檔案，只需呼叫 enqueue_block_editor_assets 鉤子並在其中載入指令碼即可。

區塊風格變體

說到區塊風格變體，你有兩種選擇：

• 使用 PHP 的 register_block_style() 函式。
• 建立 block-editor.js JavaScript 檔案，使用與區塊變體類似的registerBlockStyle()函式並呼叫指令碼。

註冊區塊風格變體後，就可以使用 variations 屬性來定位區塊：

…
"styles": {
"blocks": {
"core/button": {
"variations": {
"outline": {
"border": {
"color": "var:preset|color|black",
"radius": "0",
"style": "solid",
"width": "3px"
},
…

這意味著你可能根本不需要任何自定義 CSS，幾乎區塊設計的方方面面都可以通過 blocks 屬性來實現。

使用 blocks 屬性從頭到尾設計預設區塊的樣式

為了演示 blocks 屬性的工作原理，讓我們通過一個實際例子來了解一下。我們的網站使用了 Twenty Twenty-Four 主題，並使用了預設樣式：

每個主題通常都會有不同的風格變化，以實現不同的外觀

到目前為止，我們認為這看起來非常理想，不過標題和正文的顏色似乎過於相似。我們想改變其中一種或兩種顏色，以區別它們。作為終端使用者或網站所有者，我們可以在網站編輯器的樣式邊欄中解決這個問題。如果前往區塊>標題，就可以單擊文字元素，將顏色更改為合適的顏色：

您可以通過網站編輯器輕鬆更改各個區塊的設定

不過，作為開發人員，您可以在 theme.json 中進行更改。與其他任何主題一樣，最好的方法是建立一個子主題，以保留您所做的任何更改。這樣做的第二個好處是，你的 theme.json 檔案看起來會更整潔。

我們將在 wp-content/themes/ 目錄中建立一個目錄，並將其命名為 twentytwentyfour-child 。在此新增一個有效的 style.css 檔案和一個空白的 theme.json 檔案。

每個子主題目錄都需要一個 style.css 檔案和一個 theme.json 檔案

在這裡，你可以開啟 JSON 檔案並開始工作。

為子主題建立並填充 theme.json 檔案

建立父主題和子主題的主題 .json 檔案的主要區別在於檔案的結構。你不需要說明模式，也不一定要把所有內容都放在 settings 物件中。在我們的例子中，我們必須使用 styles 屬性：

{
"version": 3,
"styles": {
"blocks": {}
}
}

接下來，我們需要找到標題區塊的名稱空間和標題。官方的《核心區塊參考指南》列出了所有這些內容，甚至還會告訴我們該區塊支援哪些屬性。指南告訴我們可以調整 color 屬性的 background, gradient, link, 和 text 值。

"blocks": {
"core/heading": {
"color": {}
}
}

結構設計完成後，我們就可以開始考慮如何重新設計文字。

尋找配色方案並進行修改

現在，我們需要一種適合我們需要的顏色。Twenty Twenty-Four 預設變體的調色盤非常出色，在專門的對比度檢查器中進行檢查後，我們就會有一些想法：

在設計主題的過程中，檢查配色方案是否具有合適的可訪問對比度是一個關鍵步驟。

接下來，我們可以在 theme.json 中為 Block 新增顏色選擇。由於父版 Twenty Twenty-Four 主題使用自定義 CSS 屬性來定義調色盤樣式，因此我們也可以在這裡呼叫：

…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
…

如果需要知道調色盤顏色的名稱，可以在站點編輯器的顏色選擇器中找到：

通過檢視網站編輯器調色盤中的顏色，可以找到該顏色的名稱。

儲存更改後，重新整理網站，就會看到新的配色方案。如果沒有，請檢查是否在正確的物件中巢狀了 blocks 屬性，因為這是一個常見的問題。

當我們看到網站時，文字的對比度降低了，更容易閱讀了。不過，我們仍然希望看到段落區塊和周圍的標題之間有一些清晰度。主題的預設調色盤有一些其他更大膽的顏色。我們將嘗試在標題區塊中使用 Accent / 3 色：

"blocks": {
"core/heading": {
"color": { "text": "var(--wp--preset--color--accent-3)" }
},
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" }
}
}

儲存更改並重新整理前端後，你會發現標題區塊的定義更加清晰了：

前端會根據 theme.json 設定更改標題區塊

這並不是編輯的終點。你甚至可以通過 theme.json 自定義網站編輯器的選項。

為區塊新增屬性選項

每個區塊的支援決定了它在網站編輯器中的選項。例如，段落區塊預設禁用下拉上限功能。

網站編輯器預設情況下不允許您選擇啟用下拉上限

我們可以在theme.json檔案和 blocks 屬性中重新啟用。根據參考資料，我們可以利用排版屬性啟用下拉選單頁首：

…
"core/paragraph": {
"color": { "text": "var(--wp--preset--color--contrast)" },
"typography": { "dropCap": true }
…

儲存這些更改並重新整理編輯器後，您就可以使用切換下拉上限的選項了：

在 WordPress 網站編輯器中啟用下沉帽（Drop Cap）功能只需通過 theme.json 檔案幾秒鐘即可完成。

theme.json 檔案不僅僅是設計配置。它還可以幫助新增和刪除網站編輯器的功能。

小結

瞭解 theme.json 中的 block 屬性是所有主題開發人員的必修課。它可以將全域性設計變得更加獨特、連貫和相關。完全可以使用單個核心和自定義區塊設定，這有助於每個使用者充分利用全站編輯功能。此外，在網站編輯器中提供這些選項，意味著終端使用者可以在不使用程式碼的情況下自行更改，而您只需提供恆星預設選項。

關於在 theme.json 檔案中使用 block 屬性，您有任何問題嗎？請在下面的評論區提問！