テーマとブロックエディター: theme.json (実験レベル)

この機能は現在、実験中です。初期の実装であり、将来、大規模で後方互換性のない変更があるという意味で、「実験中」です。

現在何を行っているのかを明らかにし、API を使用した実験からフィードバックを得るため、早い段階でドキュメントを共有します。フィードバックを歓迎します。意見のある方は週次の #core-editor 会議で共有するか、GitHub で issue やプルリクを作成してください。

この文書ではテーマがブロックエディターの提供するさまざまなサブシステムとどのように連携するのか、その方向性と現在進行中の作業について記述します。

  • 論拠
    • 設定をブロックごとに制御できる
    • いくつかのブロックスタイルは管理できる
    • CSS カスタムプロパティ: プリセット & カスタム
  • 仕様
    • settings
    • styles
    • その他のテーマのメタデータ
  • FAQ
    • CSS カスタムプロパティの命名体系
    • なぜ、セパレータとして、「–」を使用するのか ?
    • 「custom」下の設定は、どのように新しい CSS カスタムプロパティとなるのか ?

論拠

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

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

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

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

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

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

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

達成できることの例:

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

いくつかのブロックスタイルを管理できる

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

この方法の利点:

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

CSS カスタムプロパティ

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

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

入力

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

出力

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

入力

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

出力

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

仕様

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

experimental-theme.json ファイルでは、テーマがどのようにエディターを構成したいか (settings)、そして、設定するスタイルプロパティ (styles) を宣言します。

{
  "settings": { ... },
  "styles": { ... }
}

任意の登録ブロックに対して settings も styles もサブセクションを含むことができます。一般的なルールとしてサブセクションの名前はブロック名で、これは「ブロックセレクタ」と呼ばれます。たとえば段落ブロック (名前は core/paragraph)は、settings 内ではキー (あるいは「ブロックセレクタ」) core/paragraph として処理されます。

{
  "settings": {
    "core/paragraph": { ... }
  }
}

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

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

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

settings

settings セクションは以下の構造とデフォルト値を持ちます。

{
  "settings": {
    "defaults": {
      "layout": { /* Default layout to be used in the post editor */
        "contentSize": "800px",
        "wideSize": "1000px",
      }
      "border": {
        "customRadius": false /* true to opt-in */
      },
      "color": {
        "custom": true, /* false to opt-out, as in add_theme_support('disable-custom-colors') */
        "customGradient": true, /* false to opt-out, as in add_theme_support('disable-custom-gradients') */
        "gradients": [ ... ], /* gradient presets, as in add_theme_support('editor-gradient-presets', ... ) */
        "link": false, /* true to opt-in, as in add_theme_support('experimental-link-color') */
        "palette": [ ... ], /* color presets, as in add_theme_support('editor-color-palette', ... ) */
      },
      "custom": { ... },
      "spacing": {
        "customPadding": false, /* true to opt-in, as in add_theme_support('custom-spacing') */
        "units": [ "px", "em", "rem", "vh", "vw" ], /* filter values, as in add_theme_support('custom-units', ... ) */
      },
      "typography": {
        "customFontSize": true, /* false to opt-out, as in add_theme_support( 'disable-custom-font-sizes' ) */
        "customFontWeight": true, /* false to opt-out */
        "customFontStyle": true, /* false to opt-out */
        "customLineHeight": false, /* true to opt-in, as in add_theme_support( 'custom-line-height' ) */
        "dropCap": true, /* false to opt-out */
        "fontFamilies": [ ... ], /* font family presets */
        "fontSizes": [ ... ], /* font size presets, as in add_theme_support('editor-font-sizes', ... ) */
      }
    }
  }
}

それぞれのブロックは個別にこれらの設定を構成でき、既存の add_theme_support を介したものよりも、詳細な制御を行えます。

