theme.jsonファイルの構造とプロパティを理解することは、ブロックテーマ開発の基本。theme.jsonはブロックベースのテーマの主要な要素を制御する「ハブ」として機能します。
テーマをゼロから構築する場合、既存のテーマをカスタマイズする場合、スタイルバリエーションを開発する場合、あるいは子テーマを編集する場合でも、theme.jsonを扱うことになります。
幸い、JSON（JavaScript Object Notation）は、データを一般的なものから特定のプロパティに整理する階層構造を持ち、読むことができる形式になっています。theme.jsonの文脈では、JavaScriptに関する深い知識よりも、CSS（Cascading Style Sheets）に精通していることの方が重要になります。
今回は、theme.json内のプライマリおよびセカンダリ（ネストされた）プロパティを紐解き、主要な設定とスタイルプロパティについてご説明します。これらはファイルの中核となる要素です。各要素の説明とコード例も取り上げます。
なお、本記事はすでに公開済みの記事『theme.jsonの活用方法─WordPressテーマを賢くカスタマイズ』内の「theme.jsonファイルのプロパティを使用する」セクションをもとに書かれています。
ブロックテーマにおけるスタイルのレンダリング
WordPressは組み込みのカスケード処理を用いてサイトのスタイルをレンダリングします。複数のソースが同じ設定やスタイルを定義している場合は、以下の優先順位で適用されます。
- WordPressコア：デフォルト設定を記述した
theme.jsonは、wp-includesディレクトリに格納されている。このファイルはWordPressのメジャーリリースと同時に更新されるため編集不可。 - テーマ：テーマ開発者がテーマの設定、スタイル、その他のプロパティを定義するために使用する主要な
theme.json。 - スタイルバリエーション：テーマにスタイルバリエーションが含まれている場合、各
theme.jsonファイルがテーマのstylesサブディレクトリに保存される。 - 子テーマ：標準的なテーマと同様、親テーマのファイルを直接編集することなく、カスタマイズすることができる（任意）。
- 子テーマのスタイルバリエーション：通常のスタイルバリエーションと同様、子テーマはstylesサブディレクトリに独自の
theme.jsonを持つことができる（任意）。 - ユーザーが作成したスタイル：WordPressのエディター（固定ページ、投稿、またはサイト全体）で追加され、データベースに保存されたカスタムスタイル。
上記の順序に従って、優先度の高いソースからのスタイルが優先度の低いソースからのスタイルを上書きします。例えば、テーマのtheme.jsonの設定は、WordPressコアのtheme.jsonを上書きします。同様に、子テーマのスタイルバリエーションは、親テーマのスタイルバリエーションよりも優先されます。
ユーザーが作成したスタイルが最も優先度が高くなり、他のすべてのスタイルを上書きします。
今回は、WordPressブロックテーマのルートディレクトリにあるtheme.jsonに焦点を当てます。
プライマリプロパティとそのキー/値
theme.jsonの7つのトップレベルオブジェクトをご紹介します。理解しやすいよう、3つのセクションに分類します。
本記事での定義
theme.jsonで作業を行うと、重要なコンポーネントの定義が異なる場合があります。この記事では、それぞれ以下のように定義します。
- セクション：トップレベルのグループ（「トップレベルオブジェクト」とも呼ばれる）
- オブジェクト：
settingsやstylesなど、theme.json内の主要なコンポーネント - プロパティ：オブジェクト内の構成要素（例えば、
settingsオブジェクトには12の異なるプロパティが含まれる） - キー/値のペア：プロパティはキーと値のペアで構成される。「キー」はプロパティの属性を表し、引用符（””）で囲まれ、「値」はブール値、文字列、配列のいずれかになる。
「デフォルトで」は、wp-includes/theme.jsonにあるコアtheme.jsonのデフォルト設定を指します。
「ユーザー」は、サイト、固定ページ、投稿のエディターで設定を変更できるWordPressサイトの管理者を指します。
構文の概要
- ブール値は引用符で囲まない
- 文字列は二重引用符で囲む
- 配列は角括弧（
[]）で囲む - オブジェクトは中括弧（
{}）で囲み、複数のプロパティや入れ子になったオブジェクトを含む - カンマはオブジェクト内の複数のキーと値のペアを区切るために使用
以下は一般的な構文の例です。
{
"house": {
"rooms": "kitchen"
}
}プロパティの分類
説明を理解しやすくするため、プロパティを以下3つに分けて見ていきます。
- 基本プロパティ
- 設定とスタイルのプロパティ
- テンプレートとパターンのプロパティ
また、コード例も理解しやすくなるよう、外側のラッパーオブジェクトを一部省略します。
{
"settings": {
"appearanceTools": false,
"background": {
"backgroundImage": true
}
}
}また、上記のように構造全体を示す代わりに、以下のように省略することがあります。
"appearanceTools": false,
"background": {
"backgroundImage": true
}基本的なプロパティ
theme.jsonファイルの冒頭には、通常$schemaとversionという2つの重要なプロパティがあります。これらのプロパティはファイルの先頭に置かれます。現在のスキーマバージョンは3で、WordPress 6.6で導入されています。
"$schema": "https://schemas.wp.org/wp/6.6/theme.json", "version": 3設定とスタイルのプロパティ
設定プロパティは一般的にfunctions.phpファイルで設定され、クラシックテーマでいうところのWordPress管理画面「外観」＞「カスタマイズ」で表示される機能にあたります。
スタイルは、styles.cssファイルに存在していたCSSプロパティに似たもので、テーマのレイアウトとデザインを制御します。
設定
blockとelementsプロパティを除き、その他の設定はすべてグローバルになります。設定の多くはboolean型で、UI機能を有効または無効にするトグルとして機能します。
注意点として、すべてのキーがすべての文脈で適用されるわけではありません。例えば、段落ブロックの高さの最小値は設定することができません。
appearanceTools（外観ツール）
"appearanceTools": trueを使用して一括または個別に有効化できます。
この機能を有効にすると、WordPressエディターのさまざまなUIオプションが表示され、開発を効率化することができます。デフォルトでは無効になっています（"appearanceTools": false）。
appearanceTools内のキーには以下が含まれます。
backgroundbackgroundImage─ブロックに背景画像を追加backgroundSize─背景画像の拡大縮小方法を定義（カバー、コンテントなど）
bordercolor─枠線の色を選択style─枠線のスタイル（実線、破線、点線など）を選択width─枠線の太さを選択radius─枠線の半径を調整して角を丸く設定
colorlink─コンテンツ内のリンクの色を設定heading─見出しタグ（<h1>、<h2>）の色を設定button─テーマ内のボタンの色を設定caption─キャプションのカスタムカラーを設定
dimensionsaspectRatio─ブロックの幅と高さの比率を設定minHeight─ブロックの高さの最小値を設定
positionsticky─ブロックを固定表示
spacingblockGap─ブロック間の間隔を調整margin─ブロックの周りの余白を調整padding─ブロック内の余白を調整し、コンテンツと境界線の間の余白を定義
typographylineHeight─行の高さ（テキストの行間）を調整し、可読性を向上
例：他の外観ツールは無効にしたまま、ユーザーが背景画像を追加できるようにします。
"appearanceTools": false,
"background": {
"backgroundImage": true
}
blocks（ブロック）
ユーザーはblocksプロパティを使用してブロックごとに設定を行い、グローバル設定を上書きすることができます。
例：appearanceToolsをfalseに設定したまま、ブロックの枠線の設定だけを個別に有効にします。
"border": {
"color": true,
"style": true,
"width": true,
"radius": true
}
color（色）
colorプロパティを使用すると、背景色、テキスト色、グラデーションなどの色を設定できます。
colorプロパティのキーは以下のとおりです。
background─ブロックや要素の背景色を設定custom─ユーザーがカスタムカラーを選択する機能を有効または無効化customDuotone─画像にカスタムデュオトーンフィルターを適用customGradient─カスタムグラデーションオプションを有効化defaultDuotone─デフォルトのデュオトーン画像フィルターを提供defaultGradient─ユーザーが利用できるデフォルトのグラデーションオプションを定義defaultPalette─テーマのデフォルトのカラーパレットを設定duotone─画像にデュオトーンフィルターを設定gradient─背景やその他の要素のグラデーションオプションを有効化link─テーマ内のリンクの色を設定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（寸法）
dimensionsプロパティは、幅、高さ、縦横比などのブロック寸法の設定を提供してくれます。
dimensions プロパティ内のキーは以下の通りです。
aspectRatio─ブロックの縦横比（16:9、4:3など）を設定またはロックdefaultAspectRatios─ブロックのデフォルトの縦横比を定義minHeight─ブロックの高さの最小値を設定
例：ユーザーがサポートされているブロックの高さの最小値を設定できるようにします。
"dimensions": {
"minHeight": true
}
layout（レイアウト）
layoutプロパティでは、コンテンツの幅やレイアウトのカスタマイズの可否など、レイアウト関連のオプションを設定できます。これにより、ユーザーはこれらのキーでレイアウトオプションを設定することができます：
contentSize─ブロックのデフォルトの幅を設定wideSize─wide alignment（幅広揃え）が選択されているときのブロックの幅を定義allowEditing─ユーザーがレイアウト設定を調整できるかどうかを決定allowCustomContentAndWideSize─contentSizeとwideSizeのカスタマイズを可能に
例：デフォルト幅と幅広（ワイド）幅を使ってレイアウト設定を構成します。
"layout": {
"contentSize": "620px",
"wideSize": "1000px"
}
Lightbox
lightboxプロパティを使用すると、画像の「クリックで拡大」機能を有効にすることができます。
lightboxプロパティ内のキーは以下のとおりです。
enabled─Lightbox機能を有効または無効化allowEditing─Lightboxの設定を切り替え
例：ユーザーが画像のLightbox機能を切り替えられるようにします。
"blocks": {
"core/image": {
"lightbox": {
"allowEditing": true
}
}
}
position（位置）
positionプロパティは、ユーザーがブロックの位置を制御できることを可能にします。
例：ブロックを固定表示するようにします。
"position": {
"sticky": true
}影
shadowプロパティは、プリセットまたは独自に定義された影を使用して、ブロックに影を適用することができます。
shadowプロパティ内のキーは以下のとおりです。
defaultPresets─デフォルトのプリセットを有効または無効化presets─カスタムプリセットを定義
例：デフォルトの影を無効にし、独自の影「Natural」定義します。
"shadow": {
"defaultPresets": false,
"presets": [
{ "name": "Natural", "slug": "natural", "shadow": "6px 6px 9px rgba(0, 0, 0, 0.2)" }
]
}
左から1〜3の順に進み、最後のステップ3では影「Natural」が示されています。
spacing（余白）
spacingプロパティは、エディターでの余白（パディング、マージン、ギャップ）の管理方法を定義します。
spacingプロパティ内のキーは以下のとおりです。
blockGap─ブロック間のギャップ（隙間）を設定margin─ブロックの周囲にマージンを設定padding─ブロック内のパディングを設定units─余白に使用する単位を定義（px、remなど）customSpacingSize─ユーザーが独自の余白サイズを設定できるようにspacingSizes─プリセットの余白サイズの範囲を定義spacingScale─余白単位のスケーリングを可能に
例：パディング、マージン、幅、高さに使用する単位を2種類（pxとrem）に制限し、appearanceToolsをtrueに設定してサイトエディターに余白調整のセクションを表示します。
"spacing": {
"units": ["px", "rem"]
}
typography（タイポグラフィ）
typographyプロパティは、フォントサイズ、ウェイト（文字の太さ）、行の高さなど、テーマのテキストにまつわる設定を定義します。
typographyプロパティ内のキーは以下のとおりです。
defaultFontSizes─ユーザーが利用できるデフォルトのフォントサイズを定義customFontSize─カスタムフォントサイズの設定機能を有効または無効化fontStyle─フォントのスタイルを制御（標準、斜体）fontWeight─フォントの太さ（太字、細字など）を設定flui─画面サイズに応じてフォントサイズを動的に調整するフルードタイポグラフィを有効化letterSpacing─文字の間隔を制御lineHeight─テキストの各行の高さを設定textAlign─テキストの配置（左、中央、右など）を調整できるようにtextDecoration─テキストの装飾（下線など）のオプションを提供writingMode─テキストのレイアウトを設定（横書き、縦書きなど）
例：カスタム文字サイズとドロップキャップの両方を無効にします。
"typography": {
"customFontSize": false,
"dropCap": false
}
この場合、赤く強調されたセクションがエディターに表示されなくなります。
useRotPaddingAwareAignments（ルート要素のパディングを考慮した配置）
useRootPaddingAwareAlignementsプロパティをtrueに設定すると、ページのルート要素（<html>や<body>）に適用されたパディングを考慮して、wide（幅広）やfull-width（全幅）のブロックの配置が適切に調整されるようになります。これにより、パディングが適用されている場合でも正しい配置が確保されます。
例
"useRootPaddingAwareAlignments": truetrueに設定すると、ルートの上、右、下、左のパディング値もスタイルとして定義しなければなりません（これについては後ほど）。
"spacing": {
"padding": {
"top": "0",
"right": "100px",
"bottom": "0",
"left": "100px"
}
}
上で見たコードのようにuseRootPaddingAwareAlignementsの設定、および左右のパディングを本文に適用すると、以下のようになります。
styles（スタイル）
stylesプロパティを使用すると、テーマのルート（デフォルト）、特定の要素、または個々のブロックにCSSスタイルを適用できます。
背景スタイル
画像、位置、添付ファイルなど、背景にまつわるプロパティを制御します。
背景に共通するキーは以下のとおりです。
backgroundImage─ブロックまたは要素の背景画像を定義backgroundPosition─背景画像の位置を設定する（中央、右上など）backgroundRepeat─背景画像を繰り返すかどうかを指定（repeat、no-repeatなど）backgroundSize─背景画像のサイズを制御（cover、containなど）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（カラースタイル）
colorプロパティを使用すると、背景色、グラデーション、テキスト色の設定を制御できます。
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（寸法）
dimensionsプロパティでは、ブロックの幅、高さ、縦横比を制御できます。
dimensionsプロパティのキーは以下のとおりです。
aspectRatios─要素のカスタム縦横比を定義minHeight─ブロックの高さの最小値を設定
例：画像ブロックのカスタム縦横比を3:7に設定します。
"blocks": {
"core/image": {
"dimensions": {
"aspectRatio": "custom"
}
}
}ただし、上記だけでは不十分で、「custom」スタイルを設定セクションに登録する必要があります。
"dimensions": {
"defaultAspectRatios": true,
"aspectRatios": [
{
"name": "Custom Ratio 3:7",
"slug": "custom",
"ratio": "3/7"
}
]
}
上のスクリーンショットで、独自の縦横比（Customr Ratio）が追加されていることがわかります。デフォルトの7つの縦横比を無効にするには、設定セクションから"defaultAspectRatios":trueを削除します。
elements（要素固有のスタイル）
elementsプロパティは、リンクやボタン、見出しなどの特定のHTML要素にスタイルを適用することができます。
例：すべてのリンクのテキスト装飾（下線）を無効にします。
"elements": {
"link": {
"typography": {
"textDecoration": "none"
}
}
}
filter（フィルター）
filterプロパティを使用すると、画像などの特定のブロックにCSSのようなフィルター効果（ぼかし、明るさなど）を適用できます。
例：画像ブロックにぼかしと明るさのフィルターを適用します。
"blocks": {
"core/image": {
"filter": {
"duotone": "blur(5px) brightness(0.8)"
}
}
}
上のスクリーンショットでは、画像ブロックにぼかしと明るさの効果が適用されています。他にも以下のようなものがあります。
contrast─要素のコントラストを調整grayscale─要素をグレースケールに変換invert─要素の色を反転opacity─要素の透明度を設定saturate─色の彩度を調整sepia─要素にセピアフィルターを適用
outline（輪郭）
outlineプロパティは、レイアウト空間に影響を与えることなく、要素の境界線の外側に描画される輪郭のスタイルを定義します。
outlineプロパティには以下のキーがあります。
color─輪郭の色を設定offset—枠線と輪郭の間の間隔を制御style─輪郭のスタイル（点線、実線など）を指定width─輪郭の幅を設定
例：ボタンに赤い点線の輪郭を適用します。
"elements": {
"button": {
"outline": {
"color": "#ff0000",
"style": "dotted",
"width": "4px"
}
}
}
shadow（影のスタイル）
shadowプロパティを使用すると、画像ブロックに影を適用（ボックスシャドウ）を適用し、要素を強調することができます。
例：すべての画像に影を適用します。
"blocks": {
"core/image": {
"shadow": "0 10px 20px 0 rgb(0 0 225 / 0.50)"
}
}
spacing（余白のスタイル）
spacingプロパティは、テーマの余白（パディング、マージン、ブロックギャップ）のスタイルを制御します。
spacingプロパティのキーは以下のとおりです。
blockGap─ブロックとブロックの間隔（ギャップ）を調整margin─ブロックの周囲に余白（マージン）を設定padding─ブロック内の余白（パディング）を設定
例：左右に独自のパディングを設定します。
"spacing": {
"padding": {
"left": "min(6.5rem, 8vw)",
"right": "min(6.5rem, 8vw)"
}
}
typography（タイポグラフィのスタイル）
typographyプロパティは、フォントスタイルやサイズなど、テキストにまつわる設定を制御します。
typographyプロパティの主なキーは以下のとおりです。
fontFamily─テキストのフォントファミリーを設定fontSize─フォントサイズを定義fontStyle─フォントのスタイルを指定（標準、斜体など）fontWeight─フォントの太さを調節letterSpacing─文字の間隔を調整lineHeight─行の高さ（テキストの行間）を定義textAlign─テキストの配置を設定（左、中央、右など）textColumns─テキストの列数を制御textDecoration─テキストの装飾（下線など）を設定writingMode─書き込みモード（水平、垂直など）を定義textTransform─書き込みモード（水平、垂直など）を定義
例：すべての見出しの太さ（ウェイト）を300に設定し、斜体のスタイルを適用します。
"blocks": {
"core/heading": {
"typography": {
"fontWeight": "300",
"fontStyle": "italic"
}
}
}
テンプレートとパターンのプロパティ
以下3つのトップレベルプロパティは、テーマにカスタムアセットを登録するために使用されます。
1. カスタムテンプレート
templatesプロパティは、様々な投稿タイプのカスタムテンプレートを登録するために使用します。
name─templatesサブディレクトリにある.htmlまたは.phpファイルの名前title─識別しやすいようにテンプレートに割り当てられるタイトルpostTypes─テンプレートがレンダリングするコンテンツのタイプ（投稿、固定ページなど）を指定
2. テンプレートのパーツ
templatePartsプロパティは、テンプレートの再利用可能な部分（ヘッダーやフッターなど）を定義するために使用します。
name─partsサブディレクトリにある.htmlまたは.phpファイルの名前title─識別しやすくするためにテンプレート部分につけられたタイトルarea─テンプレートパーツがページのどの部分に適用されるかを指定（header、footer、sidebarなど）
3. パターン
patternsプロパティは、ブロックパターンディレクトリからパターンスラッグの配列を登録し、テーマで利用できるようにします。
パターンの登録方法は以下のようになります。
"patterns": [
"my-custom-pattern-slug"
]theme.jsonを使用した3つの実践例
最後にテーマの開発において、よく行われる実践例をご紹介します。
1. パターンの追加
WordPressのブロックパターンディレクトリから2つのパターンを追加します。ここでは例として、「Fullscreen cover image gallery」を使用します。
"patterns": [
"fullscreen-cover-image-gallery",
"hero-banner-with-overlap-images"
]
注意事項
- パターンディレクトリから引き出したパターンは、サイトエディターの「パターン」セクションには表示されません。インサータからのみ利用可能です。
- 上の例には、トップレベルのプロパティ
patternsが含まれています（settingsとstylesを比較して、簡素化するために前述の例では省略）。
2. カスタムフォントの追加
Google Fontsライブラリから2つのフォントファイル（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"
]
}
]
}
]
}
}
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"
}
]
}
}
ちなみに、上の4色はWordPress公式カラーの一部です。
まとめ
今回は、最新のWordPressテーマ開発においてtheme.jsonが果たす重要な役割について焦点を当てました。theme.jsonを使いこなすことで、複雑なPHPやCSSによる上書きなしで、テーマの視覚的デザインとユーザーインターフェースを柔軟にカスタマイズすることができます。
appearanceToolsのようなプロパティの効果的な使い方を習得すれば、WordPressテーマの構築や改善の際に、より高度な機能や効率性を提供することができます。theme.jsonファイルは、柔軟かつ使いやすいテーマを構築したい開発者にとって必要不可欠な存在になります。
Bud Kraus has been working with WordPress as an in-class and online instructor, site developer, and content creator since 2009. He has produced instructional videos and written many articles for WordPress businesses.
