釋放theme.json的威力：像專業人士一樣定製WordPress主題

隨著 WordPress 生態系統的不斷髮展，WordPress 開發人員擁有了比以往更多的控制權。全站編輯（FSE）為所有使用者提供了從頭開始建立主題的機會，尤其是在使用 theme.json 檔案時。

開發人員也可以利用 theme.json 檔案。該配置檔案允許對 WordPress 主題進行細粒度定製，而無需使用更復雜的程式語言進行繁瑣複雜的操作。

在本綜合指南中，我們將探討 theme.json 檔案的作用，包括它與完整網站編輯的關係。到最後，無論你的開發能力如何，你都會了解如何利用它的功能來建立現代化的高效能網站。

theme.json 檔案介紹

theme.json 檔案的核心是一個配置檔案，用於定義 WordPress 主題的設定和樣式。它使用 JavaScript Object Notation (JSON)，這是一種結構化資料，繼承了其父語言的鍵值配對，方便你編寫程式碼。

JSON 程式碼示例。

theme.json 檔案是控制主題各個方面的關鍵。其中包括調色盤、排版設定、佈局選項、每個區塊的樣式、自定義 CSS 屬性等。我們將在本文中詳細介紹這些方面。

雖然到目前為止這聽起來並不太革命性，但 theme.json 對 WordPress 開發的未來非常重要。下一節將解釋原因。

為什麼 theme.json 與 WordPress 主題開發相關？

WordPress 的典型主題開發和外掛建立方法通常圍繞使用 PHP 編輯模板檔案、使用 functions.php 檔案和其他技術任務展開。

theme.json檔案標誌著一個重大轉變，尤其是在開發主題方面。原因有以下幾點：

• 該檔案是定義主題設定和樣式的單一、有序的位置。這減少了對分散的 CSS 和 PHP 檔案的需求。
• 在theme.json 中集中宣告樣式和設定意味著 WordPress 可以生成更有效的 CSS。與使用 jQuery 等框架相比，WordPress 有可能提高效能。
• 與以往相比，您對網站和各個區塊的樣式有更多的控制權。這使技術知識較少的使用者也能進行主題開發。
• 隨著 FSE 的不斷髮展，theme.json 檔案將在主題、全域性樣式和區塊編輯器的互動方式中發揮至關重要的作用。

將所有這些方面結合起來，就能以標準化的方式為主題定義設定和樣式。對於希望瞭解和使用不同主題的人來說，使用 theme.json 將使您建立的 WordPress 主題更加強大、靈活和使用者友好。更好的是，這些建立將與平臺的未來發展方向保持一致。

在哪裡找到 theme.json 檔案

首先，在 “傳統” 或 “經典” 主題中找不到 theme.json 檔案。要找到並使用該檔案，你需要一個專用的區塊主題。不過，只要執行的是 WordPress 5.8 或更高版本，您可以在任何主題中建立該檔案。

theme.json 檔案的典型位置是wp-content/themes/[你的主題]。如果檔案不在那裡，你應該開啟你最喜歡的編碼編輯器，根據需要建立檔案。暫時不用擔心檔案內容，我們很快就會討論這個問題。

如果您需要從頭開始建立一個新檔案，但又想在定製自己的檔案前瞭解其中的複雜內容，請檢視預設的 Twenty Twenty-Four 主題。

作為一個塊主題，它將有一個 theme.json 檔案可供檢視。在接下來的幾節中，我們將介紹該檔案的結構，開啟它可能會派上用場。

使用 theme.json 所需的資訊

當然，並不是每個人都能開啟配置檔案並開始工作。你仍然需要一些基本技能和知識來構建和定製主題：

• 基本的 JSON 知識。我們認為這是你可以快速掌握的，但熟悉 JSON 語法和結構仍然至關重要。
• 瞭解 CSS。您會發現，許多 theme.json 物件和屬性都與 CSS 對應。CSS “chops” 在這裡將大有裨益。
• WordPress 區塊編輯器知識。瞭解塊是如何工作的，以及它們的自定義選項，會對您的構建工作有所幫助。

雖然這並不是絕對必要的，但我們鼓勵你至少了解 FSE 的關鍵概念，這將有助於你以更有效的方式利用 theme.json 檔案。您還可以瞭解您的編輯將如何影響終端使用者的 “修補”。此外，在某些情況下，你仍然需要使用 HTML 和 JavaScript 來實現你的設想。

最後，我們向您推薦幾款技術 “額外裝備”：

• 程式碼編輯器。選擇一個能提供 JSON 語法高亮和驗證功能的高質量編輯器，將使您的工作流程更加輕鬆愉快。
• 本地開發環境。使用本地環境工具對主題進行開發，可以讓您快速試驗和測試更改，而不會影響實時網站。

有了這些工具和知識，您就可以開始使用 theme.json 自定義 WordPress 主題了。

瞭解 theme.json 的結構和層次結構

顯然，theme.json 檔案有一個你需要了解的結構。它還有一個層次結構，以及一些需要進一步解釋的獨特元素。

這可能是使用配置檔案最複雜的部分，但即便如此，你也能輕鬆掌握其中的概念。

讓我們先從結構開始，然後瞭解 theme.json 的其他元素。

基本結構

鑑於檔案採用 JSON 格式，你可能已經瞭解了結構的一般概念。首先，整個檔案物件都用大括號包起來，檔案中的其他物件也是如此。每個物件都由鍵值對組成，鍵值使用單引號或雙引號，行尾使用逗號。

一個 theme.json 檔案至少需要 version, settings, 和 styles 物件：

{
"version": 2,
"settings": {
// Global settings go here
},
"styles": {
// Global styles go here
}
}

settings 和 styles 物件簡單明瞭，但 version 需要更多解釋。該值將是一個整數，與讀取檔案時使用的 API 版本相匹配。當前的 API 版本是3，不過2版本也很常見，你也可以從舊版本遷移過來。

大多數 theme.json 檔案結構還包括一個 schema。簡而言之，它可以讓你在程式碼編輯器中使用自動完成功能，併為檔案提供驗證。你可以在檔案的頂部新增這一內容：

{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
},
"styles": {
}
}

從這裡開始，你將為 settings 和 styles 新增各種屬性和物件，以構建你的檔案。

層次結構

theme.json 檔案遵循層次結構，只是網站 settings 和 styles 整體層次結構中的一個層次。如果你有 CSS 知識，理解起來會更容易，因為該檔案的複雜程度與 CSS 類似。

簡而言之，您對 theme.json 所做的自定義不一定會顯示在網站前端。使用者配置優先於一切。這意味著在 WordPress 的外觀>編輯器介面上進行的任何更改都會顯示在前端：

WordPress 的主網站編輯器介面。

如果您使用的是子主題幷包含一個 theme.json 檔案，那麼它將覆蓋除網站編輯器之外的所有更改。同樣，你在父主題配置檔案中定義的任何內容都將覆蓋 WordPress 的預設設定和樣式。雖然 WordPress 也有自己的 theme.json 檔案，但我們在這篇文章中重點討論的就是這個檔案。

雖然這不是這篇文章的重點，但你也可以使用鉤子和過濾器來覆蓋值。通過這些動態過濾器，你可以建立外掛和主題，同時改變主題和平臺設定及樣式。

區塊語法

如果你進入 WordPress 區塊或站點編輯器，開啟一篇文章或一個頁面，然後切換程式碼編輯器，你會發現內容中有很多看似 HTML 註釋的內容：

WordPress 區塊編輯器中的程式碼編輯介面。

這是因為區塊主題不是使用 PHP 檔案，而是使用 HTML 檔案以及註釋和區塊標記來建立網站。這些元素的組合產生了您在編寫 theme.json 檔案時所需的 “區塊語法”。

對於包含內容的區塊，例如段落區塊，你需要對內容進行包裝：

<!-- wp:paragraph -->
<p>Content goes here!</p>
<!-- /wp:paragraph -->

在其他情況下，你只需要單行註釋或自動關閉的註釋。對於某些區塊，你可以組合型別來建立佈局和設計。您還可以巢狀這些註釋：

<!-- wp:columns -->
<div class="wp-block-columns">
<!-- wp:column -->
<div class="wp-block-column"></div>
<!-- /wp:column -->
<!-- wp:column -->
<div class="wp-block-column"></div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->

在這裡，我們使用封裝註釋建立一個列塊。在其中，我們可以開始新增 HTML 來設計這些列，幷包含各個列的包裝器。這在前端是很容易做到的，因為你經常會把區塊放在彼此的內部。

要查詢特定塊的標記，可以在區塊編輯器手冊中查詢，直到找到所需內容。不過，最簡單的方法是將區塊新增到 WordPress，開啟程式碼編輯器，然後從那裡複製標記。

至於如何修改標記，我們將在後面的章節中介紹。

theme.json 與 WordPress 全站編輯如何結合

通過對層次結構的討論，你會明白 theme.json 是 FSE 的重要組成部分。兩者共同為 WordPress 提供全面的主題解決方案。例如，全域性樣式介面基本上就是 theme.json 設定的視覺化呈現。

網站編輯器側邊欄顯示主題的全域性樣式選項。

您可以在全域性樣式面板或配置檔案中修改設定，WordPress 會根據需要更新相應的值。雖然網站編輯器設定優先，但theme.json 將作為主題自身樣式的基礎。對於終端使用者來說，全域性樣式可以讓他們用自己的自定義樣式替換預設樣式，而無需程式碼或編輯 theme.json 檔案。

此外，您在 theme.json 檔案中定義的 CSS 自定義屬性也可在全域性樣式介面中使用。這樣，使用者就可以利用這些屬性在整個網站上建立更一致的樣式。這還可以擴充套件到定義特定的區塊樣式和設定，你可以在 WordPress 儀表板上進一步調整。

簡而言之，theme.json  提供了對設定、樣式等更細粒度的控制。與傳統方法相比，它是一種開發人員級別的工具，能提供更直接、更簡化的體驗。相比之下，全域性樣式介面讓每個人都有機會按照自己的喜好自定義主題。在進一步開發主題的過程中，你會發現兩者是如何協同工作，幫助建立網站設計和佈局的。

使用 theme.json 檔案屬性

瞭解了基礎知識後，你就可以開始使用 theme.json 檔案中的物件和屬性了。我們無法涵蓋所有的使用情況或可能性。不過，在本教程結束時，您將能夠建立功能齊全、前端美觀的主題。

Settings

settings 屬性可讓你控制網站編輯器中提供的功能及其行為方式。這是一個頂級屬性，通常會有多層巢狀。

一旦我們瞭解了樣式及其變化，你就會發現這些選項之間有一些交叉，但這兩種型別在建立主題時都有作用。

你可以選擇一定數量的屬性：

{
"version": 3,
"settings": {
"appearanceTools": false,
"blocks": {},
"border": {},
"color": {},
"custom": {},
"dimensions": {},
"layout": {},
"position": {},
"shadow": {},
"spacing": {},
"typography": {},
"useRootPaddingAwareAlignments": false
}
}

官方的《WordPress 主題開發人員手冊》包含所有這些設定（和樣式）的參考資料。不過，以下是幾個需要進一步說明的重要設定的簡要概述：

• appearanceTools。這個包羅永珍的屬性可以啟用許多其他屬性，是為了節省時間。它可以設定邊框選項、排版線高、填充、頁邊距等。
• blocks。雖然你的大部分工作都將著眼於全域性設定和樣式，但 blocks 屬性可以讓你在每個塊的基礎上進行設定。我們不會在此詳細介紹這一概念，但《主題開發者手冊》中有關於 theme.json 這方面的出色文件。
• custom。這個獨特的屬性沒有任何功能，它的作用由你決定。你可以用它為主題建立自定義 CSS 屬性，而且範圍很廣。
• useRootPaddingAwareAlignments. 同樣，這是一個複雜的屬性，我們不會全面介紹。從本質上講，它可以幫助你放置主題的水平填充樣式，而且功能強大。如果你想讓全寬專案延伸到螢幕邊緣，同時在根元素上使用填充，就可以使用它。

請注意，你不需要在 theme.json 中新增任何你不想使用的屬性。例如，如果你不想使用 appearanceTools，你可以直接將其省略，而不是定義為 false。

如何在 theme.json 中定義設定

在定義設定時，每個屬性都有許多鍵值對子屬性。例如，你可以這樣建立調色盤：

{
"version": 3,
"settings": {
"color": {
"palette": [
{
"color": "#0073aa",
"name": "Primary",
"slug": "primary"
},
{
"color": "#23282d",
"name": "Secondary",
"slug": "secondary"
}
],
…

其他屬性具有簡單的布林值，可在網站編輯器中開啟或關閉這些功能：

{
"version": 3,
"settings": {
"color": {
"background": true,
"defaultPalette": true,
"link": true,
"text": true
}
}
}

一旦定義了設定，就可以為其引入樣式。現在就讓我們來看看。

樣式和樣式變化

settings 定義了某些樣式選項的訪問許可權，而 styles 屬性則可以讓你為主題定義全域性樣式。同樣，這是一個使用多層巢狀的頂級屬性。你可以針對特定元素、區塊，甚至使用自定義 CSS 屬性。

在這裡定義主題樣式非常重要，這樣你就可以在網站編輯器中訪問和自定義它們。您可以使用多種元素：

{
"version": 3,
"styles": {
"border": {},
"color": {},
"dimensions": {},
"filter": {},
"shadow": {},
"spacing": {},
"typography": {},
"css": {}
}
}

不過，這些二級屬性中的很多都不會經常使用。相反，有些屬性主要用於區塊或元素。例如

…
"styles": {
"blocks": {
"core/group": {
"color": {
"text": "#000000",
"background": "#ffffff",
"link": "#777777"
}
…

對於全域性樣式，你將在根目錄下工作，也就是頁面的 <body> 標籤。對於特定元素，可以採用與塊類似的結構，這次使用的是 elements 屬性：

…
"styles": {
"elements": {
"button": {
"color": {
"text": "#ffffff",
"background": "#aa3f33"
}
…

如果您在網站編輯器中檢視您所做的任何更改，就會發現它們已經到位。標記還將為您建立的任何樣式生成 CSS：

顯示瀏覽器 DevTools 的網站前端，突出顯示為元素生成的 CSS。

請注意，您還可以為元素設定偽類樣式，如懸停和焦點樣式：

…
"elements": {
"button": {
"color": {
"text": "#ffffff",
"background": "#aa3f33"
},
":hover": {
"color": {
"background": "#822f27"
}
…

樣式的應用比這還要深入，這也是使用 theme.json 的一大優點。

風格變化

在我們繼續之前，你需要了解一下風格變化。你可以在 FSE 介面中看到這些不同的調色盤和排版樣式：

網站編輯器中的 “樣式” 側邊欄，顯示不同的變化。

不過，這些並不是你在 theme.json 中編寫的程式碼。相反，你需要建立不同版本的檔案，給它們一個唯一的名稱，並將它們儲存在主題的樣式目錄中：

顯示樣式變化 JSON 檔案的程式碼編輯器。

請注意，標記中的標題對每個備選 JSON 檔案都是唯一的。不過，這是一個可選欄位，不過我們建議您使用它，以獲得清晰度和最佳體驗。

自定義模板和模板部分

與樣式變化一樣，theme.json 也允許你註冊自定義模板和相關模板部分。註冊標記非常簡單：

"customTemplates": [
{
"name": "my-template",
"title": "My Template",
"postTypes": [
"page",
"post"
]
}
]

customTemplates 屬性需要定義三個元素：

• name。這將對應於你在主題模板目錄中建立的模板，如/template/my-template.html。
• title。這是模板名稱的可讀版本。
• postTypes。如果沒有定義，預設為頁面，但可以指定模板適用的文章型別陣列。

使用者可以在網站或區塊編輯器中選擇您註冊的任何模板：

在 WordPress 網站編輯器中選擇編輯、交換、建立或顯示模板。

說到模板部件，您不需要註冊它們，但我們建議您註冊。其結構與註冊模板類似：

…
"templateParts": [
{
"area": "header",
"name": "header",
"title": "Header"
},
…

在這裡，名稱和標題與完整模板的定義相同。區域與部件所屬的位置有關：預設為 header, footer, 或 uncategorized ，但您可以將模板部件分配到任何自定義區域。

我們建議你也研究一下如何顯示這些模板部分，因為如果沒有一些額外的編碼，它們是不會顯示出來的。即便如此，註冊它們也很簡單。

樣板

最後，讓我們來討論一下區塊模式。你可以在 theme.json 檔案中使用一個頂級陣列捆綁任意數量的模式。WordPress 樣板庫中任何合適的模式都可以包含在你的檔案中：

WordPress 樣板庫。

定義陣列非常簡單：使用 patterns 屬性和庫 URL 中相關模式的標題即可：

從網路瀏覽器的 URL 中選擇樣板的 slug。

有了這個 slug，就可以填充 patterns 標記：

{
"version": 3,
"patterns": [
"fullwidth-vertically-aligned-headline-on-right-with-description-on-left"
]
}

您可以在區塊編輯器樣板目錄中選擇它們：

區塊編輯器中的 WordPress 樣板目錄。

這種將樣板庫資產引入主題的簡單方法既方便又有價值。這也是 theme.json 檔案迅速成為 WordPress 主題開發者最喜歡的構建方式的另一個原因。

使用 theme.json 定製 WordPress 網站的工作流程

瞭解 theme.json的關鍵元件後，制定使用 theme.json 的工作流程就是重要的一步。它代表了一種開發主題的新方法，因此需要以不同於傳統方法的方式來處理。

我們的方法是設定模式 URL，選擇 API 版本，並首先定義全域性設定。這包括調色盤、排版選項和佈局設定。在大多數情況下，啟用 appearanceTools 也是有益的：

"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"appearanceTools": true,
"color": {
"palette": [
{
"name": "Primary",
"slug": "primary",
"color": "#0073aa"
},
{
"name": "Secondary",
"slug": "secondary",
"color": "#23282d"
}
]
},
"typography": {
"fluid": true,
"fontSizes": [
{
"size": "13px",
"slug": "small",
"name": "Small"
},
{
"size": "16px",
"slug": "normal",
"name": "Normal"
…

接下來，您可以使用定義的 slug 建立自定義 CSS 屬性。例如，您可能已經建立了自定義 fontWeight：

…
"custom": {
"fontWeight": {
"light": 300,
"regular": 400,
"medium": 500,
"bold": 700
},
…

完成設定後，就可以指定樣式了。

…
"styles": {
"color": {
"background": "var(--wp--preset--color--base)",
"text": "var(--wp--preset--color--main)"
},
…

接下來是自定義區塊樣式，這可能會佔theme.json 檔案的很大一部分。

…
"styles": {
"block": {
"core/separator": {
"color": {
"text": "var(--wp--preset--color--main)"
},
"typography": {
"fontSize": "var(--wp--preset--font-size--large)"
}
},
"core/site-tagline": {
"spacing": {
"margin": {
"bottom": "20px"
}
},
"typography": {
"fontSize": "var(--wp--preset--font-size--small)"
}
},
"core/site-title": {
"typography": {
"fontSize": "var(--wp--preset--font-size--medium)",
"fontWeight": "var(--wp--custom--font-weight--semi-bold)",
"lineHeight": "var(--wp--custom--line-height--none)"
},
…

最後，您需要設計任何自定義模板和模板部件，並將其註冊到 theme.json 中。這也是註冊任何你想使用的 Block 模式的時候，如果有必要，還可以建立它們。

使用 theme.json 還是 WordPress 全站編輯？

鑑於 theme.json 和全站編輯之間的交叉性，您可能會問為什麼要使用其中一個而不是另一個。事實上，兩者適用於不同的情況，應該結合使用。

例如，在以下情況下，您可以使用 theme.json：

• 您開發主題並從頭開始建立新主題。
• JSON 是一種你能理解並使用自如的語言。
• 您希望使用程式設計方法為主題定義預設樣式和設定。
• 您想要實現的樣式和設定需要比網站編輯器中的預設值更多的控制。

當然，由於 FSE 幾乎完全照搬了theme.json 的功能，因此最後一點會顯得比較小眾。因此，在以下情況下，全站編輯對大多數使用者更有意義：

• 您是一位想要定製現有主題的網站所有者。
• 您不熟悉 JSON。
• 視覺化介面更適合您的定製和開發工作流程。
• 您希望快速調整，而無需大量編碼。

實際上，主題需要一個配置檔案來定義其基礎。在此基礎上，層次結構將接管一切，網站所有者可以使用 FSE 進行進一步定製。

小結

theme.json 配置檔案是 WordPress 主題開發的革命性工具。它為您的主題設定和樣式提供了一個集中的家園，使您能夠建立更靈活、可維護和可定製的主題。

您將在 WordPress 的站點編輯器中使用該檔案來完成站點的最終設計。您在 theme.json 中設定的選項將作為預設設定，終端使用者將對其進行進一步自定義。好訊息是，編寫該檔案比調整一系列 PHP 和 CSS 檔案更簡單，這也是 WordPress 設計的未來趨勢。

關於在 WordPress 中使用 theme.json 檔案，您有任何問題嗎？請在下面的評論區告訴我們！