WordPress.org

日本語

WordPress を入手
WordPress.org

Japanese Team

グローバル設定とスタイル (theme.json)

グローバル設定とスタイル (theme.json)

この投稿内

↑ ページの先頭へ戻る

WordPress 5.8ではエディターを構成する新しいメカニズムが搭載されました。きめ細かな制御を可能にし、将来の WordPress リリースにおけるスタイル管理の最初のステップとなる theme.json ファイルです。

論拠

ブロックエディター API はさまざまな速度で進化しているため、苦痛に感じられる部分が大きくなってきました。これは特にテーマに影響する部分で顕著です。たとえば、エディターのプログラム的な制御や、ユーザー、テーマ、コアスタイルの好みを取りまとめるブロックスタイルシステム などです。

この文書では現在行われている、スタイルに関連するさまざまな API を一箇所に集める努力について、すなわち、テーマディレクトリのルートに配置する theme.json ファイルについて説明します。

ブロックエディターの設定

ブロックエディターの設定を定義する際、ねずみ算式に増えるテーマサポートフラグや代替方式の代わりに theme.json ファイルは正規の方法を提供します。例えば以下の設定が可能です。

  • ユーザーが利用可能なカスタマイズオプション。隠すカスタマイズオプション。
  • ユーザーが利用可能なデフォルトの色、フォントサイズ、等々
  • エディターのデフォルトレイアウトの定義。幅、利用可能な配置

設定をブロックごとに制御できる

より詳細のため、これらの設定は theme.json 内のブロックレベルでも動作します。

達成できることの例:

  • あるブロック(例: テーブル)に対して特定のプリセットを使用するが、残りのブロックでは一般的なものを使用する。
  • サポートするすべてのブロックでフォントサイズ UI コントロールを有効化するが、見出しブロックは除く。
  • など。

スタイルを管理できる

theme.json ファイルを使用して、構造化された形でスタイルプロパティを設定することで、ブロックエディターは異なるソース (ユーザー、テーマ、コア) から来る CSS を「管理」できます。たとえば、テーマとユーザーが段落にフォントサイズを設定しても、ユーザーのスタイルのみをエンキューし、テーマから来たスタイルをエンキューしない等。

この方法の利点:

  • エンキューされる CSS の量を減らす。
  • 「CSS 詳細度の戦い」を抑止する。

CSS カスタムプロパティ: プリセットとカスタム

スタイリングの領域には、サイト内で一度に変更できる共有の値があると便利な場合があります。

このニーズを満たすためいくつかの場所で、「CSS 変数」とも呼ばれる、CSS カスタムプロパティの実験を始めました。

入力

{
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{
					"name": "Black",
					"slug": "black",
					"color": "#000000"
				},
				{
					"name": "White",
					"slug": "white",
					"color": "#ffffff"
				}
			]
		}
	}
}

出力

body {
	--wp--preset--color--black: #000000;
	--wp--preset--color--white: #ffffff;
}
  • カスタムプロパティ: 自身の CSS カスタムプロパティを作成する仕組みもあります。

入力

{
	"version": 3,
	"settings": {
		"custom": {
			"line-height": {
				"body": 1.7,
				"heading": 1.3
			}
		}
	}
}

出力

body {
	--wp--custom--line-height--body: 1.7;
	--wp--custom--line-height--heading: 1.3;
}

仕様

この仕様は、同じフォーマットを仕様する3つの異なる主体、「コア」「テーマ」「ユーザー」で共通です。テーマは、ファイル theme.json を作成することでコアのデフォルトを上書きできます。ユーザーもまた、開発中のユーザーインターフェース、サイトエディターを介して、テーマやコアの設定を上書きできます。

{
	"version": 3,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {}
}

単一ブロックが異なる HTML マークアップを表すケースがいくつかあります。見出しブロックはその一例で、h1 から h6 の HTML 要素を表します。この場合、見出しブロックは異なるマークアップ core/heading/h1、core/heading/h2、… と同じ数のブロックセレクタを持ち、それぞれ個別に処理します。

{
  "styles": {
    "core/heading/h1": { ... },
    // ...
    "core/heading/h6": { ... },
  }
}

また、さらに2つの別のブロックセレクタ root と defaults があります。root ブロックセレクタは、サイトのルートを表します。defaults ブロックセレクタは、何も宣言されなかった場合にブロックで使用されるデフォルトを表します。

version

このフィールドは、theme.json ファイルのフォーマットを表します。最新のバージョンは version 3 で WordPress 6.6 で導入されました。

新しいバージョンは、破壊的な変更を加える必要がある場合に導入されます。これにより、テーマの作者は、いつ破壊的な変更に対応し、theme.json ファイルを新しい形式に移行するかを選択できます。

古いバージョンの theme.json には後方互換性があり、新しいバージョンの WordPress や Gutenberg プラグインでも引き続き動作します。ただし、新しい機能は最新バージョンの上で開発されます。

最新バージョンへのアップデートの詳細については、新しいバージョンへの移行の指示に従ってください。

settings

Gutenberg プラグインは、WordPress 5.8で利用可能な設定を拡張しています。このため、他のバージョンの WordPress でも利用でき、コアに移植される前に機能の成熟プロセスを経ます。

次のセクションでは、WordPress 5.8でサポートされる設定と、Gutenberg プラグインでサポートされる設定を示します。

settings セクションは以下の構造を持ちます。

WordPress

{
	"version": 3,
	"settings": {
		"border": {
			"radius": false,
			"color": false,
			"style": false,
			"width": false
		},
		"color": {
			"custom": true,
			"customDuotone": true,
			"customGradient": true,
			"duotone": [],
			"gradients": [],
			"link": false,
			"palette": [],
			"text": true,
			"background": true,
			"defaultGradients": true,
			"defaultPalette": true
		},
		"custom": {},
		"layout": {
			"contentSize": "800px",
			"wideSize": "1000px"
		},
		"spacing": {
			"margin": false,
			"padding": false,
			"blockGap": null,
			"units": [ "px", "em", "rem", "vh", "vw" ]
		},
		"typography": {
			"customFontSize": true,
			"lineHeight": false,
			"dropCap": true,
			"fluid": false,
			"fontStyle": true,
			"fontWeight": true,
			"letterSpacing": true,
			"textDecoration": true,
			"textTransform": true,
			"fontSizes": [],
			"fontFamilies": []
		},
		"blocks": {
			"core/paragraph": {
				"color": {},
				"custom": {},
				"layout": {},
				"spacing": {},
				"typography": {}
			},
			"core/heading": {},
			"etc": {}
		}
	}
}

Gutenberg

{
	"version": 3,
	"settings": {
		"appearanceTools": false,
		"border": {
			"color": false,
			"radius": false,
			"style": false,
			"width": false
		},
		"color": {
			"background": true,
			"custom": true,
			"customDuotone": true,
			"customGradient": true,
			"defaultGradients": true,
			"defaultPalette": true,
			"duotone": [],
			"gradients": [],
			"link": false,
			"palette": [],
			"text": true
		},
		"custom": {},
		"dimensions": {
			"aspectRatio": false,
			"height": false,
			"minHeight": false,
			"width": false,
		},
		"layout": {
			"contentSize": "800px",
			"wideSize": "1000px"
		},
		"spacing": {
			"blockGap": null,
			"margin": false,
			"padding": false,
			"customSpacingSize": true,
			"units": [ "px", "em", "rem", "vh", "vw" ],
			"spacingScale": {
				"operator": "*",
				"increment": 1.5,
				"steps": 7,
				"mediumStep": 1.5,
				"unit": "rem"
			},
			"spacingSizes": []
		},
		"typography": {
			"customFontSize": true,
			"dropCap": true,
			"fluid": false,
			"fontFamilies": [],
			"fontSizes": [],
			"fontStyle": true,
			"fontWeight": true,
			"letterSpacing": true,
			"lineHeight": false,
			"textAlign": true,
			"textColumns": false,
			"textDecoration": true,
			"textIndent": true,
			"textTransform": true
		},
		"blocks": {
			"core/paragraph": {
				"border": {},
				"color": {},
				"custom": {},
				"layout": {},
				"spacing": {},
				"typography": {}
			},
			"core/heading": {},
			"etc": {}
		}
	}
}

それぞれのブロックは個別にこれらの設定を構成でき、既存の add_theme_support を介したものよりも、詳細な制御を行えます。トップレベルで宣言されたブロック設定は、個別に上書きしない限り、すべてのブロックに影響します。継承のコンセプトを導入し、すべてのブロックを一度に構成できます。

注意: ただし、すべての設定がすべてのブロックに関連するわけではありません。settings セクションはテーマに対してオプトイン、オプトアウトの仕組みを提供しますが、関連する機能のサポートの追加はブロックの責任です。たとえばブロックが dropCap 機能を実装しなければ、テーマは theme.json を介して有効化できません。

UI コントロールへのオプトイン

特別な設定プロパティとして appearanceTools があります。ブール値で、デフォルト値は false です。テーマはこの設定を使用して、以下を有効化できます。

  • background: backgroundImage, backgroundSize
  • border: color, radius, style, width
  • color: link
  • dimensions: aspectRatio, height, minHeight, width
  • position: sticky
  • spacing: blockGap, margin, padding
  • typography: lineHeight

add_theme_support との後方互換性

後方互換性のため、ブロックエディターを構成する既存の add_theme_support の宣言は、トップレベルのセクションの適切なカテゴリーに割り当てられます。たとえば、テーマが add_theme_support('disable-custom-colors') を使用している場合、これは settings.color.custom に false を設定したことと同じです。theme.json 内に設定があれば、 add_theme_support を介して宣言された値に優先します。以下は、完全な対応リストです。

add_theme_supporttheme.json 設定
custom-line-heighttypography.lineHeight に true を設定
custom-spacingspacing.padding に true を設定
custom-unitsspacing.units で単位のリストを渡す
disable-custom-colorscolor.custom に false を設定
disable-custom-font-sizestypography.customFontSize に false を設定
disable-custom-gradientscolor.customGradient に false を設定
editor-color-palettecolor.palette で色のリストを渡す
editor-font-sizestypography.fontSizes でフォントサイズのリストを渡す
editor-gradient-presetscolor.gradients でグラデーションのリストを渡す
editor-spacing-sizesspacing.spacingSizes でスペースサイズのリストを渡す
appearance-toolsappearanceTools に true を設定
borderborder: color, radius, style, width に true を設定
link-colorcolor.link に true を設定

プリセット

プリセットは settings セクションの一部です。各プリセット値は新しいスタイルシートに追加される CSS カスタムプロパティを生成します。CSS カスタムプロパティは命名スキーマ --wp--preset--{preset-category}--{preset-slug} に従います。

プリセットは settings セクションの一部で、UI コントロールを介してユーザーに表示される値です。theme.json で定義することでエンジンは、自動的にプリセット名を翻訳したり、対応する CSS クラスやカスタムプロパティをエンキューするなどテーマに対して多くを実行します。

以下のプリセットを theme.json で定義できます。

  • color.duotone: クラスやカスタムプロパティを生成しません。
  • color.gradients: プリセット値ごとに1つのクラスとカスタムプロパティを生成します。
  • color.palette:
    • プリセット値ごとに3つのクラスを生成します: color、background-color、border-color
    • プリセット値ごとに1つのカスタムプロパティを生成します。
  • spacing.spacingSizes/spacing.spacingScale: プリセット値ごとに1つのカスタムプロパティを生成します。
  • typography.fontSizes: プリセット値ごとに1つのクラスとカスタムプロパティを生成します。
  • typography.fontFamilies: プリセット値ごとに1つのカスタムプロパティを生成します。

クラスとカスタムプロパティは次の命名スキーマに従います。

  • カスタムプロパティ: --wp--preset--{preset-category}--{preset-slug} 例: --wp--preset--color--black
  • クラス: .has-{preset-slug}-{preset-category} 例: .has-black-color.

入力

{
	"version": 3,
	"settings": {
		"color": {
			"duotone": [
				{
					"colors": [ "#000", "#FFF" ],
					"slug": "black-and-white",
					"name": "Black and White"
				}
			],
			"gradients": [
				{
					"slug": "blush-bordeaux",
					"gradient": "linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%)",
					"name": "Blush bordeaux"
				},
				{
					"slug": "blush-light-purple",
					"gradient": "linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%)",
					"name": "Blush light purple"
				}
			],
			"palette": [
				{
					"slug": "strong-magenta",
					"color": "#a156b4",
					"name": "Strong magenta"
				},
				{
					"slug": "very-dark-grey",
					"color": "rgb(131, 12, 8)",
					"name": "Very dark grey"
				}
			]
		},
		"typography": {
			"fontFamilies": [
				{
					"fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif",
					"slug": "system-font",
					"name": "System Font"
				},
				{
					"fontFamily": "Helvetica Neue, Helvetica, Arial, sans-serif",
					"slug": "helvetica-arial",
					"name": "Helvetica or Arial"
				}
			],
			"fontSizes": [
				{
					"slug": "big",
					"size": 32,
					"name": "Big"
				},
				{
					"slug": "x-large",
					"size": 46,
					"name": "Large"
				}
			]
		},
		"spacing": {
			"spacingScale": {
				"operator": "*",
				"increment": 1.5,
				"steps": 7,
				"mediumStep": 1.5,
				"unit": "rem"
			},
			"spacingSizes": [
				{
					"slug": "40",
					"size": "1rem",
					"name": "Small"
				},
				{
					"slug": "50",
					"size": "1.5rem",
					"name": "Medium"
				},
				{
					"slug": "60",
					"size": "2rem",
					"name": "Large"
				}
			]
		},
		"blocks": {
			"core/group": {
				"color": {
					"palette": [
						{
							"slug": "black",
							"color": "#000000",
							"name": "Black"
						},
						{
							"slug": "white",
							"color": "#ffffff",
							"name": "White"
						}
					]
				}
			}
		}
	}
}

出力

/* Top-level custom properties */
body {
	--wp--preset--color--strong-magenta: #a156b4;
	--wp--preset--color--very-dark-grey: #444;
	--wp--preset--gradient--blush-bordeaux: linear-gradient( 135deg, rgb( 254, 205, 165 ) 0%, rgb( 254, 45, 45 ) 50%, rgb( 107, 0, 62 ) 100% );
	--wp--preset--gradient--blush-light-purple: linear-gradient( 135deg, rgb( 255, 206, 236 ) 0%, rgb( 152, 150, 240 ) 100% );
	--wp--preset--font-size--x-large: 46;
	--wp--preset--font-size--big: 32;
	--wp--preset--font-family--helvetica-arial: Helvetica Neue, Helvetica, Arial, sans-serif;
	--wp--preset--font-family--system: -apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif;
	--wp--preset--spacing--20: 0.44rem;
	--wp--preset--spacing--30: 0.67rem;
	--wp--preset--spacing--40: 1rem;
	--wp--preset--spacing--50: 1.5rem;
	--wp--preset--spacing--60: 2.25rem;
	--wp--preset--spacing--70: 3.38rem;
	--wp--preset--spacing--80: 5.06rem;
}

/* Block-level custom properties (bounded to the group block) */
.wp-block-group {
	--wp--preset--color--black: #000000;
	--wp--preset--color--white: #ffffff;
}

/* Top-level classes */
.has-strong-magenta-color { color: #a156b4 !important; }
.has-strong-magenta-background-color { background-color: #a156b4 !important; }
.has-strong-magenta-border-color { border-color: #a156b4 !important; }
.has-very-dark-grey-color { color: #444 !important; }
.has-very-dark-grey-background-color { background-color: #444 !important; }
.has-very-dark-grey-border-color { border-color: #444 !important; }
.has-blush-bordeaux-background { background: linear-gradient( 135deg, rgb( 254, 205, 165 ) 0%, rgb( 254, 45, 45 ) 50%, rgb( 107, 0, 62 ) 100% ) !important; }
.has-blush-light-purple-background { background: linear-gradient( 135deg, rgb( 255, 206, 236 ) 0%, rgb( 152, 150, 240 ) 100% ) !important; }
.has-big-font-size { font-size: 32; }
.has-normal-font-size { font-size: 16; }

/* Block-level classes (bounded to the group block) */
.wp-block-group.has-black-color { color: #a156b4 !important; }
.wp-block-group.has-black-background-color { background-color: #a156b4 !important; }
.wp-block-group.has-black-border-color { border-color: #a156b4 !important; }
.wp-block-group.has-white-color { color: #444 !important; }
.wp-block-group.has-white-background-color { background-color: #444 !important; }
.wp-block-group.has-white-border-color { border-color: #444 !important; }

後方互換性のため、add_theme_support を介して宣言されたプリセットもまた CSS カスタムプロパティを生成します。theme.json に含まれるプリセットは add_theme_support を介して宣言されたプリセットに優先します。

プリセットクラスは、ユーザーアクションにより、投稿のコンテンツに付加されます。ユーザーのスタイルをテーマのスタイルに優先させるため、エンジンは !important を追加します。

カスタム

プリセット用の CSS カスタムプロパティの作成に加えてテーマは theme.json を使用して独自のプロパティを作成できます。別々にエンキューする必要はありません。custom フィールド内に定義された任意の値は、命名スキーマ --wp--custom--<variable-name> を持つ CSS カスタムプロパティに変換されます。

例:

入力

{
	"version": 3,
	"settings": {
		"custom": {
			"baseFont": 16,
			"lineHeight": {
				"small": 1.2,
				"medium": 1.4,
				"large": 1.8
			}
		},
		"blocks": {
			"core/group": {
				"custom": {
					"baseFont": 32
				}
			}
		}
	}
}

出力

body {
	--wp--custom--base-font: 16;
	--wp--custom--line-height--small: 1.2;
	--wp--custom--line-height--medium: 1.4;
	--wp--custom--line-height--large: 1.8;
}
.wp-block-group {
	--wp--custom--base-font: 32;
}

注意: 変数名は各ネストレベルの間に -- を追加し、camelCase フィールドは kebab-case に変換して作成されます。

settings の例

  • 段落ブロックのみにカスタム色を有効化
{
	"version": 3,
	"settings": {
		"color": {
			"custom": false
		},
		"blocks": {
			"core/paragraph": {
				"color": {
					"custom": true
				}
			}
		}
	}
}
  • ボタンブロックの枠の角丸を無効化
{
	"version": 3,
	"settings": {
		"blocks": {
			"core/button": {
				"border": {
					"radius": false
				}
			}
		}
	}
}
  • グループブロックのみに他と異なるパレットを設定
{
	"version": 3,
	"settings": {
		"color": {
			"palette": [
				{
					"slug": "black",
					"color": "#000000",
					"name": "Black"
				},
				{
					"slug": "white",
					"color": "#FFFFFF",
					"name": "White"
				},
				{
					"slug": "red",
					"color": "#FF0000",
					"name": "Red"
				},
				{
					"slug": "green",
					"color": "#00FF00",
					"name": "Green"
				},
				{
					"slug": "blue",
					"color": "#0000FF",
					"name": "Blue"
				}
			]
		},
		"blocks": {
			"core/group": {
				"color": {
					"palette": [
						{
							"slug": "black",
							"color": "#000000",
							"name": "Black"
						},
						{
							"slug": "white",
							"color": "#FFF",
							"name": "White"
						}
					]
				}
			}
		}
	}
}

styles

Gutenberg プラグインは、WordPress 5.8で利用可能なスタイルを拡張しています。このため、他のバージョンの WordPress でも利用でき、コアに移植される前に機能の成熟プロセスを経ます。

次のセクションでは、WordPress 5.8でサポートされるスタイルと、Gutenberg プラグインでサポートされるスタイルを示します。

各ブロックはブロックサポートを介して、どのスタイルプロパティを公開するかを宣言します。サポートの宣言はエディター内でのブロックの UI コントロールを自動的に生成するために使用されます。テーマは theme.json を介して、任意のブロックのために、任意のスタイルプロパティを使用できます。ブロックマークアップ等に関して正しく動作するかどうかの検証は、テーマの責任です。

WordPress

{
	"version": 3,
	"styles": {
		"border": {
			"radius": "value",
			"color": "value",
			"style": "value",
			"width": "value"
		},
		"filter": {
			"duotone": "value"
		},
		"color": {
			"background": "value",
			"gradient": "value",
			"text": "value"
		},
		"spacing": {
			"blockGap": "value",
			"margin": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value",
			},
			"padding": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value"
			}
		},
		"typography": {
			"fontSize": "value",
			"fontStyle": "value",
			"fontWeight": "value",
			"letterSpacing": "value",
			"lineHeight": "value",
			"textDecoration": "value",
			"textTransform": "value"
		},
		"elements": {
			"link": {
				"border": {},
				"color": {},
				"spacing": {},
				"typography": {}
			},
			"h1": {},
			"h2": {},
			"h3": {},
			"h4": {},
			"h5": {},
			"h6": {}
		},
		"blocks": {
			"core/group": {
				"border": {},
				"color": {},
				"spacing": {},
				"typography": {},
				"elements": {
					"link": {},
					"h1": {},
					"h2": {},
					"h3": {},
					"h4": {},
					"h5": {},
					"h6": {}
				}
			},
			"etc": {}
		}
	}
}

Gutenberg

{
	"version": 3,
	"styles": {
		"border": {
			"color": "value",
			"radius": "value",
			"style": "value",
			"width": "value"
		},
		"color": {
			"background": "value",
			"gradient": "value",
			"text": "value"
		},
		"dimensions": {
			"aspectRatio": "value",
			"height": "value"
			"minHeight": "value"
			"width": "value"
		},
		"filter": {
			"duotone": "value"
		},
		"spacing": {
			"blockGap": "value",
			"margin": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value"
			},
			"padding": {
				"top": "value",
				"right": "value",
				"bottom": "value",
				"left": "value"
			}
		},
		"typography": {
			"fontFamily": "value",
			"fontSize": "value",
			"fontStyle": "value",
			"fontWeight": "value",
			"letterSpacing": "value",
			"lineHeight": "value",
			"textColumns": "value",
			"textDecoration": "value",
			"textTransform": "value"
		},
		"elements": {
			"link": {
				"border": {},
				"color": {},
				"spacing": {},
				"typography": {}
			},
			"h1": {},
			"h2": {},
			"h3": {},
			"h4": {},
			"h5": {},
			"h6": {},
			"heading": {},
			"button": {},
			"caption": {}
		},
		"blocks": {
			"core/group": {
				"border": {},
				"color": {},
				"dimensions": {},
				"spacing": {},
				"typography": {},
				"elements": {
					"link": {},
					"h1": {},
					"h2": {},
					"h3": {},
					"h4": {},
					"h5": {},
					"h6": {}
				}
			},
			"etc": {}
		}
	}
}

トップレベルスタイル

トップレベルのスタイルは body セレクタを使用してエンキューされます。

入力

{
	"version": 3,
	"styles": {
		"color": {
			"text": "var(--wp--preset--color--primary)"
		}
	}
}

出力

body {
	color: var( --wp--preset--color--primary );
}

ブロックスタイル

ブロック内のスタイルは、ブロックセレクタを使用してエンキューされます。

デフォルトでは、ブロックセレクタは .wp-block-<blockname-without-namespace> のような名前を基にして生成されます。たとえば、core/group ブロックの .wp-block-group です。このデフォルトの動作をオプトアウトしたいブロックもあります。これには明示的にシステムに対してどのセレクタを使用するか、block.json ファイルの supports セクション内の __experimentalSelector キーで指定します。注意: スタイルエンジンが __experimentalSelector フィールドを利用できるようにするには、このブロックをサーバーサイドで登録する必要があります。

入力

{
	"version": 3,
	"styles": {
		"color": {
			"text": "var(--wp--preset--color--primary)"
		},
		"blocks": {
			"core/paragraph": {
				"color": {
					"text": "var(--wp--preset--color--secondary)"
				}
			},
			"core/group": {
				"color": {
					"text": "var(--wp--preset--color--tertiary)"
				}
			}
		}
	}
}

出力

body {
	color: var( --wp--preset--color--primary );
}
p { /* The core/paragraph opts out from the default behaviour and uses p as a selector. */
	color: var( --wp--preset--color--secondary );
}
.wp-block-group {
	color: var( --wp--preset--color--tertiary );
}

スタイルの参照

ブロックは、ルートレベルのスタイルへの参照を使用して、スタイルを設定できます。この機能は Gutenberg でサポートされています。 ルートの背景色を styles.color.background を使用して登録すると、

"styles": {
		"color": {
			"background": "var(--wp--preset--color--primary)"
		}
	}

ref: "styles.color.background" を使用して、ブロックにスタイルを再利用できます。

{
	"color": {
		"text": { "ref": "styles.color.background" }
	}
}

要素スタイル

トップレベル、ブロックレベルのスタイルに加えて、両方の場所で使用できる要素のコンセプトがあります。

Gutenberg によるサポート

  • button: wp-element-button CSS クラスにマップ。後方互換性のため、wp-block-button__link にもマップ
  • caption: .wp-element-caption, .wp-block-audio figcaption, .wp-block-embed figcaption, .wp-block-gallery figcaption, .wp-block-image figcaption, .wp-block-table figcaption, .wp-block-video figcaption CSS クラスにマップ
  • heading: すべての見出し、h1 から h6 CSS セレクタにマップ

WordPress によるサポート

  • h1: h1 CSS セレクタにマップ
  • h2: h2 CSS セレクタにマップ
  • h3: h3 CSS セレクタにマップ
  • h4: h4 CSS セレクタにマップ
  • h5: h5 CSS セレクタにマップ
  • h6: h6 CSS セレクタにマップ
  • link: a CSS セレクタにマップ

トップレベルにあれば、要素セレクタが使用されます。ブロック内にあれば、使用されるセレクタは、対応するブロックに追加された形の要素セレクタになります。

入力

{
	"version": 3,
	"styles": {
		"typography": {
			"fontSize": "var(--wp--preset--font-size--normal)"
		},
		"elements": {
			"h1": {
				"typography": {
					"fontSize": "var(--wp--preset--font-size--huge)"
				}
			},
			"h2": {
				"typography": {
					"fontSize": "var(--wp--preset--font-size--big)"
				}
			},
			"h3": {
				"typography": {
					"fontSize": "var(--wp--preset--font-size--medium)"
				}
			}
		},
		"blocks": {
			"core/group": {
				"elements": {
					"h2": {
						"typography": {
							"fontSize": "var(--wp--preset--font-size--small)"
						}
					},
					"h3": {
						"typography": {
							"fontSize": "var(--wp--preset--font-size--smaller)"
						}
					}
				}
			}
		}
	}
}

出力

body {
	font-size: var( --wp--preset--font-size--normal );
}
h1 {
	font-size: var( --wp--preset--font-size--huge );
}
h2 {
	font-size: var( --wp--preset--font-size--big );
}
h3 {
	font-size: var( --wp--preset--font-size--medium );
}
.wp-block-group h2 {
	font-size: var( --wp--preset--font-size--small );
}
.wp-block-group h3 {
	font-size: var( --wp--preset--font-size--smaller );
}
要素疑似セレクタ

Gutenberg は疑似セレクタ :hover、:focus、:focus-visible、:visited、:active、:link、:any-link をサポートします。

"elements": {
		"link": {
			"color": {
				"text": "green"
			},
			":hover": {
				"color": {
					"text": "hotpink"
				}
			}
		}
	}

Variations

ブロックは、block.json の仕様で定義されているように「スタイルのバリエーション」を持つことができます。テーマ作成者は、theme.json ファイルを使用して、既存のスタイルバリエーションのスタイル属性を定義できます。登録されていないスタイルバリエーションのスタイルは、無視されます。

ここでバリエーションは「ブロックの概念」であり、ブロックと関連してのみ存在することに注意してください。theme.json の仕様は、ブロックレベルでのみ バリエーションを許可し、トップレベルでは許可しないことでこの区別を大切にしています。また、ブロックの block.json ファイルで定義されたバリエーションのみを「登録」されたとものとしてみなすことも強調しておきます。現在 register_block_style やクライアントで追加されたスタイルバリエーションは無視されます。詳しくは この issue を参照してください。

例えば、core/quote ブロックの既存の plain バリエーションにスタイルを当てる方法です。

{
	"version": 3,
	"styles": {
		"blocks": {
			"core/quote": {
				"variations": {
					"plain": {
						"color": {
							"background": "red"
						}
					}
				}
			}
		}
	}
}

結果の CSS 出力は以下です。

.wp-block-quote.is-style-plain {
	background-color: red;
}

It is also possible for multiple block types to share the same variation styles. There are two recommended ways to define such shared styles:

  1. theme.json partial files
  2. programmatically, using register_block_style
Variation Theme.json Partials

Like theme style variation partials, those for block style variations reside within a theme’s /styles directory. However, they are differentiated from theme style variations by the introduction of a top-level property called blockTypes. The blockTypes property is an array of block types for which the block style variation has been registered.

Additionally, a slug property is available to provide consistency between the different sources that may define block style variations and to decouple the slug from the translatable title property.

The following is an example of a theme.json partial that defines styles for the “Variation A” block style for the Group, Columns, and Media & Text block types:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Variation A",
	"slug": "variation-a",
	"blockTypes": [ "core/group", "core/columns", "core/media-text" ],
	"styles": {
		"color": {
			"background": "#eed8d3",
			"text": "#201819"
		},
		"elements": {
			"heading": {
				"color": {
					"text": "#201819"
				}
			}
		},
		"blocks": {
			"core/group": {
				"color": {
					"background": "#825f58",
					"text": "#eed8d3"
				},
				"elements": {
					"heading": {
						"color": {
							"text": "#eed8d3"
						}
					}
				}
			}
		}
	}
}
Programmatically Registering Variation Styles

As an alternative to theme.json partials, you can register variation styles at the same time as registering the variation itself through register_block_style. This is done by registering the block style for an array of block types while also passing a “style object” within the style_data option.

The example below registers a “Green” variation for the Group and Columns blocks. Note that the style object passed via style_data follows the same shape as the styles property of a theme.json partial.

register_block_style(
    array( 'core/group', 'core/columns' ),
    array(
        'name'       => 'green',
        'label'      => __( 'Green' ),
        'style_data' => array(
            'color'    => array(
                'background' => '#4f6f52',
                'text'       => '#d2e3c8',
            ),
            'blocks'   => array(
                'core/group' => array(
                    'color' => array(
                        'background' => '#739072',
                        'text'       => '#e3eedd',
                    ),
                ),
            ),
            'elements' => array(
                'link'   => array(
                    'color'  => array(
                        'text' => '#ead196',
                    ),
                    ':hover' => array(
                        'color' => array(
                            'text' => '#ebd9b4',
                        ),
                    ),
                ),
            ),
        ),
    )
);

customTemplates

WordPress Version 5.9 以降でサポートされます。

このフィールド内にテーマは、templates フォルダー内にあるカスタムテンプレートをリストできます。たとえば、カスタムテンプレート my-custom-template.html に対して、theme.json はどの投稿タイプが使用でき、ユーザーにどのようなタイトルを表示するか宣言できます。

  • name: 必須
  • title: 必須。翻訳可能
  • postTypes: オプション。デフォルトでは page のみに適用
{
    "version": 3,
	"customTemplates": [
		{
			"name": "my-custom-template",
			"title": "The template title",
			"postTypes": [
				"page",
				"post",
				"my-cpt"
			]
		}
	]
}

templateParts

WordPress Version 5.9 以降でサポートされます。

このフィールド内にテーマは、parts フォルダーにあるテンプレートパーツをリストできます。たとえば、テンプレートパーツ my-template-part.html に対して、theme.json は、テンプレートパーツのエンティティのための area タームを宣言できます。エンティティはエディター内で、対応するブロックバリエーション (ヘッダーブロック、フッターブロックなど) をレンダリングする責任があります。json 内で area タームを定義するとテンプレートパーツエンティティのすべての使用において設定を永続化できます。これは、ブロック属性が1つのブロックのみに影響するのとは対照的です。ブロック属性としての area 定義は推奨されません。これは「表舞台の裏側」で使用され、プレースホルダーフローとエンティティ作成のギャップの橋渡しを支援します。

現在、ブロックバリエーションは、area タームの header と footer の値に対して存在し、その他の値や json で定義されていないテンプレートパーツは、一般のテンプレートパーツブロックがデフォルトとなります。バリエーションはエディターのインターフェース内で特定のアイコンで示され、デフォルトでラッパーの対応するセマンティック HTML 要素となり (これも、テンプレートパーツブロック上の tagName 属性セットで上書きできます)、将来のエディターの改良でカスタムフローの実現のためテンプレートパーツをコンテキスト化します。

  • name: 必須
  • title: オプション、翻訳可能
  • area: オプション。デフォルトでは uncategorized に設定され、ブロックバリエーションをトリガーしない
{
    "version": 3,
	"templateParts": [
		{
			"name": "my-template-part",
			"title": "Header",
			"area": "header"
		}
	]
}

patterns

WordPress Version 6.0 からサポートされます。

このフィールドには、パターンディレクトリから登録するパターンをリストアップできます。patterns フィールドはパターンディレクトリに登録されているパターンの slugs の配列です。パターンのスラッグは、パターンディレクトリの単一のパターンビューで url から抽出できます。例えば、URL https://wordpress.org/patterns/pattern/partner-logos でのスラッグは partner-logos です。

{
	"version": 3,
	"patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
}

theme.json を使用した開発

開発中に theme.json の設定やプロパティ、あるいは、どの WordPress がどの設定をサポートするかを覚えておくことは困難です。そのため、theme.json に提供された JSON スキーマの使用は有用です。

多くのコードエディターが JSON スキーマをサポートし、ツールチップ、オートコンプリート、スキーマ検証などのヘルプをエディター上で支援を提供します。

各 WordPress バージョンの theme.json スキーマは、https://schemas.wp.org/wp/{{version}}/theme.json から利用できます。例えば、WordPress 5.8用のスキーマは https://schemas.wp.org/wp/5.8/theme.json にあります。テーマのユーザーが利用可能な機能のみを使用するには、テーマがサポートする最も古いバージョンを使用してください。

Gutenberg プラグインからのすべての最新の変更を含む最新のスキーマは、https://schemas.wp.org/trunk/theme.json にあります。

JSON スキーマのサポートについては、使用するエディターのドキュメントを確認してください。例えば、Visual Studio Code では、"$schema"：「https://schemas.wp.org/wp/x.x/theme.json" を theme.json ファイルのトップレベルのプロパティに追加する必要があります。他のエディターでは設定が異なるかもしれません。

スキーマを使用した検証の例

FAQ よくある質問と答え

CSS カスタムプロパティの命名体系

システムが作成する CSS カスタムプロパティの命名体系に気づいたかもしれません。ダブルハイフン -- が異なる「コンセプト」を分離しています。以下に例を見ます。

プリセット たとえば --wp--preset--color--black は次のように分割できます。

  • --wp: CSS 変数の名前空間の接頭辞。
  • preset: プリセットに属する CSS 変数であることを示す。
  • color: 変数がどのプリセットカテゴリーに属するかを示す。color、font-size、gradients を指定可。
  • black: 特定のプリセット値の slug 。

Custom プロパティ --wp--custom--line-height--body は次のように分割できます。

  • --wp: CSS 変数の名前空間の接頭辞。
  • custom: テーマに作成された「自由形式」の CSS 変数であることを示す。
  • line-height--body: 「カスタム」オブジェクトキーを文字列に変換した結果。

セパレータとしての -- には2つの機能があります。

  • 人間の理解を助ける可読性。「カテゴリー」を分ける、BEM 命名規約と同じと考えられます。
  • 機械の理解を助けるパース容易性 (Parseability)。定義された構造を使用することで、機械もプロパティ --wp--preset--color--black の意味を理解でき、これがスラッグ「black」のカラープリセットに紐付いた値と分かり、ユーザーが更なる操作を行う余地を与えます。

なぜ、セパレータとして、– (2つのハイフン) を使用するのですか ?

他のセパレータ、たとえば - (単一のハイフン)を使うこともできました。

しかし、これは問題で、例えば --wp-custom-line-height-template-header をどのように変換してオブジェクトに戻すのか伝えることは不可能です。変数名に - を使わないよう作者に強制するしかありません。

カテゴリーセパレータとして -- を予約し、作者は単語の境界に - を使えることで、命名も --wp--custom--line-height--template-header と、クリアになります。

「custom」下の設定は、どのように新しい CSS カスタムプロパティを作成しますか ?

「カスタム」キー下の設定から CSS 変数を作成するアルゴリズムは次のように動作します。

これは明快さのためですが、--wp--custom--line-height--body のような変数名をパースして theme.json 内のオブジェクト形式に戻す仕組みも必要なためです。プリセットにも同じセパレータを使用します。

例:

入力

{
	"version": 3,
	"settings": {
		"custom": {
			"lineHeight": {
				"body": 1.7
			},
			"font-primary": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif"
		}
	}
}

出力

body {
	--wp--custom--line-height--body: 1.7;
	--wp--custom--font-primary: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif";
}

このプロセスに対する注意:

  • camelCased キーはその kebab-case フォームに変換し、CSS プロパティ命名体系に従います。例: lineHeight は line-height に変換されます。
  • 異なる深さレベルのキーは -- で分割されます。line-height と body が -- で分かれている理由です。
  • You shouldn’t use -- in the names of the keys within the custom オブジェクト内のキー名で -- を使用しないでください。例: 次のような命名は止めてください。
{
	"version": 3,
	"settings": {
		"custom": {
			"line--height": { // DO NOT DO THIS
				"body": 1.7
			}
		}
	}
}

グローバルスタイルシート

WordPress 5.8では、WordPress が定義するプリセットの一部 (フォントサイズ、色、グラデーション) の CSS が、ほとんどのテーマで2回、ブロックライブラリのスタイルシートとグローバルスタイルシートで読み込まれていました。さらに、両方の CSS にわずかな違いがありました。

WordPress 5.9 リリースでは、プリセットの CSS はグローバルスタイルシートに統合され、すべてのテーマで読み込まれるようになりました。各プリセットの値は、次のように、単一のCSSカスタムプロパティとクラスを生成します。

/* CSS Custom Properties for the preset values */
body {
  --wp--preset--<PRESET_TYPE>--<PRESET_SLUG>: <DEFAULT_VALUE>;
  --wp--preset--color--pale-pink: #f78da7;
  --wp--preset--font-size--large: 36px;
  /* etc. */
}

/* CSS classes for the preset values */
.has-<PRESET_SLUG>-<PRESET_TYPE> { ... }
.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; }
.has-large-font-size { font-size: var(--wp--preset--font-size--large) !important; }

テーマがデフォルト値をオーバーライドするには、theme.json を使用し、同じスラッグを提供します。theme.json を使用しないテーマでデフォルト値をオーバーライドするには、対応する CSS カスタムプロパティを設定する CSS をエンキューします。

例 (デフォルトの large フォントサイズに新しい値を設定する):

body {
 --wp--preset--font-size--large: <NEW_VALUE>;
}

ユーザーから提供されるリンクカラーの詳細度

v1 では、ユーザーが特定のブロックのリンク色を選択すると、そのブロックに .wp-element-<ID> という形でクラスをアタッチし、次のスタイルをキューに入れました。

WordPress 5.8では、ユーザーが特定のブロックのリンク色を選択すると、そのブロックにクラス .wp-element-<ID> をアタッチし、次のスタイルをエンキューしていました。

.wp-element-<ID> a { color: <USER_COLOR_VALUE> !important; }

これは常にユーザーの好みを維持しますが、詳細度が強すぎて、リンクとみなせない HTML 要素を正当に使用している一部のブロックと衝突していました。この問題に対処するため、WordPress 5.9 リリースでは !important を削除し、対応するブロックを更新して、ユーザーのリンク色よりも高い詳細度で、a 要素をスタイルするようにしました。現在の様子です。

.wp-element-<ID> a { color: <USER_COLOR_VALUE>; }

この変更により、ユーザーの選択を常に尊重し、ユーザーが提供したリンク色 (詳細度011) が上書きされないようにすることは、ブロック作成者とテーマ作成者の責任になりました。

blockGap とは何か、どう使うのか ?

グループ、カラム、ボタン、ソーシャルアイコンなどのインナーブロックを含むブロックでは、 blockGap は、インナーブロック間の間隔を制御します。blockGap が機能するには、ブロックも layout ブロックサポートをオプトインする必要があります。これにより「ブロックスペース」コントロールで調整可能なレイアウトスタイルが提供されます。ブロックのレイアウトによって、 blockGap 値は垂直方向のマージンか gap 値として出力されます。エディター内で blockGap値のコントロールは「ブロックスペース」と呼ばれ、「寸法」パネル内にあります。

{
	"version": 3,
	"settings": {
		"spacing": {
			"blockGap": true,
		}
	},
	"styles": {
		"spacing": {
			"blockGap": "1.5rem"
		}
	}
}

blockGap の設定は boolean か null 値で、デフォルトでは null です。この設定により、スタイル出力をより細かく制御できます。theme.json ファイル内の settings.spacing.blockGap 設定は、以下の値を受け取ります。

  • true: エディター UI に_ブロックスペース_コントロールを表示し、blockGap スタイルを出力することを許可します。
  • false: エディター UI で_ブロックスペース_コントロールを表示せず、theme.json に保存された blockGap スタイルをそのままレンダーします。この結果、テーマは、エディタ内でのユーザーの変更を禁止して、blockGap 値を使用できます。
  • null (デフォルト): ブロック間隔コントロールの表示と、 blockGap スタイルの出力を停止します。

ルートの styles.spacing.blockGap スタイルに定義された値は、CSSプロパティ --wp--style--block-gap として出力されます。

なぜ、ブラウザのスタイルの更新に長い時間がかかるのか ?

theme.json を使用して開発を行っていると、変更内容がブラウザに表示されるまでに30秒以上かかることに気がつくかもしれません。これは、theme.json がキャッシュされているためです。このキャッシュの問題を解決するには、wp-config.php の WP_DEBUG または SCRIPT_DEBUG を ‘true’ に設定します。これにより、WordPress はキャッシュをスキップし、常に新しいデータを使用します。

原文

公開日

最終更新

WordPress.org

日本語

The WordPress® trademark is the intellectual property of the WordPress Foundation.

Code is Poetry.
s
検索
c
新規投稿を作成する
r
返信
e
編集
t
ページのトップへ
j
go to the next post or comment
k
go to the previous post or comment
o
コメントの表示を切替
esc
投稿やコメントの編集をキャンセル