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

WordPress 5.8では、エディタを構成する新しいメカニズムが搭載されます。このメカニズムは、きめ細かい制御を可能にし、将来の WordPress リリースでのスタイル管理の、最初のステップとなる theme.json ファイルを導入します。このページでは、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 カスタムプロパティは CSS 変数とも呼ばれます。

入力

{
    "version": 1,
    "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": 1,
    "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": 1,
    "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 ファイルのフォーマットを表します。現在の唯一のバージョンは1です。

WordPress 5.8 は、現行バージョンと異なる theme.json の内容を無視します。Gutenberg プラグインは必要があれば、バージョンを更新し、古いバージョンからの移行メカニズムを追加します。

settings

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

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

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

WordPress

{
    "version": 1,
    "settings": {
        "color": {
            "custom": true,
            "customDuotone": true,
            "customGradient": true,
            "duotone": [],
            "gradients": [],
            "link": false,
            "palette": []
        },
        "custom": {},
        "layout": {
            "contentSize": "800px",
            "wideSize": "1000px"
        },
        "spacing": {
            "customMargin": false,
            "customPadding": false,
            "units": [ "px", "em", "rem", "vh", "vw" ]
        },
        "typography": {
            "customFontSize": true,
            "customLineHeight": false,
            "dropCap": true,
            "fontSizes": []
        },
        "blocks": {
            "core/paragraph": {
                "color": {},
                "custom": {},
                "layout": {},
                "spacing": {},
                "typography": {}
            },
            "core/heading": {},
            "etc": {}
        }
    }
}

Gutenberg

{
    "version": 1,
    "settings": {
        "border": {
            "customColor": false,
            "customRadius": false,
            "customStyle": false,
            "customWidth": false
        },
        "color": {
            "background": true,
            "custom": true,
            "customDuotone": true,
            "customGradient": true,
            "duotone": [],
            "gradients": [],
            "link": false,
            "palette": [],
            "text": true
        },
        "custom": {},
        "layout": {
            "contentSize": "800px",
            "wideSize": "1000px"
        },
        "spacing": {
            "customMargin": false,
            "customPadding": false,
            "units": [ "px", "em", "rem", "vh", "vw" ]
        },
        "typography": {
            "customFontSize": true,
            "customFontStyle": true,
            "customFontWeight": true,
            "customLineHeight": false,
            "customTextDecorations": true,
            "customTextTransforms": true,
            "dropCap": true,
            "fontFamilies": [],
            "fontSizes": []
        },
        "blocks": {
            "core/paragraph": {
                "border": {},
                "color": {},
                "custom": {},
                "layout": {},
                "spacing": {},
                "typography": {}
            },
            "core/heading": {},
            "etc": {}
        }
    }
}

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

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

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.customLineHeight に true を設定
custom-spacingspacing.customPadding に 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 でグラデーションのリストを渡す
experimental-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つのカスタムプロパティを生成します。
  • 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": 1,
    "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": "normal",
                    "size": 16,
                    "name": "Normal"
                },
                {
                    "slug": "big",
                    "size": 32,
                    "name": "Big"
                }
            ]
        },
        "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--big: 32;
    --wp--preset--font-size--normal: 16;
    --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;
}

/* 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": 1,
    "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": 1,
    "settings": {
        "color": {
            "custom": false
        },
        "blocks": {
            "core/paragraph": {
                "color": {
                    "custom": true
                }
            }
        }
    }
}
  • ボタンブロックの枠の角丸を無効化 (現在、枠はプラグインでのみ利用可能)
{
    "version": 1,
    "settings": {
        "blocks": {
            "core/button": {
                "border": {
                    "customRadius": false
                }
            }
        }
    }
}
  • グループブロックのみに他と異なるパレットを設定
{
    "version": 1,
    "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": 1,
    "styles": {
        "color": {
            "background": "value",
            "gradient": "value",
            "text": "value"
        },
        "spacing": {
            "margin": {
                "top": "value",
                "right": "value",
                "bottom": "value",
                "left": "value"
            },
            "padding": {
                "top": "value",
                "right": "value",
                "bottom": "value",
                "left": "value"
            }
        },
        "typography": {
            "fontSize": "value",
            "lineHeight": "value"
        },
        "elements": {
            "link": {
                "color": {},
                "spacing": {},
                "typography": {}
            },
            "h1": {},
            "h2": {},
            "h3": {},
            "h4": {},
            "h5": {},
            "h6": {}
        },
        "blocks": {
            "core/group": {
                "color": {},
                "spacing": {},
                "typography": {},
                "elements": {
                    "link": {},
                    "h1": {},
                    "h2": {},
                    "h3": {},
                    "h4": {},
                    "h5": {},
                    "h6": {}
                }
            },
            "etc": {}
        }
    }
}

Gutenberg

{
    "version": 1,
    "styles": {
        "border": {
            "color": "value",
            "radius": "value",
            "style": "value",
            "width": "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": {
            "fontFamily": "value",
            "fontSize": "value",
            "fontStyle": "value",
            "fontWeight": "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": {}
        }
    }
}

トップレベルスタイル

トップレベルのスタイルは 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 キーで指定します。

{
    "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 );
}

要素スタイル

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

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

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

{
    "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 );
}

defaults ブロックセレクタは、styles セクションの一部にはなれず、あっても無視されます。root ブロックセレクタはなることはできず、:root CSS セレクタと共にスタイルルールを生成します。

その他のテーマのメタデータ

theme.json にはさらに多くのテーマのメタデータを追加するニーズがあります。このセクションでは、それら他のフィールドを挙げます。

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

customTemplates

このフィールドは、Gutenberg プラグインが有効な場合にのみ許可されます。WordPress 5.8では無視されます。

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

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

templateParts

このフィールドは、Gutenberg プラグインが有効な場合にのみ許可されます。WordPress 5.8では無視されます。

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

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

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

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": 1,
    "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": 1,
    "settings": {
        "custom": {
            "line--height": { // DO NOT DO THIS
                "body": 1.7
            }
        }
    }
}

原文

最終更新日: