使用帶有 WordPress 塊編輯器的設計系統 Pt。 1：主題.json

在我們之前的博客文章中，我們展示瞭如何將您的設計系統從 Figma 導入到 WordPress 主題的 theme.json 中。 通過這樣做，您可以確保整個數字資產的持續一致性。

我們新的兩部分系列在此基礎上構建，向您展示如何在塊編輯器中使用從 theme.json 導入的設計標記。 這將使您能夠更好地組織您的 WordPress 網站以反映您的設計系統。 有兩個關鍵目標：

• 了解 theme.json 中與設計系統相關的部分
• 修改和擴展 theme.json 以利用導入的設計系統

了解 theme.json

theme.json 是一個配置文件，允許您配置塊編輯器和設置主題、更改塊設置以及構建開發整個塊主題的基礎。

它旨在讓您控制 WordPress 網站的全局設置和样式。 每個新的 WordPress VIP 站點都默認帶有二十二十三主題，一個塊主題。 這個主題是嘗試輕量級塊主題和了解 theme.json 中可用的一些強大控件的絕佳起點。

修改 theme.json

讓我們從上一篇博文中使用的 theme.json 開始。 請注意自定義部分，我們的橋接工具可以在其中插入和更新來自 Figma 的設計系統。 這是您引用設計系統的各種組件（設計令牌）以實際有效使用 theme.json 的關鍵部分。

下面我們將介紹技巧和策略，以便您可以利用 theme.json 必須提供的一切。

存儲設計令牌

雖然可以使用橋接工具自定義設計標記的位置，但它們應始終保留在設置的自定義部分中。 這是橋接工具的默認位置，不應更改。 這樣可以將它們正確地組織在一個位置，並可能有助於避免與現有的自定義主題部分發生衝突。

使用設計令牌

讓我們看一個使用 theme.json 的自定義部分的示例。 這裡我們有一個片段，我們定義了綠色的主要文本顏色和黑色的背景：

 "settings": { "custom": { "text": { "primary": "#00FF00", “background”: “000000” } } } }

這允許我們使用以下方法在 theme.json 中的任何位置引用這兩種顏色：

 var(--wp--custom--text--primary) and var(--wp--custom--text--background)

以下代碼段確保默認情況下，除非另有說明，否則每個塊都將具有黑色背景和綠色文本：

 "styles": { "color": { "text": "var(--wp--custom--text--primary)", “background”: “var(--wp--custom--text--background)” } }

您要從自定義設置中引用的任何鍵的架構是：

 var(--wp--custom–<location to the value with -- as a separator between each key>)

好處是您可以使用這些鍵引用所有設計令牌，同時擁有一個管理實際值的中央位置。

最佳實踐

• 使用 WordPress 生成的設計標記變量（例如var(--wp--custom--text--primary) ）在任何地方引用標記。 請注意上面提供的代碼片段，我們在其中引用主要和背景自定義顏色，而不是使用實際值本身。 這確保了當您想要更新文本顏色等屬性時，您只需更改一個位置，因為其他位置只是引用。
• 插入到 theme.json 中的設計標記也可以通過 theme.json 外部的 CSS 訪問，使用上面顯示的相同鍵引用。 這適用於塊開發和主題中使用的其他組件。 它們並不意味著只能在 theme.json 中使用，應該在任何自定義 CSS 中重複使用。

我們建議遵循這兩種最佳實踐，以將 theme.json 保持為單一的真實來源。 它將允許您輕鬆更新設計令牌，尤其是當您使用自動化工具時，例如 WordPress VIP 的連接到 Figma 的橋接工具。

修改編輯器和塊樣式

上面的代碼片段是深入研究自定義塊樣式方式的好方法。 例如，您可以更改塊的默認樣式以及可從塊編輯器中選擇的預設。 當您想要更細化並準確指定站點中使用的內置塊的外觀時，這很有用。

theme.json中有兩個關鍵位置：

• Settings 和 settings.blocks——允許自定義塊編輯器中通常可用的設置，以及為各個塊類型定制的設置。
• Styles 和 styles.blocks——允許為整個塊編輯器和每個塊自定義定義預設樣式。

例如，以下是如何確保所有標題都具有默認的綠色（主要）顏色和輔助顏色選項：

 "settings": { "custom": { "text": { "primary": "#00FF00", “secondary”: “#FF0000” } }, “blocks”: { “core/heading”: { “color”: { “text”: true, “palette”: [ { "slug": "primary", "color": "var(--wp--custom--text--primary)", "name": "Primary" }, { "slug": "secondary", "color": "var(--wp--custom--text--secondary)", "name": "Secondary" } ] } } } }, "styles": { "blocks": { “core/heading”: { “color”: { "text": "var(--wp--custom--text--primary)" } } } }

這會將每個標題塊配置為具有主要的綠色文本顏色，並添加第二個塊編輯器選項以將顏色更改為紅色輔助顏色。 注意：這需要一些重複。 樣式指定默認的主色，調色板將相同的顏色與輔助色組合在一起，以在塊編輯器中提供這兩個選項。

造型警告

盡可能只使用 theme.json 的 styles 和 styles.blocks 部分來設置塊的樣式。 除非絕對需要，否則不要使用 CSS 樣式來覆蓋核心塊樣式。 塊樣式的 CSS 覆蓋通常不穩定——塊編輯器更新會改變樣式和結構，導致這些樣式被破壞。

每塊定制

雖然上面的示例顯示瞭如何自定義塊的設置和样式，但也可以完全禁用自定義並將塊編輯器選項限制為特定塊。 這對於嚴格控制哪些選項可用於創建內容、維護設計系統的外觀很有用。

讓我們繼續另一個顏色設置示例，其中相同的原則適用於其他可配置屬性，如顏色、排版和間距。 要禁用在除標題塊之外的任何地方更改默認文本顏色的功能，可以配置 theme.json 的方法如下：

 "settings": { "custom": { "text": { "primary": "#00FF00", “secondary”: “#FF0000” } }, “color”: { “text”: false }, “blocks”: { “core/heading”: { “color”: { “text”: true, “palette”: [ { "slug": "primary", "color": "var(--wp--custom--text--primary)", "name": "Primary" }, { "slug": "secondary", "color": "var(--wp--custom--text--secondary)", "name": "Secondary" } ] } } } }

此示例顯示通過設置配置全局設置，以及通過設置下的塊部分配置特定於塊的設置。 這也適用於全局樣式（在根樣式屬性下可用）和特定於塊的樣式（在 styles.blocks 下）。

簡單的預設模板

開始創建設計系統的一個好方法是全局鎖定塊編輯器設置。 之後，您可以逐步啟用各個塊的設置並控制您的設計系統的外觀和感覺，而不會被自定義選項所淹沒。首先，這是一組簡單的設置，WordPress VIP 的設計系統使用它來全局禁用所有邊框、顏色、排版和間距控件默認情況下在編輯器中：

 { "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 2, "settings": { "appearanceTools": true, "border": { "color": false, "radius": false, "style": false, "width": false }, "color": { "text": false, "background": false, "link": false, "custom": false, "defaultPalette": false, "defaultGradients": false, "defaultDuotone": false, "customGradient": false, "customDuotone": false, "palette": [ // Design system palette colors... ], "gradients": [ // Design system gradients... ] }, "spacing": { "margin": false, "padding": false, "units": ["rem", "%"] }, "typography": { "customFontSize": false, "fontStyle": false, "fontWeight": false, "letterSpacing": false, "lineHeight": false, "textDecoration": false, "textTransform": false, "dropCap": false, "fontFamilies": [], "fontSizes": [] } } }

有了這些鎖定的默認值，您就可以使用 settings.blocks 在編輯器中公開特定塊的選項，並將自定義限制為定義明確的設置。

綜上所述

Theme.json 是一個強大的工具，用於組織全局設計標記、設置全局主題樣式和自定義單個塊。 利用塊編輯器為定制公開的所有功能，使設計系統實現集中並與內置塊編輯器兼容。

在我們系列的第 2 部分中，我們將介紹 theme.json 之外的更多高級技巧，用於管理設計系統中的內置塊類型和样式。

有用的鏈接

• 什麼是 Theme.json？
• 全局設置和样式 (theme.json)

作者

Automattic 高級軟件開發人員 Alec Geatches

居住在台灣台北的企業 WordPress 開發人員和設計系統愛好者。

Gopal Krishnan，Automattic 高級軟件開發人員

Gopal 致力於 WordPress VIP 的解耦 WordPress 產品，對設計系統和古騰堡感興趣。 他居住在澳大利亞悉尼，最近剛從加拿大搬來。