パターン（Patterns）

ブロックパターン

register_block_pattern

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

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

– title: namespace/title の命名規則に従った機械可読のタイトル。

– properties: パターンのプロパティを説明する配列。

ブロックパターンで利用可能なプロパティは次のとおりです:

• title (必須): パターンの人間可読のタイトル。
• content (必須): パターンのブロックHTMLマークアップ。
• description (オプション): インサーターでパターンを説明するために使用される視覚的に隠されたテキスト。説明はオプションですが、タイトルがパターンの機能を完全に説明していない場合は強く推奨されます。説明は、ユーザーが検索中にパターンを発見するのに役立ちます。
• categories (オプション): ブロックパターンをグループ化するために使用される登録済みパターンカテゴリの配列。ブロックパターンは複数のカテゴリに表示できます。カテゴリは、ここで使用するために別途登録する必要があります。
• keywords (オプション): ユーザーが検索中にパターンを発見するのを助けるエイリアスまたはキーワードの配列。
• viewportWidth (オプション): インサーターでパターンのスケールプレビューを許可するために、パターンの意図された幅を指定する整数。
• blockTypes (オプション): パターンが使用されることを意図したブロックタイプの配列。各値は宣言されたブロックの name である必要があります。
• postTypes (オプション): パターンが使用されることを制限されている投稿タイプの配列。パターンは、配列に渡された投稿タイプの1つを編集しているときのみ利用可能です。他のすべての投稿タイプでは、パターンはまったく利用できません。
• 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つずつ選択した場合、両方のブロックが変換されます。

ブロックは、他の場所でもこれらの文脈ブロックパターンを使用できます。たとえば、新しいクエリループブロックを挿入する際、ユーザーにはそのブロックに関連付けられたすべてのパターンのリストが提供されます。

セマンティックブロックパターン

ブロックテーマでは、ブロックパターンを「ヘッダー」または「フッター」パターン（テンプレートパートエリア）としてマークすることもできます。これらを「セマンティックブロックパターン」と呼びます。これらのパターンは、ヘッダーまたはフッターのテンプレートパートを挿入または置き換える際にユーザーに表示されます。

例:

<?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',
   )
);