ブロックパターンは、あらかじめ定義されたブロックのレイアウトです。ブロックインサーターの「パターン」タブから利用できます。ブロックパターンをコンテンツ内に挿入すると、含まれるブロックのコンテンツや構成を追加、変更できます。
ブロックパターン
register_block_pattern
エディターにはいくつかのコアブロックパターンが付属します。それ以外にテーマやプラグインの作者は register_block_pattern ヘルパー関数を使用して、追加のカスタムブロックパターンを登録できます。
register_block_pattern ヘルパー関数は2つの引数を取ります。
title: 機械が読めるタイトル。命名規約はnamespace/titleproperties: パターンのプロパティを説明する配列
ブロックパターンで利用可能なプロパティを以下に示します。
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
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
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
unregister_block_pattern_category ヘルパー関数を利用すると、以前に登録したたブロックパターンカテゴリをテーマやプラグインから登録解除できます。1つの引数を取ります。
title: 登録解除するブロックパターンカテゴリーの名前
次のコードの例ではカテゴリー名 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' ),
// パターンを「header」領域に割り当て
'blockTypes' => array( 'core/template-part/header' ),
'content' => 'Content of my block pattern',
)
);