テーマ - グローバル設定とスタイル（theme.json）（Global Settings & Styles (theme.json)）

Rationale
Specification
Developing with theme.json
Frequently Asked Questions

Rationale

ブロックエディタAPIは異なる速度で進化しており、特にテーマに影響を与える領域では成長痛が見られます。これに関する例としては、エディタをプログラム的に制御する能力や、ユーザー、テーマ、コアスタイルの好みを容易にするブロックスタイルシステムがあります。

これは、スタイルに関連するさまざまなAPIを単一のポイントに統合するための現在の取り組みを説明しています。これは、テーマディレクトリのルート内に配置されるべきtheme.jsonファイルです。

Settings for the block editor

テーマサポートフラグや代替手段の増加の代わりに、theme.jsonファイルはブロックエディタの設定を定義するための標準的な方法を提供します。これらの設定には、次のようなものが含まれます：

ユーザーに対してどのカスタマイズオプションを利用可能または非表示にするか。
ユーザーに利用可能なデフォルトの色、フォントサイズなど。
エディタのデフォルトレイアウト（幅と利用可能な配置）を定義します。

Settings can be controlled per block

より細かい制御のために、これらの設定はtheme.json内のブロックレベルでも機能します。

達成できる例は次のとおりです：

特定のプリセットをブロック（例：テーブル）に使用し、他のブロックには共通のものを使用する。
見出しブロック以外のすべてのブロックにフォントサイズのUIコントロールを有効にする。
その他。

Styles are managed


いくつかの利点は次のとおりです：  
- エンキューされるCSSの量を減らす。 
- 特異性の戦争を防ぐ。  
 <a name="css-custom-properties-presets-custom"></a>
### CSS Custom Properties: presets &amp; custom
サイト全体で変更できる共有値を持つことが利益となるスタイリングの領域があります。  
このニーズに対処するために、私たちはいくつかの場所でCSSカスタムプロパティ、別名CSS変数を使った実験を始めました：  
- **プリセット**：テーマによって宣言された[カラーパレット](a79eb3e4eb9df7a2.md#block-color-palettes)、[フォントサイズ](a79eb3e4eb9df7a2.md#block-font-sizes)、または[グラデーション](a79eb3e4eb9df7a2.md#block-gradient-presets)はCSSカスタムプロパティに変換され、フロントエンドとエディタの両方にエンキューされます。
``````bash
{
   "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;
}

Specification

この仕様は、この形式を使用する3つの異なる起源（コア、テーマ、ユーザー）に対して同じです。テーマは、theme.jsonというファイルを作成することでコアのデフォルトをオーバーライドできます。ユーザーは、サイトエディタを介して、作業中のユーザーインターフェースを介してテーマやコアの設定をオーバーライドすることもできます。

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

Version

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

破壊的な変更が必要な場合に新しいバージョンが導入されます。これにより、テーマの著者は破壊的な変更にオプトインするタイミングを選択し、theme.jsonファイルを新しいフォーマットに移行できます。

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

最新バージョンへの更新の詳細については、新しいバージョンへの移行手順を参照してください。

Settings

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

以下のタブは、WordPress 5.8でサポートされている設定とGutenbergプラグインでサポートされている設定を示しています。

設定セクションは次の構造を持っています：

{
   "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": {}
   }
   }
}

{
   "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,
   "minHeight": 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,
   "textTransform": true
   },
   "blocks": {
   "core/paragraph": {
   "border": {},
   "color": {},
   "custom": {},
   "layout": {},
   "spacing": {},
   "typography": {}
   },
   "core/heading": {},
   "etc": {}
   }
   }
}

各ブロックは、add_theme_supportを介して存在するこれらの設定のいずれかを個別に構成でき、すべてのブロックを一度に構成する方法を提供します。トップレベルで宣言された設定は、特定のブロックがそれを上書きしない限り、すべてのブロックに影響します。これは、継承を提供し、すべてのブロックを一度に構成する方法です。

ただし、すべての設定がすべてのブロックに関連するわけではないことに注意してください。設定セクションは、テーマに対してオプトイン/オプトアウトメカニズムを提供しますが、ブロックが関連する機能のサポートを追加する責任があります。たとえば、ブロックがdropCap機能を実装していない場合、テーマはtheme.jsonを介してそのブロックに対してそれを有効にすることはできません。

Opt-in into UI controls

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

背景：backgroundImage、backgroundSize
ボーダー：color、radius、style、width
色：link
寸法：aspectRatio、minHeight
位置：sticky
スペーシング：blockGap、margin、padding
タイポグラフィ：lineHeight

Backward compatibility with add_theme_support

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

add_theme_support	theme.json設定
`custom-line-height`	`typography.lineHeight`を`true`に設定します。
`custom-spacing`	`spacing.padding`を`true`に設定します。
`custom-units`	`spacing.units`を介して単位のリストを提供します。
`disable-custom-colors`	`color.custom`を`false`に設定します。
`disable-custom-font-sizes`	`typography.customFontSize`を`false`に設定します。
`disable-custom-gradients`	`color.customGradient`を`false`に設定します。
`editor-color-palette`	`color.palette`を介して色のリストを提供します。
`editor-font-sizes`	`typography.fontSizes`を介してフォントサイズのリストを提供します。
`editor-gradient-presets`	`color.gradients`を介してグラデーションのリストを提供します。
`editor-spacing-sizes`	`spacing.spacingSizes`を介してスペーシングサイズのリストを提供します。
`appearance-tools`	`appearanceTools`を`true`に設定します。
`border`	`border: color, radius, style, width`を`true`に設定します。
`link-color`	`color.link`を`true`に設定します。

Presets

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

次のプリセットはtheme.jsonを介して定義できます：

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

クラスとカスタムプロパティの命名スキーマは次のとおりです：

カスタムプロパティ：--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を追加します。ユーザースタイルはテーマスタイルよりも優先されるべきです。

Custom

プリセットのためにCSSカスタムプロパティを作成することに加えて、theme.jsonはテーマが独自のプロパティを作成することも許可します。これにより、別々にエンキューする必要がなくなります。customフィールド内で宣言された値は、次の命名スキーマに従ってCSSカスタムプロパティに変換されます：--wp--custom--<variable-name>。

たとえば：

{
   "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 examples

段落ブロックのみにカスタムカラーを有効にする：

{
   "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を介して任意のブロックの任意のスタイルプロパティを使用できます。これは、テーマがブロックのマークアップに従って正しく機能することを確認する責任があります。

{
   "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": {}
   }
   }
}

{
   "version": 3,
   "styles": {
   "border": {
   "color": "value",
   "radius": "value",
   "style": "value",
   "width": "value"
   },
   "color": {
   "background": "value",
   "gradient": "value",
   "text": "value"
   },
   "dimensions": {
   "aspectRatio": "value",
   "minHeight": "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": {}
   }
   }
}

Top-level styles

トップレベルで見つかったスタイルは、bodyセレクタを使用してエンキューされます。

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

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

Block styles

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

デフォルトでは、ブロックセレクタはその名前に基づいて生成されます（例：.wp-block-<blockname-without-namespace>）。たとえば、.wp-block-groupはcore/groupブロックのためのものです。このデフォルトの動作からオプトアウトしたいブロックもあります。これらは、experimentalSelectorキーを介してsupportsファイルのblock.jsonセクション内で使用するセレクタを明示的に指定することによって行うことができます。ブロックは、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 );
}

Referencing a style

ブロックは、ルートレベルのスタイルへの参照を使用してスタイルを適用できます。この機能はGutenbergによってサポートされています。

ルートの背景色をstyles.color.backgroundを使用して登録した場合：

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

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

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

Element styles

トップレベルおよびブロックレベルのスタイルに加えて、両方の場所で使用できる要素の概念があります。それらは閉じたセットです：

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 to 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 );
}

Element pseudo selectors

擬似セレクタ:hover、:focus、:visited、:active、:link、:any-linkはGutenbergによってサポートされています。

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

Variations

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

バリエーションは「ブロックの概念」であり、ブロックにバインドされてのみ存在します。theme.json仕様は、その区別を尊重し、トップレベルではなくブロックレベルでのみvariationsを許可します。また、ブロックのblock.jsonファイルで定義されたバリエーションのみが「登録された」と見なされることを強調する価値があります。register_block_styleまたはクライアントで追加されたスタイルバリエーションは無視されます。詳細については、この問題を参照してください。

たとえば、core/quoteブロックの既存のplainバリエーションにスタイルを提供する方法は次のとおりです：

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

結果として得られるCSS出力は次のとおりです：

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

customTemplates

WordPress 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 5.9からサポートされています。

このフィールド内で、テーマはpartsフォルダー内に存在するテンプレートパーツをリストできます。たとえば、my-template-part.htmlというテンプレートパートの場合、theme.jsonは、エディタ内で対応するブロックバリエーション（ヘッダーブロック、フッターブロックなど）をレンダリングする責任を持つテンプレートパートエンティティのエリア用語を宣言できます。このエリア用語をjsonで定義することで、そのテンプレートパートエンティティのすべての使用にわたって設定が持続することができます。これは、1つのブロックにのみ影響を与えるブロック属性とは対照的です。エリアをブロック属性として定義することは推奨されません。これは、プレースホルダーフローとエンティティ作成のギャップを埋めるのを助けるためにのみ使用されます。

現在、エリア用語の「ヘッダー」と「フッター」の値に対してブロックバリエーションが存在し、jsonで定義されていない他の値やテンプレートパーツは一般的なテンプレートパートブロックにデフォルトされます。バリエーションは、エディタのインターフェース内で特定のアイコンによって示され、ラッパーの対応するセマンティックHTML要素にデフォルトされます（これは、テンプレートパートブロックに設定されたtagName属性によって上書きされることもあります）、そしてテンプレートパートを文脈化し、将来のエディタの改善においてよりカスタムフローを可能にします。

name：必須。
title：オプション、翻訳可能。
area：オプション、デフォルトではuncategorizedに設定され、ブロックバリエーションをトリガーしません。

{
   "version": 3,
   "templateParts": [
   {
   "name": "my-template-part",
   "title": "Header",
   "area": "header"
   }
   ]
}

patterns

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

このフィールド内で、テーマはパターンダイレクトリから登録するパターンをリストできます。patternsフィールドは、パターンダイレクトリからのパターンslugsの配列です。パターンスラグは、パターンダイレクトリの単一パターンビューでurlによって抽出できます。たとえば、このURLhttps://wordpress.org/patterns/pattern/partner-logos` the slug ispartner-logos`。

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

Developing with theme.json

テーマ.jsonの設定やプロパティ、どのバージョンのWordPressがどの設定をサポートしているかを開発中に覚えておくのは難しい場合があるため、提供されたJSONスキーマを使用することが役立ちます。

多くのコードエディタはJSONスキーマをサポートしており、ツールチップ、オートコンプリート、またはスキーマ検証などのヘルプをエディタ内で提供できます。

各WordPressバージョンのtheme.jsonスキーマはhttps://schemas.wp.org/wp/{{version}}/theme.json`. For example a schema for WordPress 5.8 is available athttps://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ファイルのトップレベルプロパティとして追加する必要がありますが、他のエディタは異なる設定が必要な場合があります。

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

Frequently Asked Questions

The naming schema of CSS Custom Properties

システムが作成するCSSカスタムプロパティの命名スキーマ、特に異なる「概念」を区切るために二重ハイフン--を使用することに気付いたかもしれません。以下の例を見てみましょう。

プリセットは--wp--preset--color--blackのように、次のように分割できます：

--wp：CSS変数の名前空間をプレフィックスします。
preset：プリセットに属するCSS変数であることを示します。
color：変数が属するプリセットカテゴリを示します。color、font-size、gradientsのいずれかです。
black：特定のプリセット値のslugです。

カスタムプロパティは--wp--custom--line-height--bodyのように、次のように分割できます：

--wp：CSS変数の名前空間をプレフィックスします。
custom：「自由形式」のCSS変数であることを示します。
line-height--body：カスタムオブジェクトキーを文字列に変換した結果です。


- 読みやすさ、人間の理解のため。BEM命名スキーマに似ていると考えられ、カテゴリを区切ります。 
- 機械の理解のための解析可能性。定義された構造を使用することで、機械はプロパティ`````--wp--preset--color--black`````の意味を理解できます。これは、スラグが「black」の色プリセットにバウンドされた値であることを示し、これによりそれらを使用してさらに多くのことを行う余地が生まれます。  
 <a name="why-using-as-a-separator"></a>
### Why using — as a separator?
他の区切り文字、たとえば単一の`````-`````を使用することもできました。  
しかし、それは問題がありました。`````--wp-custom-line-height-template-header`````をオブジェクトに戻す方法を判断することが不可能になり、テーマの著者が`````-`````を変数名に使用しないように強制しなければなりませんでした。  
`````--`````をカテゴリ区切りとして予約し、テーマの著者が`````-`````を単語の境界に使用できるようにすることで、命名が明確になります：`````--wp--custom--line-height--template-header`````。  
 <a name="how-settings-under-custom-create-new-css-custom-properties"></a>
### How settings under “custom” create new CSS Custom Properties
「カスタム」キーの下の設定からCSS変数を作成するアルゴリズムは次のように機能します：  
これは明確さのためですが、変数名`````--wp--custom--line-height--body`````をtheme.jsonのオブジェクト形式に解析するメカニズムを持ちたいからでもあります。プリセットに対しても同じ分離を使用します。  
たとえば：  
``````bash
{
   "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キーは、CSSプロパティ命名スキーマに従ってkebab-case形式に変換されます。例：lineHeightはline-heightに変換されます。
異なる深さのレベルのキーは--で区切られます。これがline-heightとbodyが--で区切られる理由です。
--をcustomオブジェクト内のキーの名前に使用しないでください。例、これを行わないでください：

{
   "version": 3,
   "settings": {
   "custom": {
   "line--height": { // DO NOT DO THIS
   "body": 1.7
   }
   }
   }
}

Global Stylesheet

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をエンキューすることで、デフォルト値をオーバーライドできます。


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

Specificity for link colors provided by the user

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）が上書きされないようにする責任があります。

What is blockGap and how can I use it?

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

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

blockGapの設定はブール値またはnull値であり、デフォルトではnullです。これにより、スタイル出力に対する追加の制御レベルが提供されます。settings.spacing.blockGap設定はtheme.jsonファイルで次の値を受け入れます：

true：エディタUIでブロックスペーシングコントロールを表示することにオプトインし、blockGapスタイルを出力します。
false：エディタUIでブロックスペーシングコントロールを表示しないことにオプトアウトし、blockGapスタイルがtheme.jsonに保存されている場合でもレンダリングされます。これにより、テーマはblockGap値を使用できますが、ユーザーがエディタ内で変更を加えることはできません。
null（デフォルト）：ブロックスペーシングコントロールを表示しないことにオプトアウトし、blockGapスタイルの出力を防ぎます。

ルートstyles.spacing.blockGapスタイルに対して定義された値もCSSプロパティとして出力され、--wp--style--block-gapという名前が付けられます。

Why does it take so long to update the styles in the browser?

theme.jsonを使用して積極的に開発しているとき、変更がブラウザに表示されるまでに30秒以上かかることに気付くかもしれません。これは、theme.jsonがキャッシュされているためです。このキャッシュの問題を解決するには、WP_DEBUGまたはSCRIPT_DEBUGを「true」に設定します。これにより、WordPressはキャッシュをスキップし、常に新しいデータを使用するようになります。