テーマとブロックエディター: 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));
}
カラープロパティ
以下は現在、ブロックでサポートされる色プロパティです。
Context | Background | Gradient | Link | Text |
---|---|---|---|---|
Global | Yes | Yes | Yes | Yes |
Columns | Yes | Yes | Yes | Yes |
Group | Yes | Yes | Yes | Yes |
Heading [1] | Yes | – | Yes | Yes |
List | Yes | Yes | – | Yes |
Media & text | Yes | Yes | Yes | Yes |
Navigation | Yes | – | – | Yes |
Paragraph | Yes | – | Yes | Yes |
Post Author | Yes | Yes | Yes | Yes |
Post Comments | Yes | Yes | Yes | Yes |
Post Comments Count | Yes | Yes | – | Yes |
Post Comments Form | Yes | Yes | Yes | Yes |
Post Date | Yes | Yes | – | Yes |
Post Excerpt | Yes | Yes | Yes | Yes |
Post Hierarchical Terms | Yes | Yes | Yes | Yes |
Post Tags | Yes | Yes | Yes | Yes |
Post Title | Yes | Yes | – | Yes |
Site Tagline | Yes | Yes | – | Yes |
Site Title | Yes | Yes | – | Yes |
Template Part | Yes | Yes | Yes | Yes |
[1] 「見出し」ブロックは6つの異なる HTML 要素、H1 から H6 を表します。それぞれ個別の要素をターゲットとするセレクタも付きます。たとえば H1 に対して core/heading/h1 等。
スペース関連のプラパティ
Context | Padding |
---|---|
Cover | Yes |
Group | Yes |
タイポグラフィプロパティ
以下は現在、ブロックでサポートされるタイポグラフィプロパティです。
Context | Font Family | Font Size | Font Style | Font Weight | Line Height | Text Decoration | Text Transform |
---|---|---|---|---|---|---|---|
Global | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
Code | – | Yes | – | – | – | – | – |
Heading [1] | – | Yes | – | – | Yes | – | – |
List | – | Yes | – | – | – | – | – |
Navigation | Yes | Yes | Yes | Yes | – | Yes | Yes |
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 Title | Yes | Yes | – | – | Yes | – | – |
Preformatted | – | Yes | – | – | – | – | – |
Site Tagline | Yes | Yes | – | – | Yes | – | – |
Site Title | Yes | Yes | – | – | Yes | – | – |
Verse | Yes | Yes | – | – | – | – | – |
[1] 「見出し」ブロックは6つの異なる HTML 要素、H1 から H6 を表します。それぞれ個別の要素をターゲットとするセレクタも付きます。たとえば H1 に対して core/heading/h1 等。
最終更新日: