在theme.json中使用屬性和鍵值對

瞭解 theme.json 檔案的結構和屬性是區塊主題開發的基礎。該檔案是所有基於區塊的主題的主要配置中心。

無論你是從頭開始建立一個主題，還是對現有主題進行自定義、開發風格變體或製作子主題，掌握theme.json的使用方法都是至關重要的。

幸運的是，JSON（JavaScript Object Notation，JavaScript 物件符號）是一種人類可讀的格式，其分層結構可將資訊從一般屬性組織到特定屬性。就 theme.json 而言，熟悉層疊樣式表（CSS）比深入瞭解 JavaScript 更有意義。

本文旨在分解 theme.json 檔案中的主要和次要（巢狀）屬性，重點關注鍵設定和樣式屬性。這些是檔案的核心元素，我們將為每個元素提供詳細解釋和程式碼示例。

我們將在上一篇文章《釋放主題 .json 的力量》：像專業人士那樣定製 WordPress 主題中奠定的基礎上繼續努力，尤其是在使用 theme.json 檔案屬性部分。

區塊主題中如何呈現樣式

WordPress 使用內建的層疊過程來呈現網站的樣式。當多個來源定義了相同的設定或樣式時，WordPress 必須確定哪一個優先。以下是 WordPress 決定應用哪種樣式所遵循的優先順序：

1. WordPress 核心–  theme.json 檔案位於 WordPress 的 wp-includes 目錄下。這個檔案會在主要的 WordPress 版本更新時被更新，不應該直接編輯。
2. 主題– 主題開發人員使用的主要 theme.json 檔案，用於定義主題的設定、樣式和其他屬性。
3. 風格變體– 如果主題包含風格變體，每個變體都有自己的 theme.json 檔案，儲存在主題的 styles 子目錄中。
4. 子主題– 與經典主題一樣，子主題可以修改父主題，而無需更改其檔案（可選）。
5. 子主題樣式變化– 與常規樣式變化類似，子主題可以在其樣式子目錄中擁有自己的 theme.json 檔案（可選）。
6. 使用者建立的樣式– 這些是通過 WordPress 編輯器新增並儲存在資料庫中的自定義樣式（用於頁面、文章或整個網站）。

級聯順序確保來自優先順序較高來源的樣式優先於來自優先順序較低來源的樣式。例如，主題的 theme.json 檔案中的設定將覆蓋 WordPress 核心的 theme.json 檔案。同樣，子主題的樣式變化將優先於父主題的樣式變化。

使用者建立的樣式（6）具有最高優先順序，在級聯中優先於所有其他樣式。

本文的重點是位於任何 WordPress 區塊主題根目錄下的 theme.json 檔案。

主要屬性及其鍵值參考

讓我們來探討一下 theme.json 中的七個頂級物件，為了便於理解，我們將它們分成了三個部分。

深入瞭解前的幾個定義

在使用theme.json 時，你可能會發現重要元件的定義各不相同。為清晰起見，我們在本文中將對它們進行如下定義：

1. 章節 – 在 theme.json 檔案中用於組織和分組頂層選項的部分。從某種意義上來說，它們可以被視為頂層物件（top-level objects），它們幫助將不同的配置選項分類，以便更容易地理解和管理。
2. 物件 –theme.json檔案中的主要元素，如 settings 和 styles。
3. 屬性 – 物件中的元件。例如，settings 物件包含 12 個不同的屬性。
4. 鍵值對 – 屬性由鍵值對組成。鍵代表一個屬性，用引號括起來。值可以是布林值、字串或陣列。

當我們提到“預設情況下”時，我們指的是 theme.json 檔案中的預設配置，該檔案位於wp-includes/theme.json 中。

最後，“使用者”是指任何使用 WordPress 管理後臺的人，他們可以修改網站、頁面或文章編輯器中的設定。

語法概述

1. 布林值不用引號括起來。
2. 字串用雙引號括起來。
3. 陣列用方括號 [] 括起來。
4. 物件用大括號 {} 括起來，包含多個屬性或巢狀物件。
5. 逗號用於分隔物件中的多個鍵值對。

下面是一個典型的語法示例：

{
"house": {
"rooms": "kitchen"
}
}

屬性分組

為了便於瀏覽，我們將屬性分為三個部分：

1. 基本屬性
2. 設定和樣式屬性
3. 模板和樣板屬性

為了簡化示例，我們有時會省略外部物件包裝器。而不是顯示整個結構：

{
"settings": {
"appearanceTools": false,
"background": {
"backgroundImage": true
}
}
}

We might shorten it to:

"appearanceTools": false,
"background": {
"backgroundImage": true
}

提示：部分示例用於說明概念，可能並不代表主題開發中的實際應用。

基本屬性

在 theme.json 檔案的開頭，你通常會發現兩個關鍵屬性：$schema 和 version。這些屬性通常位於檔案的頂部。當前的模式版本是 3，在 WordPress 6.6 中引入。

"$schema": "https://schemas.wp.org/wp/6.6/theme.json", "version": 3

設定和樣式屬性

如果你熟悉經典主題，就會把設定屬性看作通常在 functions.php 檔案中設定並在 WordPress 管理後臺的“外觀”>“自定義”版塊中顯示的特性和功能。

而樣式則類似於以前存在於 styles.css 檔案中的 CSS 屬性，用於控制主題的佈局和設計。

設定

除 block 和 elements 屬性外，所有其他設定都是全域性設定。由於這些設定中有很多都是布林值，因此它們就像是啟用或禁用使用者介面功能的切換開關。

值得注意的是，並不是所有的鍵都適用於任何情況。例如，不可能允許使用者設定段落塊的最小高度。

外觀工具

這些設定可以通過使用 "appearanceTools": true 來集體或單獨啟用。

啟用此功能後，WordPress 編輯器中的各種使用者介面選項就會顯示出來，從而節省開發人員的時間。預設情況下，這些工具是禁用的（"appearanceTools":false）。

appearanceTools 中的鍵包括：

• background
  • backgroundImage — 允許使用者為圖塊新增背景圖片。
  • backgroundSize — 定義背景圖片的縮放方式（覆蓋、包含等）。
• border
  • color — 啟用顏色選擇（用於設定邊框顏色）。
  • style — 讓使用者選擇邊框樣式（實線、虛線、點線等）。
  • width — 控制邊框的厚度。
  • radius — 允許使用者通過調整邊框半徑來設定圓角。
• color
  • link — 為內容中的連結設定顏色。
  • heading — 允許使用者為標題標記（ <h1>、<h2> 等）定義顏色。
  • button — 控制主題中按鈕的顏色。
  • caption — 允許為標題設定自定義顏色。
• dimensions
  • aspectRatio — 允許使用者控制區塊的寬高比。
  • minHeight — 允許設定區塊的最小高度。
• position
  • sticky — 允許使用者將區塊設定為固定，即在滾動時保持固定位置。
• spacing
  • blockGap — 控制區塊之間的間距。
  • margin — 允許使用者調整區塊周圍的邊距。
  • padding — 控制區塊內的填充，定義其內容和邊框之間的空間。
• typography
  • lineHeight — 允許使用者調整行高（文字行間距），以提高可讀性。

舉例說明：如果希望使用者新增背景圖片，同時禁用其他外觀工具，請使用

"appearanceTools": false,
"background": {
"backgroundImage": true
}

由此產生的使用者介面允許使用者為組區塊新增背景圖片。

區塊

blocks 屬性允許使用者啟用每個區塊的設定，這些設定可以覆蓋全域性設定。

例如：如果 appearanceTools 設定為 false，但仍想為區塊顯示邊框控制元件，請使用：

"border": {
"color": true,
"style": true,
"width": true,
"radius": true
}

顯示生成的使用者介面，可以新增邊框。

顏色

使用者可通過該屬性設定背景色、文字色或漸變色等顏色選項。

顏色屬性中的鍵

• background– 控制區塊或元素的背景顏色。
• custom– 啟用或禁用使用者選擇自定義顏色的功能。
• customDuotone– 允許使用者對圖片應用自定義雙色濾鏡。
• customGradient– 啟用自定義漸變選項。
• defaultDuotone– 提供預設的雙色調影象濾鏡選項。
• defaultGradient– 定義使用者可用的預設漸變選項。
• defaultPalette– 控制主題的預設調色盤。
• duotone– 允許在影象上使用雙色調濾鏡。
• gradient– 啟用背景或其他元素的漸變選項。
• link– 設定主題中連結的顏色。
• text– 控制 text 顏色選項。
• heading– 設定標題（如 h1、h2 等）的顏色。
• button – 控制按鈕顏色選項。
• caption– 為媒體元素設定標題顏色。

讓我們舉例說明：

示例 1：如果要禁用使用者的顏色選擇器，可以使用下面的方法：

"color": {
"custom": false
}

禁用顏色選擇器使用者介面。

示例 2：要設定自定義的主主題色和次主題色，可以使用此配置：

"color": {
"palette": [
{ "slug": "primary", "color": "#0000ff", "name": "Primary" },
{ "slug": "secondary", "color": "#ff0000", "name": "Secondary" }
]
}

由此產生的使用者介面設定主色調和次主題色調。

尺寸

該屬性提供了控制塊尺寸（如寬度、高度和寬高比）的選項。

dimensions 屬性中的鍵

• aspectRatio– 允許使用者設定或鎖定區塊的縱橫比（如 16:9、4:3）。
• defaultAspectRatios– 為區塊定義預設寬高比。
• minHeight– 啟用為區塊設定最小高度的功能。

例如，要允許使用者為支援的區塊設定最小高度，請使用以下命令：

"dimensions": {
"minHeight": true
}

使用者介面中設定的最小高度。

佈局

layout 屬性允許使用者設定與佈局相關的選項，如內容寬度和使用者是否可以自定義佈局。使用者可以通過這些鍵來設定佈局選項：

• contentSize– 設定區塊的預設寬度。
• wideSize– 定義選擇寬對齊選項時區塊的寬度。
• allowEditing– 確定使用者是否可以編輯佈局選項。
• allowCustomContentAndWideSize– 啟用 contentSize 和 wideSize 的自定義選項。

示例 ： 配置具有預設和寬對齊區塊寬度的佈局設定：

"layout": {
"contentSize": "620px",
"wideSize": "1000px"
}

設定和預覽區塊尺寸。

注：這些值是使用者可以更改的起點。

燈箱

通過 lightbox 屬性，使用者可以啟用圖片的“點選即展開”功能，在點選時以更大的檢視開啟圖片。

lightbox 屬性中的鍵：

• enabled — 啟用或禁用燈箱功能。
• allowEditing — 允許使用者切換燈箱設定。

示例：要允許使用者切換圖片的燈箱功能，請使用此配置：

"blocks": {
"core/image": {
"lightbox": {
"allowEditing": true
}
}
}

切換燈箱效果。

位置

position 屬性允許使用者控制區塊的位置，例如使區塊在頁面上固定位置。

示例：讓區塊可固定位置：

"position": {
"sticky": true
}

陰影

此屬性可讓使用者通過使用預定義預置或自定義陰影為圖塊應用陰影效果。

shadow 屬性中的鍵：

• defaultPresets —啟用或禁用預設陰影預設。
• presets —允許使用者定義自定義陰影預設。

下面是一個關閉預設陰影並定義名為“Natural”的自定義陰影的示例：

"shadow": {
"defaultPresets": false,
"presets": [
{ "name": "Natural", "slug": "natural", "shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)" }
]
}

在使用者介面中設定陰影選項。

數字表示網站編輯器中的點選步驟，以演示使用者介面。最後一步顯示的是“Natural”陰影。

間距

該屬性定義了編輯器中如何控制間距（padding、margin、gap）。

spacing 屬性中的鍵：

• blockGap — 控制區塊之間的間隙。
• margin — 允許使用者設定區塊周圍的邊距。
• padding — 提供在區塊內設定填充的選項。
• units — 定義可用的間距單位（如 px、rem）。
• customSpacingSize — 允許使用者設定自定義間距大小。
• spacingSizes — 定義一系列預設的間距大小。
• spacingScale — 允許縮放間距單位。

舉例說明：要將使用者的填充、邊距、寬度和高度限制為兩種測量單位（畫素和 rem），並在網站編輯器中顯示間距控制元件，請將 appearanceTools 設定為 true 並進行如下配置：

"spacing": {
"units": ["px", "rem"]
}

限制使用 2 個計量單位。

排版

該屬性控制主題的文字相關設定，如字型大小、粗細和行高。

typography 屬性中的鍵：

• defaultFontSizes — 定義使用者可用的預設字型大小。
• customFontSize — 啟用或禁用設定自定義字型大小的功能。
• fontStyle — 控制字型的樣式（如普通、斜體）。
• fontWeight — 允許使用者設定字型的重量（如粗體、淺色）。
• fluid — 啟用流體排版，根據螢幕大小動態調整字型大小。
• letterSpacing —控制字母之間的間距。
• lineHeight — 設定每行文字的高度。
• textAlign — 允許控制文字對齊方式（如左對齊、居中對齊、右對齊）。
• textDecoration — 提供文字裝飾選項（如下劃線）。
• writingMode — 設定文字的書寫模式（如水平或垂直）。

示例：要禁用自定義字型大小和 ropCap 選項，請使用以下命令：

"typography": {
"customFontSize": false,
"dropCap": false
}

刪除自定義字型大小選項和 DropCap。

在這種情況下，這兩個高亮顯示的鍵都不會出現在編輯器中。

根元素內邊距感知對齊

當一項名為“root padding aware alignments”的屬性被設定為“true”時，它會確保寬度或全寬度的塊級元素（例如，某些容器或背景影象）在頁面根元素（如  <html> 或  <body>）上應用的內邊距（padding）影響下，進行正確的對齊。

示例：

"useRootPaddingAwareAlignments": true

注：預設情況下，該屬性設定為 false，因此會產生平齊設計。

當設定為 true 時，還必須將根的頂部、右側、底部和左側填充值定義為樣式。(下文將詳細介紹樣式屬性）。

"spacing": {
"padding": {
"top": "0",
"right": "100px",
"bottom": "0",
"left": "100px"
}
}

useRotPaddingAwareAignements 預設設定。

將 useRootPaddingAwareAlignements 設定與左右填充一起應用於正文（如上述程式碼所示），結果如下。

當 useRootPaddingAwareAlignments 設定為 true 時，應用左右填充。

樣式

通過 styles 屬性，你可以將 CSS 樣式應用到根目錄（預設）、特定元素或主題中的單個區塊。

背景樣式

你可以控制與背景相關的屬性，如影象、定位和附件。

背景的常用鍵：

• backgroundImage — 定義區塊或元素的背景圖片。
• backgroundPosition — 設定背景影象的位置（如居中、右上角）。
• backgroundRepeat — 指定背景影象是否重複（例如，重複、不重複）。
• backgroundSize — 控制背景圖片的大小（如封面、包含）。
• backgroundAttachment — 指定背景圖片是固定還是隨頁面滾動。

例如，您可以為主題設定背景圖片：

"background": {
"backgroundImage": {
"url": "https://joyofwp.com/wp-content/uploads/2024/09/dots.png"
}
}

為所有頁面新增背景圖片樣式。

區塊特定樣式

您可以為單個區塊應用特定樣式，如陰影、排版和邊框。

邊框鍵：

• color — 定義邊框的顏色。
• radius — 為圓角設定邊框半徑。
• style — 指定邊框的樣式（如實心、虛線）。
• width — 控制邊框的寬度。
• top, right, bottom, left — 允許您為每一側設定單獨的邊框樣式。

例如，下面的內容會在整個頁面周圍設定一個 20px 的紅色實心邊框：

"border": {
"color": "#ff0000",
"width": "20px",
"style": "solid"
}

為所有頁面新增邊框樣式

您還可以為特定區塊、元素或根指定自定義 CSS。例如，下面的程式碼為表格塊應用了紅色文字顏色：

"border": {
"color": "#ff0000",
"width": "20px",
"style": "solid"
}

為所有表格新增文字顏色樣式。

顏色樣式

color 屬性允許你控制背景、漸變和文字顏色設定：

• background — 設定區塊或元素的背景顏色。
• gradient — 為區塊定義背景漸變色。
• text — 控制文字的顏色。

下面的示例為每個頁面的每個元素設定了黑色背景和白色文字：

"color": {
"background": "#000000",
"text": "#ffffff"
}

為所有頁面設定文字和背景顏色樣式。

CSS

通過 css 屬性，你可以將自定義樣式附加到特定類，從而對主題樣式進行更精細的控制。

示例：為 wp-block-template-parts 和 wp-block-button 應用自定義樣式，併為按鈕新增懸停效果：

"css": ".wp-block-template-part { background-color: #777777; padding: 20px; } .wp-block-button__link:hover { background-color: #ffffff; color: #000000; }"

顯示頁首中所有按鈕的文字和背景樣式都處於懸停狀態。

如您所見，頁首和頁尾模板部分被指定了 background-color 和 padding，而按鈕的懸停狀態則是白底黑字。

尺寸

通過 dimensions 屬性，可以控制區塊的寬度、高度和長寬比。

尺寸鍵：

• aspectRatios —為元素定義自定義寬高比。
• minHeight —設定區塊的最小高度。

示例：為影象區塊建立 3:7 的自定義縱橫比：

"blocks": {
"core/image": {
"dimensions": {
"aspectRatio": "custom"
}
}
}

不過，僅有上述內容還不夠。您必須在設定部分註冊“自定義”樣式。

"dimensions": {
"defaultAspectRatios": true,
"aspectRatios": [
{
"name": "Custom Ratio 3:7",
"slug": "custom",
"ratio": "3/7"
}
]
}

為所有影象新增自定義比例樣式選項。

在這裡，你可以看到“自定義比例 ”選項已經新增。如果你想移除七個預設寬高比，請從設定部分移除 "defaultAspectRatios":true 。

特定元素樣式

通過 elements 屬性，可以對連結、按鈕或標題等特定 HTML 元素應用樣式。

例如，下面的程式碼關閉了所有連結的文字裝飾（下劃線）：

"elements": {
"link": {
"typography": {
"textDecoration": "none"
}
}
}

禁用連結的文字裝飾樣式。

濾鏡

通過 filter 屬性，您可以對某些區塊（如影象）應用類似 CSS 的濾鏡效果（如模糊、亮度）。

示例：對影象區塊應用模糊和亮度濾鏡：

"blocks": {
"core/image": {
"filter": {
"duotone": "blur(5px) brightness(0.8)"
}
}
}

為所有影象新增模糊樣式。

在這裡，影象區塊應用了模糊和亮度效果。其他可用的濾鏡值包括：

• contrast — 調整元素的對比度。
• grayscale — 將元素轉換為灰度。
• invert — 反轉元素的顏色。
• opacity — 控制元素的透明度。
• saturate — 增加或減少顏色的飽和度。
• sepia — 為元素新增棕褐色調。

輪廓

outline 屬性定義了在元素邊框外繪製輪廓的樣式，但不影響佈局空間。

輪廓鍵：

• color — 設定輪廓的顏色。
• offset — 控制邊框與輪廓之間的空間。
• style — 指定輪廓樣式（如虛線、實線）。
• width — 設定輪廓的寬度。

示例：在按鈕上應用紅色圓點輪廓：

"elements": {
"button": {
"outline": {
"color": "#ff0000",
"style": "dotted",
"width": "4px"
}
}
}

為所有按鈕新增輪廓樣式。

陰影樣式

shadow 屬性允許你對區塊應用方框陰影，增加元素的深度和強調效果。

示例：為所有影象新增陰影：

"blocks": {
"core/image": {
"shadow": "0 10px 20px 0 rgb(0 0 225 / 0.50)"
}
}

為所有影象新增陰影。

間距樣式

spacing 屬性可管理主題的 padding、margin 和區塊間隙樣式。

間距鍵：

• blockGap — 控制區之間的間隙。
• margin — 設定區塊周圍的邊距。
• padding — 控制區塊內的填充。

下面的示例設定了左右兩側的自定義填充：

"spacing": {
"padding": {
"left": "min(6.5rem, 8vw)",
"right": "min(6.5rem, 8vw)"
}
}

新增左右填充。

排版樣式

typography 屬性管理字型樣式、大小和其他文字相關設定。

排版的常用鍵：

• fontFamily — 設定文字的字型家族。
• fontSize — 定義字型大小。
• fontStyle — 指定字型樣式（如斜體、正體）。
• fontWeight — 控制字型的重量（粗細）。
• letterSpacing — 調整字母之間的間距。
• lineHeight — 定義行高（文字行間距）。
• textAlign — 設定文字對齊方式（如左對齊、居中對齊、右對齊）。
• textColumns — 控制文字列數。
• textDecoration — 設定文字裝飾（如下劃線）。
• writingMode — 定義書寫模式（如水平、垂直）。
• textTransform — 控制文字的轉換（如大寫、小寫）。

例如，您可以將所有標題的字型粗細設定為 300，並使用斜體樣式：

"blocks": {
"core/heading": {
"typography": {
"fontWeight": "300",
"fontStyle": "italic"
}
}
}

所有標題都包含斜體和加粗樣式屬性。

模板和樣板屬性

這三個頂級屬性用於在主題中註冊自定義資產。

1. 自定義模板

templates 屬性用於為各種文章型別註冊自定義模板。

• name– 位於 templates 子目錄中的 .html 或 .php 檔案的名稱。
• title– 將分配給模板的標題，以便於識別。
• postTypes– 指定模板用於呈現的內容型別（如文章、頁面）。

2. 模板部分

templateParts 屬性用於定義模板的可重複使用部分（如頁首、頁尾）。

• name – 位於 parts 子目錄中的 .html 或 .php 檔案的名稱。
• title – 模板部分的標題，以便於識別。
• area – 指定模板部分適用於頁面的哪個部分（如header, footer, sidebar）。

3. 樣板

通過 patterns 屬性，你可以從 WordPress 樣板目錄中註冊一個模式短語陣列，使它們在主題中可用。

以下是註冊樣板的方法：

"patterns": [
"my-custom-pattern-slug"
]

使用theme.json的三個實用示例

以下是您可能希望為正在開發的主題做的幾件事。

1. 新增樣板

下面是如何從 WordPress 樣板目錄中新增兩種樣板。這裡顯示的是 “全屏封面圖片庫 ”樣板：

"patterns": [
"fullscreen-cover-image-gallery",
"hero-banner-with-overlap-images"
]

演示從 wordpress.org 插入樣板。

注意事項：

• 從樣板目錄中提取的模式不會顯示在網站編輯器的樣板部分。這些模式只能通過插入器獲取。
• 在本示例中，我們包含了頂層屬性 patterns（與 settings 和 styles 相比，為簡潔起見，我們在之前的示例中省略了它們）。

2. 新增自定義字型

我們從 Google 字型庫中下載了兩個字型檔案（Roboto-Regular.ttf 和 Roboto-Bold.ttf ），並將它們上傳到主題的 assets/fonts/ 子目錄中。

以下程式碼將註冊這兩種字型，使它們在全站範圍內可用：

"settings": {
"typography": {
"fontFamilies": [
{
"fontFamily": "Roboto",
"name": "Roboto",
"slug": "roboto",
"fontFace": [
{
"fontFamily": "Roboto Regular",
"fontWeight": "400",
"fontStyle": "normal",
"src": [
"file./assets/fonts/Roboto-Regular.ttf"
]
},
{
"fontFamily": "Roboto Bold",
"fontWeight": "700",
"fontStyle": "bold",
"src": [
"file./assets/fonts/Roboto-Bold.ttf"
]      
}  
]
}
]
}
}

顯示包含的 Google 字型。

3. 設定調色盤

如果要限制使用者使用特定的調色盤，可以這樣配置。(漸變和雙色調也可以根據您的要求進行配置）。

例如：

"settings": {
"color": {
"custom": false,
"defaultPalette": false,
"palette": [
{
"slug": "primary",
"color": "#1e8cbe",
"name": "Primary"
},
{
"slug": "secondary",
"color": "#21759b",
"name": "Secondary"
},
{
"slug": "tertiary",
"color": "#",
"name": "Tertiary"
},
{
"slug": "accent",
"color": "#464646",
"name": "Accent"
}
]
}
}

演示自定義主題顏色。

認識這四種顏色嗎？它們是 WordPress 顏色故事的一部分。

小結

本文重點介紹了 theme.json 在現代 WordPress 主題開發中的關鍵作用。掌握了 theme.json，你就可以完全自定義主題的視覺設計和使用者介面，而無需複雜的 PHP 或 CSS 過載。

瞭解如何有效使用 appearanceTools 等屬性，可以在構建或改進 WordPress 主題時提供更強的控制力和更高的效率，使該檔案成為希望建立靈活、使用者友好主題的開發人員的必備工具。