グローバル設定とスタイル (theme.json)
WordPress 5.8ではエディターを構成する新しいメカニズムが搭載されました。きめ細かな制御を可能にし、将来の WordPress リリースにおけるスタイル管理の最初のステップとなる theme.json ファイルです。その後、WordPress 5.9のリリースに伴い theme.json も v2へと進化しました。このページでは、theme.json ファイルのフォーマットについて説明します。
- 論拠
- ブロックエディターのための設定
- 設定をブロックごとに制御できる
- スタイルは管理できる
- CSS カスタムプロパティ: プリセット & カスタム
- 仕様
- version
- settings
- add_theme_support との後方互換性
- プリセット
- カスタム
- 例
- styles
- トップレベル
- ブロックレベル
- 要素
- customTemplates
- templateParts
- FAQ
- CSS カスタムプロパティの命名体系
- なぜ、セパレータとして、「–」を使用するのか ?
- 「custom」下の設定は、どのように新しい CSS カスタムプロパティとなるのか ?
論拠
ブロックエディター API はさまざまな速度で進化しているため、苦痛に感じられる部分が大きくなってきました。これは特にテーマに影響する部分で顕著です。たとえば、エディターのプログラム的な制御や、ユーザー、テーマ、コアスタイルの好みを取りまとめるブロックスタイルシステム などです。
この文書では現在行われている、スタイルに関連するさまざまな API を一箇所に集める努力について、すなわち、テーマディレクトリのルートに配置する theme.json ファイルについて説明します。
ブロックエディターの設定
ブロックエディターの設定を定義する際、ねずみ算式に増えるテーマサポートフラグや代替方式の代わりに theme.json ファイルは正規の方法を提供します。例えば以下の設定が可能です。
- ユーザーが利用可能なカスタマイズオプション。隠すカスタマイズオプション。
- ユーザーが利用可能なデフォルトの色、フォントサイズ、等々
- エディターのデフォルトレイアウトの定義。幅、利用可能な配置
設定をブロックごとに制御できる
より詳細のため、これらの設定は theme.json 内のブロックレベルでも動作します。
達成できることの例:
- あるブロック(例: テーブル)に対して特定のプリセットを使用するが、残りのブロックでは一般的なものを使用する。
- サポートするすべてのブロックでフォントサイズ UI コントロールを有効化するが、見出しブロックは除く。
- など。
スタイルを管理できる
theme.json ファイルを使用して、構造化された形でスタイルプロパティを設定することで、ブロックエディターは異なるソース (ユーザー、テーマ、コア) から来る CSS を「管理」できます。たとえば、テーマとユーザーが段落にフォントサイズを設定しても、ユーザーのスタイルのみをエンキューし、テーマから来たスタイルをエンキューしない等。
この方法の利点:
- エンキューされる CSS の量を減らす。
- 「CSS 詳細度の戦い」を抑止する。
CSS カスタムプロパティ: プリセットとカスタム
スタイリングの領域には、サイト内で一度に変更できる共有の値があると便利な場合があります。
このニーズを満たすためいくつかの場所で、「CSS 変数」とも呼ばれる、CSS カスタムプロパティの実験を始めました。
入力
{
"version": 2,
"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": 2,
"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": 2,
"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 ファイルのフォーマットを表します。現在のバージョンは v2 で、WordPress 5.9 で導入されました。現行の Gutenberg プラグインでも動作します。
過去に v1 を使っていた場合、v1 ファイルの version を v2 に更新する必要はありません。実行時に v2 に 移行 されます。
settings
Gutenberg プラグインは、WordPress 5.8で利用可能な設定を拡張しています。このため、他のバージョンの WordPress でも利用でき、コアに移植される前に機能の成熟プロセスを経ます。
次のセクションでは、WordPress 5.8でサポートされる設定と、Gutenberg プラグインでサポートされる設定を示します。
settings セクションは以下の構造を持ちます。
WordPress
{
"version": 2,
"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": 2,
"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": {
"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,
"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 です。テーマはこの設定を使用して、以下を有効化できます。
- border: color, radius, style, width
- color: link
- dimensions: 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 でグラデーションのリストを渡す |
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.spacingScale: padding、margin、gap の設定に使用する、spacing プリセットサイズの配列の生成に使用されます。operator: ステップを掛け算で計算するか(*)、足し算で計算するか(+)を指定します。increment: 各ステップの増加量。コアはデフォルトで1.5の掛け算、「完全五度」を使用します。steps: spacing スケールを生成するステップ数。デフォルトは7。spacing プリセットを生成せず、関連する UI を無効にするには、0に設定します。mediumStep: スケールのステップは、中間のステップから減少、増加の2方向に生成されるため、これは中間の space のサイズ値でなければならず、単位を含みません。デフォルトの中間のステップは1.5remのため、mediumStep の値は1.5です。unit: スケールの使用する単位。例えば、px, rem, em, %。デフォルトはrem。
spacing.spacingSizes: 足し算や掛け算で生成できないサイズの並びがある場合、テーマは spacing プリセットサイズの静的配列spacing.spacingSizesを含めることを選択できます。name: 人が読めるサイズの名前。例:Small, Medium, Large。slug: 機械が読める名前。サイトやテーマ間の互換性を保つため、slug は “10”, “20”, “30”, “40”, “50”, “60” の形式で、”50″はMediumサイズの値を表してください。size: 単位を含むサイズ。例:1.5rem. fluid 値を含むことも可能。例:clamp(2rem, 10vw, 20rem)
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": 2,
"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": 2,
"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": 2,
"settings": {
"color": {
"custom": false
},
"blocks": {
"core/paragraph": {
"color": {
"custom": true
}
}
}
}
}
- ボタンブロックの枠の角丸を無効化
{
"version": 2,
"settings": {
"blocks": {
"core/button": {
"border": {
"radius": false
}
}
}
}
}
- グループブロックのみに他と異なるパレットを設定
{
"version": 2,
"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": 2,
"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": 2,
"styles": {
"border": {
"color": "value",
"radius": "value",
"style": "value",
"width": "value"
},
"color": {
"background": "value",
"gradient": "value",
"text": "value"
},
"dimensions": {
"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": 1,
"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": 1,
"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-buttonCSS クラスにマップ。後方互換性のため、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 figcaptionCSS クラスにマップheading: すべての見出し、h1からh6CSS セレクタにマップ
WordPress によるサポート
h1:h1CSS セレクタにマップh2:h2CSS セレクタにマップh3:h3CSS セレクタにマップh4:h4CSS セレクタにマップh5:h5CSS セレクタにマップh6:h6CSS セレクタにマップlink:aCSS セレクタにマップ
トップレベルにあれば、要素セレクタが使用されます。ブロック内にあれば、使用されるセレクタは、対応するブロックに追加された形の要素セレクタになります。
入力
{
"version": 1,
"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": 2,
"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": 2,
"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": 2,
"templateParts": [
{
"name": "my-template-part",
"title": "Header",
"area": "header"
}
]
}
patterns
theme.jsonの version 2 を使用して、WordPress Version 6.0 からサポートされます。
このフィールドには、パターンディレクトリから登録するパターンをリストアップできます。patterns フィールドはパターンディレクトリに登録されているパターンの slugs の配列です。パターンのスラッグは、パターンディレクトリの単一のパターンビューで url から抽出できます。例えば、URL https://wordpress.org/patterns/pattern/partner-logos でのスラッグは partner-logos です。
{
"version": 2,
"patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
}
theme.json を使用した開発
開発中に theme.json の設定やプロパティを覚えておくのは困難です。そのため、 JSON スキーマが作成されました。このスキーマは https://schemas.wp.org/trunk/theme.json で利用可能です。
コードエディターはスキーマを取り、ツールチップやオートコンプリート、エディタ内でのスキーマ検証などの支援機能を提供できます。Visual Studio Code でスキーマを使用するには、"$schema": "https://schemas.wp.org/trunk/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": 2,
"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": 2,
"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> という形でクラスをアタッチし、次のスタイルをキューに入れました。
.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": 2,
"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 はキャッシュをスキップし、常に新しいデータを使用します。
最終更新日: