カスタム設定の概要

この settings.custom プロパティは単一のオブジェクトを受け入れ、このオブジェクトは他の値を格納するために使用できます。個々のオブジェクトの値は有効な CSS 値であるか、ネストされたキー/値ペアを持つオブジェクトでなければなりません。

以下は、カスタム値が設定されていない theme.json からの例のスニペットです: 

  1. {
  2.     "version": 2,
  3.     "settings": {
  4.         "custom": {}
  5.     }
  6. }

settings.custom オブジェクトの素晴らしい点は、自分自身の CSS カスタムプロパティを作成するために使用できることです。オブジェクトにキーと値を追加すると、WordPress は自動的に CSS カスタムプロパティを生成し、値を割り当て、読み込んでくれます。

生成された CSS カスタムプロパティは次のパターンに従います: --wp--custom--{key}--{value}.

fruit のキーを使用し、apple の値を与えたいとします。これを theme.json ファイルに追加します: 

  1. {
  2.     "version": 2,
  3.     "settings": {
  4.         "custom": {
  5.             "fruit": "apple"
  6.         }
  7.     }
  8. }

WordPress は次の CSS を生成します: 

  1. body {
  2.     --wp--custom--fruit: apple;
  3. }

CSS カスタムプロパティの生成方法

上記で学んだように、settings.custom.fruit キー名は CSS で --wp--custom--fruit 変数を生成します。しかし、他にもケースがあります。

自動ハイフネーション

WordPress はキャメルケースの名前を自動的にハイフンで区切ります。例えば、以下の例の lineHeight は line-height になります: 

  1. {
  2.     "version": 2,
  3.     "settings": {
  4.         "custom": {
  5.             "lineHeight": "1.4em"
  6.         }
  7.     }
  8. }

これにより、次の CSS が生成されます: 

  1. body {
  2.     --wp--custom--line-height: 1.4em;
  3. }

数字は、キーとして使用されるときに大文字と同様に扱われます。例えば、abc123 のキーは、生成された CSS で abc-1-2-3 になります。

ネストされたプロパティ

上記の例を基に、テーマで使用するためにいくつかの行の高さの CSS カスタムプロパティを作成したいとします。このためには、単一の値の代わりに settings.custom.lineHeight の下にオブジェクトを作成することをお勧めします。

次の内容を theme.json ファイルに追加します: 

  1. {
  2.     "version": 2,
  3.     "settings": {
  4.         "custom": {
  5.             "lineHeight": {
  6.             "xs": "1",
  7.             "sm": "1.25",
  8.             "md": "1.5",
  9.             "lg": "1.75"
  10.             }
  11.         }
  12.     }
  13. }

WordPress は CSS カスタムプロパティ名を生成する際に、このネストされた構造を自動的に使用します。

これにより、次の CSS が生成されます: 

  1. body {
  2.     --wp--custom--line-height--xs: 1;
  3.     --wp--custom--line-height--sm: 1.25;
  4.     --wp--custom--line-height--md: 1.5;
  5.     --wp--custom--line-height--lg: 1.75;
  6. }

ネストの量に制限はありませんが、ネストが多くなるほど CSS カスタムプロパティ名が長くなることを考慮してください。

実用的な使用法

settings.custom プロパティを何に使用するかは完全にあなた次第です。その本質は、CSS カスタムプロパティを生成することだけであり、それ自体では何も行いません。カスタムプロパティは CSS で使用する必要があります。

上記の theme.json の例では、一連の行の高さを作成しました。これらを実際に使用する方法はいくつかあります。

theme.json スタイルでの使用

スタイルのドキュメント では、theme.json を介してルート要素、要素、およびブロックにスタイルを適用する方法を学びます。これは settings.custom と統合するための主要な使用ケースの一つになります。

上記の行の高さのセットを登録し、それを利用したいとします。ルート要素を md 行の高さに設定し、段落ブロックを lg に設定したいかもしれません。各行の高さプロパティにはそれぞれ var:custom|line-height|md と var:custom|line-height|lg を介してアクセスできます。

次のコードを theme.json ファイルに使用します: 

  1. {
  2.     "version": 2,
  3.     "settings": {
  4.         "custom": {
  5.             "lineHeight": {
  6.             "xs": "1",
  7.             "sm": "1.25",
  8.             "md": "1.5",
  9.             "lg": "1.75"
  10.             }
  11.         }
  12.     },
  13.     "styles": {
  14.         "typography": {
  15.             "lineHeight": "var:custom|line-height|md"
  16.         }
  17.         "blocks": {
  18.             "core/paragraph": {
  19.             "typography": {
  20.             "lineHeight": "var:custom|line-height|lg"
  21.             }
  22.             }
  23.         }
  24.     }
  25. }

また、CSS カスタムプロパティを介して値を参照することもできます。例えば、var:custom|line-height|md の代わりに var( --wp--custom--line-height--md ) を使用します。

覚えておいてください、スタイルのドキュメント から theme.json を介してスタイリングについてもっと学びます。そこで学んだことを、ここで説明した技術と組み合わせて使用できます。

CSS での使用

生成された CSS カスタムプロパティを CSS で直接参照する必要がある場合があります。例えば、style.css ファイルのように。これを行うには、CSS カスタムプロパティ名を使用する必要があります。

.example-class という名前のクラスをターゲットにし、登録した sm 行の高さを与えたいとします。次のコードを CSS に使用します: 

  1. .example-class {
  2.     line-height: var( --wp--custom--line-height--sm );
  3. }