<!--
# Adding and using custom settings in theme.json
-->
# theme.json でのカスタム設定の追加と利用

原文
https://developer.wordpress.org/news/2023/08/adding-and-using-custom-settings-in-theme-json/
Justin Tadlock
2023年8月31日

<!--
One of my favorite features of theme.json is its support of custom settings. It’s one of the most powerful ways to build on top of the block system but is often underutilized by the theming community.
-->
私が `theme.json` で気に入っている機能のひとつが、「カスタム設定」のサポートです。ブロックシステム上での最も強力な構築方法のひとつですが、テーマ作成コミュニティではあまり活用されていません。

<!--
Unlike most other theme.json properties, custom settings aren’t tied to controls in the interface or something that users can interact with. Even the term “settings” is a bit of a stretch when thinking about how they work.
-->
他のほとんどの `theme.json` プロパティとは異なり、カスタム設定は、インターフェイスのコントロールや、ユーザーが操作できる何かとは結びついていません。その動きを考えると「設定」という言葉さえ、少し無理を感じます。

<!--
What you’re actually doing is configuring CSS custom properties (aka CSS variables) that WordPress will output in the editor and on the front end.
-->
カスタム設定が行っているのは実際には、WordPressがエディターやフロントエンドで出力する、CSSカスタムプロパティ (別名 CSS 変数) の設定です。

<!--
Let’s spend some time together exploring how custom settings work and what they let you do. Then we’ll walk through a practical example. And by the end, I hope you’ll see the possibilities and start pushing the limits of what you can give your users in your own themes.
-->
この記事では、カスタム設定がどのように機能し、何ができるのかを一緒に探索します。また実践的な例も見ていきます。この記事を読み終える頃には、その可能性を理解し、自分のテーマ内でユーザーに提供可能な限界に挑戦し始めることを願っています。

<!--
Table of Contents

How custom settings work
Why follow the WordPress convention?
Overrides in global style variations and child themes
Per-block custom properties
Filtering theme.json data
Integrating custom settings with block plugins
A practical use case: styling form inputs
Create custom properties in theme.json
Use the custom properties in CSS
Override in a child theme or style variation
-->
<!--
## How custom settings work
-->
## カスタム設定の動き

<!--
Suppose you wanted to use one global value for text shadows across your site. This might be how you’d write the CSS for it in a traditional stylesheet:
-->
テキストシャドウに、サイト全体でひとつのグローバルな値を使いたいとします。伝統的なスタイルシートであれば、以下のようにCSSを記述します。

body {
	--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.3 );
}

<!--
It’s perfectly OK to keep doing that if you want, but I recommend doing it the WordPress way.

So let’s try that out. First, add this code to your theme.json file:
-->
そうしたければ、この書き方を続けても何の問題ありません。しかし、私は 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 will automatically generate the CSS custom property for you and load it on both the front-end and in the editor. The resulting CSS code will be:
-->
WordPress は自動的に CSS カスタムプロパティを生成し、フロントエンドとエディターの両方に読み込みます。結果のCSSコードは次のようになります。

body {
	--wp--custom--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.3 );
}

<!--
The difference between your custom CSS and that generated by WordPress? The name of the CSS custom property.
-->
カスタム CSS と WordPress が生成する CSS の違いはなんでしょう ? それは CSS カスタムプロパティの名前です。

<!--
That tracks with other presets that come from theme.json—custom font sizes, spacing scale, colors, and more. For example, a color from your palette would get the CSS custom property name of --wp--preset--color--{$slug}.
-->
この名前は `theme.json` から来る他のプリセット （カスタムフォントサイズ、スペーシングスケール、色など） に従います。例えば、パレットにある色の CSS カスタムプロパティ名は `--wp--preset--color--{$slug}` です。

<!--
In a nutshell, this feature creates CSS custom properties that follow a standard naming convention.
-->
つまりこの機能は、標準的な命名規則に従った CSS カスタムプロパティを作成します。

<!--
WordPress will automatically hyphenate camel-cased properties in the generated CSS. So textShadow becomes text-shadow. Note that numbers are also treated the same as an uppercase letter.
-->
> ヒント: WordPress は生成された CSS の中で、自動的にキャメルケースのプロパティをハイフン形式に変換します。たとえば `textShadow` は `text-shadow` になります。数字も大文字と同じように扱われることに注意してください。

<!--
## Why follow the WordPress convention?
-->
## なぜ WordPress 規約に従うのか ?

<!--
You may be wondering why you should follow the WordPress standard if all it does is create CSS custom properties. I mean, you can do that all on your own, right?
-->
CSS のカスタムプロパティを作成するだけなのに、なぜ WordPress の標準に従わなければならないのでしょう ? 自分しか使わないのに。

<!--
A good rule of thumb is to use WordPress’ built-in features whenever you can. That’s because you’ll usually get access to more features and tools. And custom settings are no different.
-->
経験則から言うと、できる限り WordPress の組み込み機能を使うべきです。そうすればより多くの機能やツールにアクセスできます。カスタム設定も同じです。

<!--
Let’s dive into some examples. I’m sure you’ll see the benefits!
-->
いくつか例を挙げてみます。きっとメリットがわかるはずです !

<!--
### Overrides in global style variations and child themes
-->
### グローバルスタイルのバリエーションと子テーマでの上書き

<!--
Custom settings make it trivial to override the values via global style variations and child themes.
-->
カスタム設定を使用すると、グローバルスタイルのバリエーションや子テーマで、簡単に値を上書きできます。

<!--
Remember the text-shadow example above? Try overriding it from a variation in your theme. Make a new /styles/example.json file and add this JSON code to it:
-->
上の 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 )"
		}
	}
}

<!--
Once you save the Example style variation via Appearance > Editor > Styles, WordPress will use the settings.custom.textShadow value from /styles/example.json and output this CSS:
-->
「外観」 > 「エディター」 > 「スタイル」で、例のスタイルバリエーションを保存すると、WordPress は `/styles/example.json` の `settings.custom.textShadow` の値を使用して、以下の CSS を出力します。

body {
	--wp--custom--text-shadow: 2px 2px 2px rgba( 0, 0, 0, 0.7 );
}

<!--
And overrides are just the beginning. You can also define completely new properties for (and in) your custom variations or child themes.
-->
上書きはほんの始まりに過ぎません。カスタムバリエーションや子テーマのために （そして子テーマの中で）、まったく新しいプロパティも定義できます。

<!--
### Per-block custom properties
-->
### ブロックごとのカスタムプロパティ

<!--
Doing things the WordPress way also lets you write custom properties for a specific block. You can even override your own global settings at the block level.
-->
WordPress の方法で行うことで、特定のブロックのためのカスタムプロパティも書けます。自身のグローバル設定をブロックレベルで上書きすることさえできます。

<!--
Suppose you wanted to change the text-shadow property when a Heading block is in use. To do that, target settings.blocks[core/heading].custom.textShadow. Give it a try:
-->
例えば、見出しブロックが使用されているときに 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 will generate this CSS:
-->
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 );
}

<!--
### Filtering theme.json data
-->
### theme.json データのフィルタリング
<!--
For more advanced use cases, you have access to the settings through theme.json-related filter hooks and functions. For example, you could filter wp_theme_json_data_theme to dynamically alter the data.
-->
より高度な使用例として、`theme.json` 関連のフィルターフックと関数を通して、設定にアクセスできます。例えば、`wp_theme_json_data_theme` をフィルタリングして、動的にデータを変更できます。

<!--
Find out more at How to modify theme.json data using server-side filters.
-->
詳しくは「[サーバーサイドフィルタを使用して theme.json データを変更する方法](https://developer.wordpress.org/news/2023/07/how-to-modify-theme-json-data-using-server-side-filters/)」を参照してください。

<!--
### Integrating custom settings with block plugins
-->
### カスタム設定とブロックプラグインの統合

<!--
Some block plugins let your theme define default values for CSS custom properties. Of course, the plugin must use custom properties and name them in a way that is compatible with theme.json.
-->
ブロックプラグインの中には、テーマが CSS カスタムプロパティのデフォルト値を定義できるものもあります。もちろん、プラグインはカスタムプロパティを使用し、 `theme.json` と互換性のある方法で名前を付けなければなりません。

<!--
Let’s suppose you wanted to add support for a third-party block named Super Duper. Its CSS has a couple of custom properties—to set the block’s default height and apply a CSS filter:
-->
ここで、架空のサードパーティ製ブロック「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 ) );
}

<!--
Before doing anything else, go thank that plugin author for taking themes into consideration, and for namespacing the CSS custom properties.
-->
まず最初に、テーマのことを考え、CSS カスタムプロパティを名前空間化してくれた、プラグイン作者に感謝しましょう。

<!--
If that third-party block existed, you could customize its height and filter properties in your theme.json:
-->
サードパーティのブロックが存在すれば、`theme.json` で`height` と `filter` プロパティをカスタマイズできます。

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"custom": {
			"superDuper": {
				"height": "1.5rem",
				"filter": "grayscale( 100% )"
			}
		}
	}
}

<!--
I haven’t seen many block plugins in the wild that use this technique, but there are a few roaming about. My hope is that this becomes a standard in block development.
-->
このテクニックを使用したブロックプラグインはあまり見かけませんが、ないわけではありません。私の希望は、これがブロック開発のスタンダードになることです。

<!--
Are you a block developer? Theme authors love it when you make it easy for them to integrate with your code. To learn more about this technique, read “A note about theme compatibility” from Styling blocks: empowering users with CSS custom properties.
-->
> ヒント: あなたはブロック開発者ですか ? テーマの作者たちは、あなたのコードと簡単に統合できることを熱望しています。このテクニックの詳細については、「[ブロックのスタイリング: CSS カスタムプロパティでユーザーに力を](https://developer.wordpress.org/news/2023/08/styling-blocks-empowering-users-with-css-custom-properties/)」の「テーマの互換性に関する注意」を参照ください。

<!--
## A practical use case: styling form inputs
-->
## 実際的なユースケース: フォーム入力のスタイリング

<!--
You can get pretty far with styling a few base elements and blocks in theme.json. But you are limited to the design tools you get in core WordPress. If you want to do more, that’s when you reach for custom settings.
-->
theme.json 内でいくつかのベースとなる要素やブロックをスタイリングするだけでも、かなりのことが可能です。しかし、WordPress のコア内で得られるデザインツールに限られます。それ以上を望むのであれば、カスタム設定の利用が必要です。

<!--
This is actually one of my pet-peeves: theme.json doesn’t support styling form elements with the standard design features.
-->
たとえば `theme.json` は標準的なデザイン機能での[フォーム要素のスタイリングをサポートしていません](https://github.com/WordPress/gutenberg/issues/34198)。実はこれは私の悩みの種の1つでもあります。

<!--
There are some contributors working hard on better form handling. But if you’re staring down a deadline, you can’t wait around for that to show up in a release. So let’s walk through adding some base support with settings.custom.
-->
[より良いフォーム処理](https://github.com/WordPress/gutenberg/pull/44214)に努めているコントリビューターもいます。しかし、目の前に締め切りが来ている状況では、次のリリースを待ってはいられないでしょう。そこで、`settings.custom` で基本的なサポートを追加する方法を説明します。

<!--
### Create custom properties in theme.json
-->
### theme.json 内でのカスタムプロパティの作成

<!--
To keep the code examples from getting out of hand, let’s work with just a few colors. I’ll show you how to add text, background, and border colors for `<input>`, `<select>`, and `<textarea>` elements. And of course you’d probably extend this to typography, shadows, or anything else in the CSS specification.

First, pick out the three colors you want to use. I’m going with a mix of grays:
-->
サンプルコードが複雑にならないように、少ない色数で試します。ここでは `<input>`、`<select>`、`<textarea>` 要素にテキスト色、背景色、ボーダー色を追加します。もちろん、これをタイポグラフィや影、他の任意の CSS 仕様に拡張できます。

まず、使いたい3色を選びましょう。ここではグレーのミックスにします。
<!--
-->

<!--
Add your colors to `theme.json` under a custom `settings.custom.formInput` object:
-->
`theme.json` の `settings.custom.formInput` オブジェクトの下に色を追加します。

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"custom": {
			"formInput": {
				"color": "#000000",
				"background": "#f1f5f9",
				"borderColor": "#e2e8f0"
			}
		}
	}
}

<!--
_Did you catch something new in the code?_ In previous examples, you nested the custom properties and values right in the `settings.custom` object. This `theme.json` code adds another nested object that groups all the CSS custom properties for form inputs together.

And here’s the CSS that WordPress will output:
-->
_コードの中の変化に気づきましたか ?_ これまでの例では `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 generates the property names with proper nesting. It adds all the correct levels, in order, and separates them with a double hyphen.

You can add as many levels of nesting as you want inside of `settings.custom`. But you probably shouldn’t take it too far. The more levels, the longer and more complex your CSS custom property names become.
-->
WordPress は適切な入れ子で、プロパティ名を生成します。すべての正しいレベルを順番に追加し、2つのハイフンでつなぎます。

`settings.custom` の中には、好きなだけネストを増やせます。しかし、あまりやり過ぎない方がいいでしょう。レベルが増えれば増えるほど、CSS カスタムプロパティ名は長く複雑になります。

<!--
### Use the custom properties in CSS
-->
### CSS でのカスタムプロパティの使用

<!--
The next step is putting those custom properties to use. That means sticking a bit of code in a CSS file somewhere. For this tutorial, I’ll assume that you’re loading the theme’s primary `style.css` file for any of your styling needs.

So add this code to your theme’s `style.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... */
}

<!--
Of course, you’ll probably want to flesh that CSS out for better overall form styling. This code only shows you how to use the custom properties that you defined.

I’m testing this with the Login/out core block (while logged out so that it shows the form). Perhaps that was a poor choice in examples because its default styling—or lack thereof—[is a bit messy](https://github.com/WordPress/gutenberg/issues/50466) as of WordPress 6.3.

We might as well take care of that while we’re here. Use this CSS to make the Login/out block’s layout serviceable:
-->

もちろんフォーム全体のスタイリングを整えるには、おそらく CSS を刷新したいところでしょう。このコードは、サンプルとして定義したカスタムプロパティの使い方を紹介することのみを目的としています。

テストでは「Login/out」コアブロックを使用しています (フォーム表示のためログアウトした状態)。サンプルとしてはちょっとまずい選択だったかもしれません。WordPress 6.3 でも、このフォームのスタイリング (の欠如) は[いまイチ](https://github.com/WordPress/gutenberg/issues/50466)です。

今できるところを対処しましょう。以下の 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%;
}

<!--
This only fixes the block’s layout issues. I’ll leave any other style rules up to you. 
-->
ただしこのコードはブロックのレイアウト問題を修正するだけです。その他のスタイルルールは、あなたの宿題とします。

<!--
### Override in a child theme or style variation
-->
### 子テーマ、またはスタイルバリエーションでの上書き

<!--
Try making some adjustments either through a child theme’s `theme.json` file or a global style variation in your theme’s `/styles` folder. Either method will yield the same result.

I added this JSON code to the `theme.json` in one of my child themes:
-->

子テーマの `theme.json` ファイル、またはテーマの `/styles` フォルダ内のグローバルスタイルバリエーションで調整してみましょう。どちらの方法でも同じ結果になります。

ここでは以下の JSON コードを、任意の子テーマの `theme.json` に追加しました。

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"custom": {
			"formInput": {
				"background": "#f0ebe4",
				"borderColor": "#e9e1d8"
			}
		}
	}
}

<!--
If you look closely at the code, you should see that I left out the `settings.formInput.color` property that was defined in the parent theme’s `theme.json`. This was intentional. WordPress’ `theme.json` system is hierarchical, so properties are inherited from the parent level in the hierarchy.

WordPress will generate this CSS, pulling data from both the parent and child `theme.json` files:
-->
コードをよく見ると、親テーマの `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;
}

<!--
And forms will look like this with the child theme active:


This method has quickly become one of my go-to techniques whenever I add custom style rules in my theme. I always want child theme authors to have an easy way to alter those customizations. It’s a powerful feature that offers a ton of flexibility. So give it a try in your themes.
-->
子テーマを有効化するとフォームは以下のようになります。


この方法は私がテーマでカスタムスタイルルールを追加する際に、常用するテクニックのひとつになりました。私は常に子テーマの作者が、この簡単なカスタマイズ方法を理解することを希望します。これは非常に柔軟性のある強力な機能です。あなたのテーマでも試してみてください。

_Props to [@marybaum](https://profiles.wordpress.org/marybaum/) and [@bph](https://profiles.wordpress.org/bph/) レビューとフィードバックに対して_

**タグ:**

[Block themes](https://developer.wordpress.org/news/tag/block-themes/), [Classic themes](https://developer.wordpress.org/news/tag/classic-themes/), [theme.json](https://developer.wordpress.org/news/tag/theme-json/)