原文
https://developer.wordpress.org/news/2023/08/adding-and-using-custom-settings-in-theme-json/
Justin Tadlock
2023年8月31日
私が theme.json で気に入っている機能のひとつが、「カスタム設定」のサポートです。ブロックシステム上での最も強力な構築方法のひとつですが、テーマ作成コミュニティではあまり活用されていません。
他のほとんどの theme.json プロパティとは異なり、カスタム設定は、インターフェイスのコントロールや、ユーザーが操作できる何かとは結びついていません。その動きを考えると「設定」という言葉さえ、少し無理を感じます。
カスタム設定が行っているのは実際には、WordPressがエディターやフロントエンドで出力する、CSSカスタムプロパティ (別名 CSS 変数) の設定です。
この記事では、カスタム設定がどのように機能し、何ができるのかを一緒に探索します。また実践的な例も見ていきます。この記事を読み終える頃には、その可能性を理解し、自分のテーマ内でユーザーに提供可能な限界に挑戦し始めることを願っています。
カスタム設定の動き
テキストシャドウに、サイト全体でひとつのグローバルな値を使いたいとします。伝統的なスタイルシートであれば、以下のようにCSSを記述します。
body {
--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.3 );
}
そうしたければ、この書き方を続けても何の問題ありません。しかし、私は WordPress 流の方法をお勧めします。
早速、試してみましょう。まず、theme.json ファイルに以下のコードを追加します。
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"custom": {
"textShadow": "2px 2px 2px rgba( 0, 0, 0, 0.3 )"
}
}
}
WordPress は自動的に CSS カスタムプロパティを生成し、フロントエンドとエディターの両方に読み込みます。結果のCSSコードは次のようになります。
body {
--wp--custom--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.3 );
}
カスタム CSS と WordPress が生成する CSS の違いはなんでしょう ? それは CSS カスタムプロパティの名前です。
この名前は theme.json から来る他のプリセット （カスタムフォントサイズ、スペーシングスケール、色など） に従います。例えば、パレットにある色の CSS カスタムプロパティ名は --wp--preset--color--{$slug} です。
つまりこの機能は、標準的な命名規則に従った CSS カスタムプロパティを作成します。
ヒント: WordPress は生成された CSS の中で、自動的にキャメルケースのプロパティをハイフン形式に変換します。たとえば textShadow は text-shadow になります。数字も大文字と同じように扱われることに注意してください。
なぜ WordPress 規約に従うのか ?
CSS のカスタムプロパティを作成するだけなのに、なぜ WordPress の標準に従わなければならないのでしょう ? 自分しか使わないのに。
経験則から言うと、できる限り WordPress の組み込み機能を使うべきです。そうすればより多くの機能やツールにアクセスできます。カスタム設定も同じです。
いくつか例を挙げてみます。きっとメリットがわかるはずです !
グローバルスタイルのバリエーションと子テーマでの上書き
カスタム設定を使用すると、グローバルスタイルのバリエーションや子テーマで、簡単に値を上書きできます。
上の text-shadow の例を思い出してください。テーマのバリエーションから上書きしてみましょう。新しい /styles/example.json ファイルを作成し、次の JSON コードを追加します。
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"title": "Example",
"settings": {
"custom": {
"textShadow": "2px 2px 2px rgba( 0, 0, 0, 0.7 )"
}
}
}
「外観」 > 「エディター」 > 「スタイル」で、例のスタイルバリエーションを保存すると、WordPress は /styles/example.json の settings.custom.textShadow の値を使用して、以下の CSS を出力します。
body {
--wp--custom--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.7 );
}
上書きはほんの始まりに過ぎません。カスタムバリエーションや子テーマのために （そして子テーマの中で）、まったく新しいプロパティも定義できます。
ブロックごとのカスタムプロパティ
WordPress の方法で行うことで、特定のブロックのためのカスタムプロパティも書けます。自身のグローバル設定をブロックレベルで上書きすることさえできます。
例えば、見出しブロックが使用されているときに text-shadow プロパティを変更したいとします。それには、settings.blocks[core/heading].custom.textShadow を使用します。以下を試してみてください。
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"custom": {
"textShadow": "2px 2px 2px rgba( 0, 0, 0, 0.3 )"
},
"blocks": {
"core/heading": {
"custom": {
"textShadow": "2px 2px 2px rgba( 0, 0, 0, 0.7 )"
}
}
}
}
}
WordPress は以下の CSS を生成します。
body {
--wp--custom--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.3 );
}
.wp-block-heading {
--wp--custom--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.7 );
}
theme.json データのフィルタリング
より高度な使用例として、theme.json 関連のフィルターフックと関数を通して、設定にアクセスできます。例えば、wp_theme_json_data_theme をフィルタリングして、動的にデータを変更できます。
詳しくは「サーバーサイドフィルタを使用して theme.json データを変更する方法」を参照してください。
カスタム設定とブロックプラグインの統合
ブロックプラグインの中には、テーマが CSS カスタムプロパティのデフォルト値を定義できるものもあります。もちろん、プラグインはカスタムプロパティを使用し、 theme.json と互換性のある方法で名前を付けなければなりません。
ここで、架空のサードパーティ製ブロック「Super Duper」のサポートを追加したいとします。その CSS にはカスタムプロパティがあり、ブロックのデフォルトの高さを設定し、CSS フィルタを適用します。
.wp-block-super-duper {
height: var( --wp--custom--super-duper--height, 1rem );
filter: var( --wp--custom--super-duper--filter, blur( 8px ) );
}
まず最初に、テーマのことを考え、CSS カスタムプロパティを名前空間化してくれた、プラグイン作者に感謝しましょう。
サードパーティのブロックが存在すれば、theme.json でheight と filter プロパティをカスタマイズできます。
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"custom": {
"superDuper": {
"height": "1.5rem",
"filter": "grayscale( 100% )"
}
}
}
}
このテクニックを使用したブロックプラグインはあまり見かけませんが、ないわけではありません。私の希望は、これがブロック開発のスタンダードになることです。
ヒント: あなたはブロック開発者ですか ? テーマの作者たちは、あなたのコードと簡単に統合できることを熱望しています。このテクニックの詳細については、「ブロックのスタイリング: CSS カスタムプロパティでユーザーに力を」の「テーマの互換性に関する注意」を参照ください。
実際的なユースケース: フォーム入力のスタイリング
theme.json 内でいくつかのベースとなる要素やブロックをスタイリングするだけでも、かなりのことが可能です。しかし、WordPress のコア内で得られるデザインツールに限られます。それ以上を望むのであれば、カスタム設定の利用が必要です。
たとえば theme.json は標準的なデザイン機能でのフォーム要素のスタイリングをサポートしていません。実はこれは私の悩みの種の1つでもあります。
より良いフォーム処理に努めているコントリビューターもいます。しかし、目の前に締め切りが来ている状況では、次のリリースを待ってはいられないでしょう。そこで、settings.custom で基本的なサポートを追加する方法を説明します。
theme.json 内でのカスタムプロパティの作成
サンプルコードが複雑にならないように、少ない色数で試します。ここでは <input>、<select>、<textarea> 要素にテキスト色、背景色、ボーダー色を追加します。もちろん、これをタイポグラフィや影、他の任意の CSS 仕様に拡張できます。
まず、使いたい3色を選びましょう。ここではグレーのミックスにします。
theme.json の settings.custom.formInput オブジェクトの下に色を追加します。
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"custom": {
"formInput": {
"color": "#000000",
"background": "#f1f5f9",
"borderColor": "#e2e8f0"
}
}
}
}
コードの中の変化に気づきましたか ? これまでの例では settings.custom オブジェクトの直下にカスタムプロパティと値をネストしていました。この theme.json コードでは、別のネストオブジェクトを追加し、フォーム入力用のすべての CSS カスタムプロパティをまとめてグループ化しています。
そして、これが WordPress が出力するCSSです。
body {
--wp--custom--form-input--color: #000000;
--wp--custom--form-input--background: #f1f5f9;
--wp--custom--form-input--border-color: #e2e8f0;
}
WordPress は適切な入れ子で、プロパティ名を生成します。すべての正しいレベルを順番に追加し、2つのハイフンでつなぎます。
settings.custom の中には、好きなだけネストを増やせます。しかし、あまりやり過ぎない方がいいでしょう。レベルが増えれば増えるほど、CSS カスタムプロパティ名は長く複雑になります。
CSS でのカスタムプロパティの使用
次のステップはこのカスタムプロパティを使用する番です。つまり、CSS ファイルのどこかにコードを貼り付けます。ところでこのチュートリアルではスタイリングに必要なすべてを、テーマのプライマリ style.css ファイルで読み込むと仮定しています。
ですので、以下のコードをテーマの style.css に追加します。
input:where( :not( [type=checkbox] ):not( [type=radio ] ) ),
select,
textarea {
color: var( --wp--custom--form-input--color, inherit );
background: var( --wp--custom--form-input--background, transparent );
border: 1px solid var( --wp--custom--form-input--border-color, currentColor );
/* Other CSS rules... */
}
もちろんフォーム全体のスタイリングを整えるには、おそらく CSS を刷新したいところでしょう。このコードは、サンプルとして定義したカスタムプロパティの使い方を紹介することのみを目的としています。
テストでは「Login/out」コアブロックを使用しています (フォーム表示のためログアウトした状態)。サンプルとしてはちょっとまずい選択だったかもしれません。WordPress 6.3 でも、このフォームのスタイリング (の欠如) はいまイチです。
今できるところを対処しましょう。以下の CSS を使用して、Login/out ブロックのレイアウトを使えるものにします。
.wp-block-loginout form {
display: grid;
grid-template-columns: repeat( 1, 1fr );
gap: var( --wp--style--block-gap );
}
.wp-block-loginout form > * {
margin: 0;
}
.wp-block-loginout form input:not([type=submit]):not([type=checkbox]):not([type=hidden]) {
box-sizing: border-box;
display: block;
width: 100%;
}
ただしこのコードはブロックのレイアウト問題を修正するだけです。その他のスタイルルールは、あなたの宿題とします。
子テーマ、またはスタイルバリエーションでの上書き
子テーマの theme.json ファイル、またはテーマの /styles フォルダ内のグローバルスタイルバリエーションで調整してみましょう。どちらの方法でも同じ結果になります。
ここでは以下の JSON コードを、任意の子テーマの theme.json に追加しました。
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"custom": {
"formInput": {
"background": "#f0ebe4",
"borderColor": "#e9e1d8"
}
}
}
}
コードをよく見ると、親テーマの theme.json で定義されていた settings.formInput.color プロパティが欠けていますが、これは意図的なものです。WordPress の theme.json システムは階層構造になっていて、プロパティは親レベルから継承されます。
WordPress は親と子の両方の theme.json ファイルからデータを取得して、以下の CSS を生成します。
body {
--wp--custom--form-input--color: #000000;
--wp--custom--form-input--background: #f0ebe4;
--wp--custom--form-input--border-color: #e9e1d8;
}
子テーマを有効化するとフォームは以下のようになります。
この方法は私がテーマでカスタムスタイルルールを追加する際に、常用するテクニックのひとつになりました。私は常に子テーマの作者が、この簡単なカスタマイズ方法を理解することを希望します。これは非常に柔軟性のある強力な機能です。あなたのテーマでも試してみてください。
Props to @marybaum and @bph レビューとフィードバックに対して
タグ:
Block themes, Classic themes, theme.json
