テーマサポート

新しいブロックにはすべてのテーマで有効な基本サポートや、オプトイン可能なオプション、拡張やカスタマイズ可能な機能があります。

テーマを構築する際は、以下の新しいコンセプトを検討してください。

• エディターカラーパレット – 色のデフォルトセットを提供します。ただしテーマは独自の色を登録したり、オブションでユーザーに定義したパレットからのみ色を選択するよう強制できます。
• エディターテキストサイズパレット – テキストサイズのデフォルトセットを提供します。ただしテーマは独自のテキストサイズを登録したり、オブションでユーザーに設定されたサイズからのみ選択するよう強制できます。
• レスポンシブな埋め込みコンテンツ – テーマが埋め込みコンテンツをレスポンシブ化するにはオプトインしなければなりません。
• フロントエンドとエディターのスタイル – ブロックのスタイルを最大限活かすには、テーマ作者はコアのスタイルが適切であることを確認してオプトインするか、テーマに合う独自のスタイルを記述します。
• ブロックツール – テーマは「行の高さ」や「カスタムユニット」などいくつかのブロックツールをオプトインできます。
• コアのブロックパターン – テーマはデフォルトのブロックパターンをオプトアウトできます。

デフォルトでブロックはそのまま使える基本的なスタイルを提供します。また、以下で説明するようなオプトインで有効化するスタイルも提供します。テーマはこれらのスタイルを追加したり上書きできます。逆にテーマではまったくスタイルを提供せず、ブロックが提供するスタイルに完全に依存することもできます。

いくつかの高度なブロック機能はテーマによるオプトインのサポートが必要です。これはブロックからのスタイルの提供が容易ではなく、正しく動作するにはテーマの構造の理解が必要なためです。

これらの機能をオプトインするには以下の例のように、テーマの functions.php ファイルで add_theme_support を呼び出します。

function mytheme_setup_theme_supported_features() {
	add_theme_support( 'editor-color-palette', array(
		array(
			'name'  => esc_attr__( 'strong magenta', 'themeLangDomain' ),
			'slug'  => 'strong-magenta',
			'color' => '#a156b4',
		),
		array(
			'name'  => esc_attr__( 'light grayish magenta', 'themeLangDomain' ),
			'slug'  => 'light-grayish-magenta',
			'color' => '#d0a5db',
		),
		array(
			'name'  => esc_attr__( 'very light gray', 'themeLangDomain' ),
			'slug'  => 'very-light-gray',
			'color' => '#eee',
		),
		array(
			'name'  => esc_attr__( 'very dark gray', 'themeLangDomain' ),
			'slug'  => 'very-dark-gray',
			'color' => '#444',
		),
	) );
}

add_action( 'after_setup_theme', 'mytheme_setup_theme_supported_features' );

コアブロックにはデフォルトの構造化スタイルが含まれていてエディター、フロントエンドの両方でロードされます。このスタイルの例は「カラム」ブロックで利用されている CSS です。このルールがなければブロックはまったくカラムを含まない壊れたレイアウトになります。

ブロックエディターでテーマはフロントエンドに拡張したスタイルをオプトインできます。このスタイルの例は「引用」ブロックの左側のデフォルトのカラーバーです。テーマでこのスタイルを使用する場合はテーマサポートに wp-block-styles を追加します。

add_theme_support( 'wp-block-styles' );

ブロックライブラリーテーマファイル内で、含まれる CSS を参照できます。

「画像」ブロックやいくつかのブロックには「幅広 (wide)」や「全幅 (full)」を定義する機能があり、ブロックのラッパーに対応するクラス名を追加します (alignwide や alignfull)。テーマは以下のようにオプトインします。

add_theme_support( 'align-wide' );

この関数の詳細については add_theme_support() の開発者ドキュメント を参照してください。

幅広な画像、サイドバー、中央揃えのカラム、中央揃えのカラム内でフロートする要素等々、レスポンシブなレイアウト作成は困難です。

ブロックエディターはフロートした画像に追加マークアップを付加してスタイリングを容易にします。

キャプション付きの Image のマークアップを示します。

<figure class="wp-block-image">
	<img src="..." alt="" width="200px" />
	<figcaption>Short image caption.</figcaption>
</figure>

左にフロートする画像のマークアップを示します。

<div class="wp-block-image">
	<figure class="alignleft">
		<img src="..." alt="" width="200px" />
		<figcaption>Short image caption.</figcaption>
	</figure>
</div>

codepen にマークアップを使用した例があります。レスポンシブなレイアウトでサイドバー、幅広の画像、キャプション付きのフロートする要素ががあります。

異なるブロックはそれぞれで色をカスタマイズしている可能性があります。ブロックエディターはデフォルトのパレットを提供しますが、テーマはこれを上書きして独自のパレットを提供できます。

add_theme_support( 'editor-color-palette', array(
	array(
		'name'  => esc_attr__( 'strong magenta', 'themeLangDomain' ),
		'slug'  => 'strong-magenta',
		'color' => '#a156b4',
	),
	array(
		'name'  => esc_attr__( 'light grayish magenta', 'themeLangDomain' ),
		'slug'  => 'light-grayish-magenta',
		'color' => '#d0a5db',
	),
	array(
		'name'  => esc_attr__( 'very light gray', 'themeLangDomain' ),
		'slug'  => 'very-light-gray',
		'color' => '#eee',
	),
	array(
		'name'  => esc_attr__( 'very dark gray', 'themeLangDomain' ),
		'slug'  => 'very-dark-gray',
		'color' => '#444',
	),
) );

name は上の例のようなラベルです。ツールチップに表示され、ユーザーに意味のある説明を伝えます。スクリーンリーダーを使用するユーザーには特に重要で、説明が不十分であれば色の認識が困難になります。slug は色の一意の識別子です。ブロックエディターのカラーパレットで使われる CSS クラスの生成で使用されます。color は色を指定する16進コードです。

Twenty Nineteen テーマのメインカラーやサブカラーのように動的に変わる色もあり、これらの色はプログラム的に記述できません。その場合でも必要な際のデフォルト値として意味のあるテキストを name に設定することを推奨します。

色はパレット上に順番に表示され、指定可能な数に制限はありません。

テーマにはコンテキストに応じて色に適用するクラスを作成する責任があります。コアブロックは「color」コンテキスト、「background-color」コンテキスト、「border-color」コンテキストを使用します。コアブロックのすべてのコンテキストで正しく「strong magenta」を適用するにはテーマはクラス自身を実装する必要があります。クラス名は、最初に「has-」、続けてケバブケースを使用したクラス名、最後にコンテキスト名で作成します。

.has-strong-magenta-color {
	color: #a156b4;
}

.has-strong-magenta-background-color {
	background-color: #a156b4;
}

.has-strong-magenta-border-color {
	border-color: #a156b4;
}

WordPress 5.9 以降、theme.json を持たないテーマが、コアで定義された色の値を上書きするには、クラスを提供する代わりに、CSSカスタムプロパティで値を設定しなければなりません。CSSカスタムプロパティは、命名規則 --wp--preset--color--<slug> を使用します。詳細については devnote を参照してください。例えば

:root {
	--wp--preset--color--cyan-bluish-gray: <new_value>;
	--wp--preset--color--pale-pink: <new_value>;
}

異なるブロックはそれぞれ事前に定義されたグラデーションを選択している可能性があります。ブロックエディターはデフォルトのグラデーションのプリセットを提供しますが、テーマはこれを上書きし独自のグラデーションを提供できます。

add_theme_support(
	'editor-gradient-presets',
	array(
		array(
			'name'     => esc_attr__( 'Vivid cyan blue to vivid purple', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
			'slug'     => 'vivid-cyan-blue-to-vivid-purple'
		),
		array(
			'name'     => esc_attr__( 'Vivid green cyan to vivid cyan blue', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(0,208,132,1) 0%,rgba(6,147,227,1) 100%)',
			'slug'     =>  'vivid-green-cyan-to-vivid-cyan-blue',
		),
		array(
			'name'     => esc_attr__( 'Light green cyan to vivid green cyan', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)',
			'slug'     => 'light-green-cyan-to-vivid-green-cyan',
		),
		array(
			'name'     => esc_attr__( 'Luminous vivid amber to luminous vivid orange', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%)',
			'slug'     => 'luminous-vivid-amber-to-luminous-vivid-orange',
		),
		array(
			'name'     => esc_attr__( 'Luminous vivid orange to vivid red', 'themeLangDomain' ),
			'gradient' => 'linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%)',
			'slug'     => 'luminous-vivid-orange-to-vivid-red',
		),
	)
);

name は上の例のようなラベルです。ツールチップに表示され、ユーザーに意味のある説明を伝えます。スクリーンリーダーを使用するユーザーには特に重要で、説明が不十分であればグラデーションの認識が困難になります。gradient はブロックの背景色に適用されるグラデーションの CSS 値です。有効なグラデーションタイプの詳細については mozilla のドキュメント を参照してください。slug はグラデーションの一意の識別子です。ブロックエディターで使われる CSS クラスの生成で使用されます。

テーマにはグラデーションに適用するクラスを作成する責任があります。正しく「Vivid cyan blue to vivid purple」を適用するには、テーマは次のクラスを実装する必要があります。

.has-vivid-cyan-blue-to-vivid-purple-gradient-background {
	background: linear-gradient(
		135deg,
		rgba( 6, 147, 227, 1 ) 0%,
		rgb( 155, 81, 224 ) 100%
	);
}

WordPress 5.9 以降、theme.json を持たないテーマが、コアで定義されたグラデーションの値を上書きするには、クラスを提供する代わりに、CSSカスタムプロパティで値を設定しなければなりません。CSSカスタムプロパティは、命名規則 --wp--preset--gradient--<slug> を使用します。詳細については devnote を参照してください。例えば

:root {
	--wp--preset--gradient--vivid-cyan-blue-to-vivid-purple: <new_value>;
	--wp--preset--gradient--light-green-cyan-to-vivid-green-cyan: <new_value>;
}

「段落」ブロックのように、ユーザーはブロックで使用するフォントのサイズを構成できます。ブロックはでフォントサイズのデフォルトセットを提供しますが、テーマはこれを上書きし独自のセットを提供できます。

add_theme_support( 'editor-font-sizes', array(
	array(
		'name' => esc_attr__( 'Small', 'themeLangDomain' ),
		'size' => 12,
		'slug' => 'small'
	),
	array(
		'name' => esc_attr__( 'Regular', 'themeLangDomain' ),
		'size' => 16,
		'slug' => 'regular'
	),
	array(
		'name' => esc_attr__( 'Large', 'themeLangDomain' ),
		'size' => 36,
		'slug' => 'large'
	),
	array(
		'name' => esc_attr__( 'Huge', 'themeLangDomain' ),
		'size' => 50,
		'slug' => 'huge'
	)
) );

フォントサイズはテーマが提供した順番でフォントサイズピッカー上にレンダリングされます。

テーマには正しいフォントサイズスタイルに適用するクラスを作成する責任があります。クラス名は、最初に「has-」、続けてケバブケースを使用したフォントサイズ名、最後に -font-size で作成します。

たとえば標準のフォントサイズであれば、テーマは次のクラスを提供します。

.has-regular-font-size {
	font-size: 16px;
}

注意: スラッグ default と custom は予約済みのため、テーマでは使えません。

WordPress 5.9 以降、theme.json を持たないテーマが、コアで定義されたフォントサイズの値を上書きするには、クラスを提供する代わりに、CSSカスタムプロパティで値を設定しなければなりません。CSSカスタムプロパティは、命名規則 --wp--preset--font-size--<slug> を使用します。詳細については devnote を参照してください。例えば

:root {
	--wp--preset--font-size--small: <new_value>;
	--wp--preset--font-size--large: <new_value>;
}

テーマはカスタムフォントサイズの設定を無効化できます。

add_theme_support( 'disable-custom-font-sizes' );

無効化するとユーザーはブロックエディターで提供されるデフォルトのサイズ、またはテーマサポート設定 editor-font-sizes で提供されたサイズに制限されます。

デフォルトでブロックのユーザーは、カラーパレットを使用してエディターやテーマのデフォルトの色と異なるカスタム色を選択できます。

テーマはこの機能を無効化できます。

add_theme_support( 'disable-custom-colors' );

無効化するとユーザーは、テーマが提供した editor-color-palette、またはテーマが提供していなければエディターのデフォルト色からのみ色を選択できます。

テーマはカスタムグラデーションの設定を無効化できます。

add_theme_support( 'disable-custom-gradients' );

無効化するとユーザーは、ブロックエディターで提供されるデフォルトのグラデーション、またはテーマサポート設定 editor-gradient-presets で提供されたグラデーションに制限されます。

注意: WordPress 6.1以降

テーマは、グループ、カラム、ボタン、ソーシャルアイコンなどのコアブロックにデフォルトの構造スタイルを提供する、生成されたブロックレイアウトスタイルを拒否できます。次のコードを使用して、テーマは独自の構造スタイルを提供することをコミットします。提供せずに、この機能を使用すると、エディターとサイトのフロントエンドの両方でコアブロックが正しく表示されません。

add_theme_support( 'disable-layout-styles' );

blockGap スタイルやブロック間隔をカスタマイズしたいテーマは、グローバル設定とスタイルに関する開発者向けドキュメントを参照してください。

「段落」や「見出し」などいくつかのブロックは行の高さのカスタマイズをサポートします。テーマはこの機能のサポートを有効化できます。

add_theme_support( 'custom-line-height' );

ユーザーはピクセルに加えて、サイズやパディングなどを定義する他の単位を使用できます。利用可能な単位は px、em、rem、vh、vw です。テーマはこの機能のサポートを無効化できます。

add_theme_support( 'custom-units', array() );

テーマはまた利用可能なカスタムユニットを選択できます。

add_theme_support( 'custom-units', 'rem', 'em' );

WordPress には多くの組み込みブロックパターンが付属します。テーマは同梱のパターンをオプトアウトし、独自のセットを提供できます。

remove_theme_support( 'core-block-patterns' );

ブロックエディターはテーマの エディタースタイル をサポートしますが、クラシックエディターとは少し異なって動作します。

クラシックエディターではエディタースタイルは WYSIWYG エディターの iframe に直接、変更なしでロードされていました。しかしブロックエディターは iframe を使用しません。このためブロックエディターではスタイルがエディターのコンテンツだけに適用されるよう、エディタースタイルを選択的に書き換えるか、一部の CSS セレクターを調整して自動的に変換します。またこの動作によりブロックエディターはエディタースタイルでブロックのバリエーションをプレビューできます。

たとえばエディタースタイル内の body { ... } は .editor-styles-wrapper { ... } に書き換えられます。ちなみにこのことはエディターのクラス名を直接 指定すべきでない ことも意味しています。

この動作は少し変わっているため、テーマには add_editor_style に加えて追加のオプトインが必要です。

add_theme_support( 'editor-styles' );

エディタースタイルの多くを変更する必要はありません。ほとんどのテーマは上のコードを追加することでクラシックエディターでもブロックエディターでも同じ結果を得られます。

エディター画面に CSS をエンキューしロードするには add_editor_style 関数を使用してください。クラシックエディターではこの関数のみでエディターにスタイルを追加できました。新しいブロックエディターでは上で説明したようにまず add_theme_support( 'editor-styles'); が必要です。

add_editor_style( 'style-editor.css' );

functions.php ファイルに上の行を追加すると、エディター内にロードされるスタイルシートのキューにスタイルシート style-editor.css が追加されます。

他の Web ページのようにエディターをスタイルできます。次のコードは背景色とフォントの色を青に変更します。

/* `style-editor.css` ファイルに追加する */
body {
	background-color: #d3ebf3;
	color: #00005d;
}

エディターのメインのカラムの幅を変更するには style-editor.css に次の CSS を追加します。

/* メインのカラム幅 */
.wp-block {
	max-width: 720px;
}

/* 「幅広」ブロックの幅 */
.wp-block[data-align="wide"] {
	max-width: 1080px;
}

/* 「全幅」ブロックの幅 */
.wp-block[data-align="full"] {
	max-width: none;
}

テーマと合わせるためにこれらのエディターの幅を使用できます。% や px を含む任意の CSS 幅の単位を使用できます。

スタイルシートでのスタイルの適用 も参照してください。

「埋め込み」ブロックは、iFrame 内に埋め込まれたコンテンツのアスペクト比を反映するため、自動的に埋め込みコンテンツに対してスタイルを適用します。アスペクト比にレスポンシブな形でのブロックスタイルは次のようになります。

<figure class="wp-embed-aspect-16-9 wp-has-aspect-ratio">...</figure>

アスペクト比を保ったままコンテンツをリサイズするには <body> 要素に wp-embed-responsive クラスが必要です。デフォルトでは設定されないため、テーマは responsive-embeds 機能をオプトインする必要があります。

add_theme_support( 'responsive-embeds' );

いくつかのブロックはパディングの制御を持つことができます。この機能は標準で無効のため、テーマはサポートを宣言してオプトインする必要があります。

Some blocks can have padding controls. This is off by default, and requires the theme to opt in by declaring support:

add_theme_support( 'custom-spacing' );

link サポートは WordPress 5.8の一部として安定動作します。デフォルトは false ですが、テーマは theme.json ファイル を通して有効化できます。

{
	"version": 1,
	"settings": {
		"color": {
			"link": true
		}
	}
}

代替として、Gutenberg プラグインが有効な場合は、古いレガシーサポートである add_theme_support( 'experimental-link-color' ) も機能します。このフォールバックは、Gutenberg プラグインのサポートするバージョンが WordPress 5.9 以上になった時点で削除されます。

ユーザーがブロックのリンク色を設定すると、新しいスタイルが追加されます。

.wp-elements-<uuid> a {
	color: <link-color> !important;
}

このとき

• <uuid> は、ランダムな番号です
• <link-color> は、var(--wp--preset--color--slug) (プリセット値が選択された場合)、または、生のカラー値 (カスタム値が選択された場合) です。

このブロックには、クラス .wp-elements-<uuid> が付けられます。

この設定を使用すると、以下のグローバルスタイル設定が有効になります。

• border: color, radius, style, width
• color: link
• spacing: blockGap, margin, padding
• typography: lineHeight
• dimensions: aspectRatio, minHeight
• position: sticky

add_theme_support( 'appearance-tools' );

すべての枠線の設定を有効化します。

add_theme_support( 'border' );

リンク色の設定を有効化します。

add_theme_support( 'link-color' );

ブロックベースのテンプレートパーツにより管理者は、ブロックを使用してサイトの一部を編集できます。この設定はデフォルトではオフで、テーマはサポートを宣言することでオプトインする必要があります。

add_theme_support( 'block-template-parts' );

この機能はブロックベースではないテーマにのみ関連します。ブロックベースのテーマではサイトエディターの一部として、ブロックベースのテンプレートパーツを既にサポートしています。

スタンドアロンのテンプレートパーツエディターでは、エディターは新規テンプレートパーツの作成や、既存テンプレートパーツの削除はできません。これは、テーマが手動でテンプレートパーツをPHPテンプレートに含める必要があるためです。

ブロックベースのテンプレートパーツの詳細については、テーマハンドブックのブロックテンプレートとテンプレートパーツのセクションを参照してください。

原文

最終更新日: 2024年1月27日