defaults ブロックセレクタの下で宣言されたブロック設定は、個別に上書きしない限り、すべてのブロックに影響します。継承のコンセプトを導入し、すべてのブロックを一度に迅速に構成できます。後方互換性のため、ブロックエディターを構成する既存の add_theme_support の宣言は、defaults セクションの適切なカテゴリーに割り当てられます。テーマが add_theme_support('disable-custom-colors') を使用している場合、これは settings.defaults.color.custom に false を設定したことと同じです。experimental-theme.json 内に設定があれば、 add_theme_support を介して宣言された値に優先します。

テーマ作者が段落ブロックのみにカスタムカラーを有効化したいとします。この場合、イカのようになります。

{
  "settings": {
    "defaults": {
      "color": {
        "custom": false // すべてのブロックで無効化
      }
    },
    "core/paragraph": {
      "color": {
        "custom": true // 段落ブロックは設定を上書き
      }
    }
  }
}

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

プリセット

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

例:

入力

{
    "settings": {
        "defaults": {
            "color": {
                "palette": [
                    {
                        "slug": "strong-magenta",
                        "color": "#a156b4"
                    },
                    {
                        "slug": "very-dark-grey",
                        "color": "rgb(131, 12, 8)"
                    }
                ],
                "gradients": [
                    {
                        "slug": "blush-bordeaux",
                        "gradient": "linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%)"
                    },
                    {
                        "slug": "blush-light-purple",
                        "gradient": "linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%)"
                    }
                ]
            },
            "typography": {
                "fontSizes": [
                    {
                        "slug": "normal",
                        "size": 16
                    },
                    {
                        "slug": "big",
                        "size": 32
                    }
                ]
            }
        }
    }
}

出力

:root {
    --wp--preset--color--strong-magenta: #a156b4;
    --wp--preset--color--very-dark-gray: #444;
    --wp--preset--font-size--big: 32;
    --wp--preset--font-size--normal: 16;
    --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%
    );
}

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

自由形式の CSS カスタムプロパティ

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

例:

入力

{
    "settings": {
        "defaults": {
            "custom": {
                "base-font": 16,
                "line-height": {
                    "small": 1.2,
                    "medium": 1.4,
                    "large": 1.8
                }
            }
        }
    }
}

出力

:root {
    --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;
}

注意: 変数名は各ネストレベルの間に -- を追加して作成されます。

styles

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

{
    "styles": {
        "some/block/selector": {
            "border": {
                "radius": "value"
            },
            "color": {
                "background": "value",
                "gradient": "value",
                "link": "value",
                "text": "value"
            },
            "spacing": {
                "padding": {
                    "top": "value",
                    "right": "value",
                    "bottom": "value",
                    "left": "value"
                }
            },
            "typography": {
                "fontFamily": "value",
                "fontSize": "value",
                "fontStyle": "value",
                "fontWeight": "value",
                "lineHeight": "value",
                "textDecoration": "value",
                "textTransform": "value"
            }
        }
    }
}

例:

{
    "styles": {
        "root": {
            "color": {
                "text": "var(--wp--preset--color--primary)"
            }
        },
        "core/heading/h1": {
            "color": {
                "text": "var(--wp--preset--color--primary)"
            },
            "typography": {
                "fontSize": "calc(1px * var(--wp--preset--font-size--huge))"
            }
        },
        "core/heading/h4": {
            "color": {
                "text": "var(--wp--preset--color--secondary)"
            },
            "typography": {
                "fontSize": "var(--wp--preset--font-size--normal)"
            }
        }
    }
}

出力

:root {
    color: var( --wp--preset--color--primary );
}
h1 {
    color: var( --wp--preset--color--primary );
    font-size: calc( 1px * var( --wp--preset--font-size--huge ) );
}
h4 {
    color: var( --wp--preset--color--secondary );
    font-size: calc( 1px * var( --wp--preset--font-size--normal ) );
}

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

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

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

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

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

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

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

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

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 内のオブジェクト形式に戻す仕組みも必要なためです。プリセットにも同じセパレータを使用します。

例:

入力

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

出力

:root {
    --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 オブジェクト内のキー名で -- を使用しないでください。例: 次のような命名は止めてください。
{
    "settings": {
        "defaults": {
            "custom": {
                "line--height": {
                    "body": 1.7
                }
            }
        }
    }
}

原文

最終更新日: