グローバル設定とスタイル (theme.json)
Topics
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
を作成することでコアのデフォルトを上書きできます。ユーザーもまた、開発中のユーザーインターフェース、サイトエディターを介して、テーマやコアの設定を上書きできます。
任意の登録ブロックに対して settings も styles もサブセクションを含むことができます。一般的なルールとしてサブセクションの名前はブロック名で、これは「ブロックセレクタ」と呼ばれます。たとえば段落ブロック (名前は core/paragraph
)は、settings 内ではキー (あるいは「ブロックセレクタ」) core/paragraph
として処理されます。
{
"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,
"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
を介したものよりも、詳細な制御を行えます。トップレベルで宣言されたブロック設定は、個別に上書きしない限り、すべてのブロックに影響します。継承のコンセプトを導入し、すべてのブロックを一度に構成できます。
注意: ただし、すべての設定がすべてのブロックに関連するわけではありません。settings セクションはテーマに対してオプトイン、オプトアウトの仕組みを提供しますが、関連する機能のサポートの追加はブロックの責任です。たとえばブロックが dropCap
機能を実装しなければ、テーマは theme.json
を介して有効化できません。
UI コントロールへのオプトイン
特別な設定プロパティとして appearanceTools
があります。ブール値で、デフォルト値は false です。テーマはこの設定を使用して、以下を有効化できます。
- background: backgroundImage, backgroundSize
- border: color, radius, style, width
- color: link
- dimensions: aspectRatio, minHeight
- 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_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 を設定 |
プリセット
プリセットは 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",
"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": {}
}
}
}
トップレベルスタイル
トップレベルのスタイルは 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 );
}
要素疑似セレクタ
疑似セレクタ :hover
、:focus
、:visited
、:active
、:link
、:any-link
を Gutenberg はサポートします。
"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;
}
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 thecustom
オブジェクト内のキー名で--
を使用しないでください。例: 次のような命名は止めてください。
{
"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 はキャッシュをスキップし、常に新しいデータを使用します。
最終更新日: