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

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

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

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

  • 論拠
    • 設定をブロックごとに制御できる
    • CSS カスタムプロパティ: プリセット & カスタム
    • いくつかのブロックスタイルは管理できる
  • 仕様
    • settings
    • styles

論拠

ブロックエディター周辺の API は異なる速度で進化しており、今やこのことから生じる苦労は、特にテーマに影響を与える部分で大きくなっています。例として エディターのプログラム的な制御や、ユーザー、テーマ、コアスタイルの好みを取りまとめるブロックスタイルシステム があります。

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

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

ブロックエディターはすでに、配置、ドロップキャップ (先頭の文字を大きくする)、インサーター内での表示の有無など、特定の設定をブロックレベルで実行できます。目標として、これらの機能をテーマからでもブロックレベルで制御できるようにします。

CSS カスタムプロパティ

カラーパレット、フォントサイズ、グラデーション などのプリセットは CSS カスタムプロパティとなり、システムでエンキューされるため、テーマはフロントエンドとエディターの両方で使うことができます。また独自の CSS カスタムプロパティを作成する仕組みもあります。

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

ブロックエディターは構造化した形式のブロックスタイルプロパティを提供することで、異なるソース (ユーザー、テーマ、コア) から来る CSS を「管理」し、ページにロードする CSS の量を減らし、テーマ、ブロック、プラグインなど関与するコンポーネントの競合したニーズによる「CSS 詳細度の戦い」を抑止します。

仕様

experimental-theme.json ファイルは「コンテキスト」と呼ばれる、異なる CSS セレクタを表すセクションに分けられます。たとえば core/paragraph コンテキストは p にマップし、core/group は .wp-block-group にマップします。一般に1つのブロックは1つのコンテキストにマップしますが、1つのブロックが複数のコンテキスト (異なる CSS セレクタ) を生成できる場合もあります。たとえば「見出し」ブロックは6つの異なるコンテキスト (core/heading/h1、core/heading/h2、等) を生成し、それぞれ異なるセレクタ (h1、h2、等) に対応します。

{
  "global": { ... },
  "core/paragraph": { ... },
  "core/group": { ... },
  "core/heading/h1": { ... },
  "core/heading/h2": { ... },
  "core/heading/h3": { ... },
  "core/heading/h4": { ... },
  "core/heading/h5": { ... },
  "core/heading/h6": { ... }
}

すべてのコンテキストは同じ構造を持ち2つのセクション settings と styles に分かれます。settings はエディターの制御、たとえばある機能の有効化、無効化やプリセットの定義に使用され、add_theme_support での宣言よりも優先されます。styles は新しいスタイルシート global-styles-inline-css の末尾に追加される新しいスタイルルールの作成に使用されます。global-styles-inline-css はフロントエンドとエディターの両方でエンキューされます。

{
  "some/context": {
    "settings": {
      "border": [ ... ],
      "color": [ ... ],
      "custom": [ ... ],
      "spacing": [ ... ],
      "typography": [ ... ]
    },
    "styles": {
      "border": { ... },
      "color": { ... },
      "typography": { ... }
    }
  }
}

この構造は3つの異なる既存ソース、コア、テーマ、ユーザーで共通です。テーマはファイル experimental-theme.json を作成することでコアのデフォルトを上書きできます。ユーザーもまた開発中のユーザーインターフェース、サイトエディターを介してテーマやコアの設定を上書きできる予定です。

settings

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

{
  "some/context": {
    "settings": {
      "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', ... ) */
        "fontStyles": [ ... ], /* font style presets */
        "fontWeights": [ ... ], /* font weight presets */
        "textDecorations": [ ... ], /* text decoration presets */
        "textTransforms": [ ... ] /* text transform presets */
      }
    }
  }
}

後方互換性のため add_theme_support の宣言は適切なカテゴリーに割り当てられます。テーマが add_theme_support('disable-custom-colors') を使用している場合、これは global.settings.color.custom に false を設定したことと同じです。experimental-theme.json の設定があれば、 add_theme_support で定義された値に優先します。

settings はまたコンテキストでも制御でき、既存の add_theme_support よりも詳細な制御が可能です。例えば、テーマ作者が「段落」 ブロックのみでカスタムカラーを有効化したければ以下のようになります。

{
  "global": {
    "settings": {
      "color": {
        "custom": false
      }
    }
  },
  "core/paragraph": {
    "settings": {
      "color": {
        "custom": true
      }
    }
  }

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

プリセット

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

たとえば次の入力に対して

{
  "global": {
    "settings": {
      "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%);
}

最終的な目標はこの形式を使用したプリセットの定義ですが、現在はまだこのファイルからエディターで使用される name プロパティを翻訳できません。この理由と、後方互換性のため、add_theme_support を介して宣言されたプリセットもまた CSS カスタムプロパティを生成します。experimental-theme.json に含まれるプリセットは add_theme_support を介して宣言されたプリセットに優先します。

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

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

たとえば次の入力に対して、

{
  "global": {
    "settings": {
      "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 ファイルを介してターゲットのテーマで利用できます。

{
  "some/context": {
    "styles": {
      "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"
      }
    }
  }
}

たとえば次のような入力は、

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

次のスタイルルールをスタイルシート末尾に追加します。

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

カラープロパティ

以下は現在、ブロックでサポートされる色プロパティです。

ContextBackgroundGradientLinkText
GlobalYesYesYesYes
ColumnsYesYesYesYes
GroupYesYesYesYes
Heading [1]Yes–YesYes
ListYesYes–Yes
Media & textYesYesYesYes
NavigationYes––Yes
ParagraphYes–YesYes
Post AuthorYesYesYesYes
Post CommentsYesYesYesYes
Post Comments CountYesYes–Yes
Post Comments FormYesYesYesYes
Post DateYesYes–Yes
Post ExcerptYesYesYesYes
Post Hierarchical TermsYesYesYesYes
Post TagsYesYesYesYes
Post TitleYesYes–Yes
Site TaglineYesYes–Yes
Site TitleYesYes–Yes
Template PartYesYesYesYes

[1] 「見出し」ブロックは6つの異なる HTML 要素、H1 から H6 を表します。それぞれ個別の要素をターゲットとするセレクタも付きます。たとえば H1 に対して core/heading/h1 等。

スペース関連のプラパティ

ContextPadding
CoverYes
GroupYes

タイポグラフィプロパティ

以下は現在、ブロックでサポートされるタイポグラフィプロパティです。

ContextFont FamilyFont SizeFont StyleFont WeightLine HeightText DecorationText Transform
GlobalYesYesYesYesYesYesYes
Code–Yes–––––
Heading [1]–Yes––Yes––
List–Yes–––––
NavigationYesYesYesYes–YesYes
Paragraph–Yes––Yes––
Post Author–Yes––Yes––
Post Comments–Yes––Yes––
Post Comments Count–Yes––Yes––
Post Comments Form–Yes––Yes––
Post Date–Yes––Yes––
Post Excerpt–Yes––Yes––
Post Hierarchical Terms–Yes––Yes––
Post Tags–Yes––Yes––
Post TitleYesYes––Yes––
Preformatted–Yes–––––
Site TaglineYesYes––Yes––
Site TitleYesYes––Yes––
VerseYesYes–––––

[1] 「見出し」ブロックは6つの異なる HTML 要素、H1 から H6 を表します。それぞれ個別の要素をターゲットとするセレクタも付きます。たとえば H1 に対して core/heading/h1 等。

原文

最終更新日: