パターン

ブロックパターンは、あらかじめ定義されたブロックのレイアウトで、挿入して微調整できます。ブロックインサーターの「パターン」タブから利用できます。ブロックパターンをコンテンツ内に挿入すると、含まれるブロックのコンテンツや構成を追加、変更できます。

目次

• パターン
  • ブロックパターン
    • register_block_pattern
  • ブロックパターンの登録の解除
    • unregister_block_pattern
  • ブロックパターンカテゴリー
    • register_block_pattern_category
    • unregister_block_pattern_category
  • ブロックタイプやパターン変換のコンテキストに応じたブロックパターン
  • セマンティックブロックパターン

エディターにはいくつかのコアブロックパターンが付属します。テーマやプラグインの作者は register_block_pattern ヘルパー関数を使用して、追加のカスタムブロックパターンを登録できます。

register_block_pattern ヘルパー関数は2つの引数を取ります。

• title: 機械が読めるタイトル。命名規約は namespace/title
• properties: パターンのプロパティを説明する配列

ブロックパターンで利用可能なプロパティを以下に示します。

• title (必須): 表示されるパターンのタイトル。
• content (必須): パターンのブロック HTML マークアップ。
• description (オプション): インスペクター内でパターンの記述に使用される非表示のテキスト。オプションだがタイトルで十分にブロックの動作を表せない場合は強く推奨。ユーザーの検索を支援する。
• categories (オプション): ブロックパターンのグループ化に使用される、登録されたパターンカテゴリーの配列。ブロックパターンは複数のカテゴリーに分けて表示できる。ここで使用するには、カテゴリーを個別に登録する必要がある。
• keywords (オプション): 検索の際に役立つ別名またはキーワードの配列。
• viewportWidth (オプション): インサーター内でのパターンのインデント幅を指定する整数。パターンのスケールするプレビュー用。
• blockTypes (オプション): パターンが一緒に使われることを想定するブロックタイプの配列。各値は、ブロックの name で宣言される必要がある。
• postTypes (オプション): このパターンを使用可能な投稿タイプの配列。配列で指定した投稿タイプのいずれかを編集する際にのみこのパターンを使用でき、その他のすべての投稿タイプではまったく使用できない。
• templateTypes (オプション): パターンが意味を持つ、テンプレートタイプの配列。例: パターンが 404 ページ用であれば ‘404’。パターンが単一の投稿用であれば single-post。
• inserter (オプション): デフォルトでは、すべてのパターンはインサーターに表示されます。プログラムでのみ挿入できるようにパターンを非表示にするには、inserter を false に設定します。
• source (オプション): パターンのソースを示す文字列。パターンを登録するプラグインの場合は、文字列 ‘plugin’ を指定します。テーマの場合は文字列 ‘theme’ を指定します。

次のサンプルコードは、ブロックパターン「my-plugin/my-awesome-pattern」を登録します。

register_block_pattern(
	'my-plugin/my-awesome-pattern',
	array(
		'title'       => __( 'Two buttons', 'my-plugin' ),
		'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', 'my-plugin' ),
		'content'     => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">" . esc_html__( 'Button One', 'my-plugin' ) . "</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">" . esc_html__( 'Button Two', 'my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
	)
);

注意:

register_block_pattern() は、init フックにアタッチされたハンドラから呼ぶ必要があります。

function my_plugin_register_my_patterns() {
  register_block_pattern( ... );
}

add_action( 'init', 'my_plugin_register_my_patterns' );

unregister_block_pattern ヘルパー関数を使用すると、テーマやプラグインからブロックパターンの登録を解除できます。1つの引数を取ります。

• title: 登録解除するブロックパターンの名前

次のサンプルコードは、ブロックパターン「my-plugin/my-awesome-pattern」の登録を解除します。

unregister_block_pattern( 'my-plugin/my-awesome-pattern' );

注意:

unregister_block_pattern() は、init フックにアタッチされたハンドラから呼ぶ必要があります。

function my_plugin_unregister_my_patterns() {
  unregister_block_pattern( ... );
}

add_action( 'init', 'my_plugin_unregister_my_patterns' );

ブロックパターンはカテゴリーを使用してグループ分けできます。ブロックエディターにはカスタムブロックパターンでも利用可能な組み込みのカテゴリーが付属します。独自のブロックパターンカテゴリーを登録することもできます。

register_block_pattern_category ヘルパー関数は2つの引数を取ります。

• title: ブロックパターンカテゴリーの機械が読み取り可能なタイトル。
• properties: パターンカテゴリーのプロパティを説明する配列

パターンカテゴリーのプロパティを以下に示します。

• label (必須): 表示されるパターンカテゴリーの名前。

次のサンプルコードは、カテゴリー「hero」を登録します。

register_block_pattern_category(
	'hero',
	array( 'label' => __( 'Hero', 'my-plugin' ) )
);

注意:

register_block_pattern_category() は、init フックにアタッチされたハンドラから呼ぶ必要があります。

パターンがあるカテゴリーに割り当てられていなければ、そのカテゴリーはパターンの下に表示しません。

function my_plugin_register_my_pattern_categories() {
  register_block_pattern_category( ... );
}

add_action( 'init', 'my_plugin_register_my_pattern_categories' );

unregister_block_pattern_category はパターンカテゴリーの登録を解除します。

関数の引数は解除するパターンカテゴリーの名前です。

次のコードの例ではカテゴリー「hero」の登録を解除します。

unregister_block_pattern_category( 'hero' );

注意:

unregister_block_pattern_category() は、init フックにアタッチされたハンドラから呼ぶ必要があります。

function my_plugin_unregister_my_pattern_categories() {
  unregister_block_pattern_category( ... );
}

add_action( 'init', 'my_plugin_unregister_my_pattern_categories' );

1つまたは複数のブロックタイプにブロックパターンをアタッチできます。これにより、そのブロックタイプで使用可能な変換としてブロックパターンが追加されます。

現在、これらの変換は単純なブロック (内部ブロックを持たないブロック) でのみ可能です。パターンが提案されるには、選択されたすべてのブロックがブロックパターンに存在する必要があります。

例:

register_block_pattern(
	'my-plugin/powered-by-wordpress',
	array(
		'title'      => __( 'Powered by WordPress', 'my-plugin' ),
		'blockTypes' => array( 'core/paragraph' ),
		'content'    => '<!-- wp:paragraph {"backgroundColor":"black","textColor":"white"} -->
		<p class="has-white-color has-black-background-color has-text-color has-background">Powered by WordPress</p>
		<!-- /wp:paragraph -->',
	)
);

上のコードは、ブロックパターン my-plugin/powered-by-wordpress を登録し、段落ブロックの「変換」メニューにパターンを表示します。変換結果は、段落の既存のコンテンツを維持したまま、他の属性 (この場合は背景とテキストの色) を適用します。

上で述べたように、単純なブロックに対するパターン変換は、複数のブロックを選択し、かつ、これらのブロックに対応するコンテキストパターンがある場合にも機能します。2つのブロックタイプがアタッチされたパターンの例を見ます。

register_block_pattern(
	'my-plugin/powered-by-wordpress',
	array(
		'title'      => __( 'Powered by WordPress', 'my-plugin' ),
		'blockTypes' => array( 'core/paragraph', 'core/heading' ),
		'content'    => '<!-- wp:group -->
						<div class="wp-block-group">
						<!-- wp:heading {"fontSize":"large"} -->
						<h2 class="has-large-font-size"><span style="color:#ba0c49" class="has-inline-color">Hi everyone</span></h2>
						<!-- /wp:heading -->
						<!-- wp:paragraph {"backgroundColor":"black","textColor":"white"} -->
						<p class="has-white-color has-black-background-color has-text-color has-background">Powered by WordPress</p>
						<!-- /wp:paragraph -->
						</div><!-- /wp:group -->',
	)
);

上の例では、2つのブロックタイプのうち1つ、段落または見出しブロックのどちらかを選択すると、選択したブロックをその内容を使って変換し、パターンから残りのブロックを追加して、このパターンが提案されます。一方、1つの段落と1つの見出しブロックを複数選択すると、両方のブロックが変換されます。

ブロックは、このコンテキストに応じたブロックパターンを他の場所でも使用できます。例えば、新しいクエリーループブロックを挿入すると、ブロックにアタッチされたすべてのパターンのリストが提供されます。

ブロックテーマでは、ブロックパターンを「ヘッダー」パターン、「フッター」パターン (テンプレートパーツ領域) としてもマークできます。これを「セマンティックブロックパターン」と呼びます。これらのパターンは、ヘッダーテンプレートパーツやフッターテンプレートパーツの挿入、置換の際に表示されます。

例:

<?php
register_block_pattern(
	'my-plugin/my-header',
	array(
		'title'      => __( 'My Header', 'my-plugin' ),
		'categories' => array( 'header' ),
		// Assigning the pattern the "header" area.
		'blockTypes' => array( 'core/template-part/header' ),
		'content'    => 'Content of my block pattern',
	)
);

最終更新日: 2023年6月25日