ブロックの登録

WordPress のブロックは通常プラグインにバンドルされ、block.json メタデータを使用してサーバーサイドとクライアントサイドの両方で登録されます。

ブロックはクライアントサイドのみに登録できますが、ベストプラクティスとして、サーバーとクライアントの両方で登録することを強く推奨します。この2つの登録により、動的レンダリング、ブロックサポート、ブロックフック、スタイルバリエーションなどのサーバーサイドの機能が可能となるため、非常に重要です。サーバーサイドに登録がなければ、これらの機能は正しく動作しません。

例えば、あるブロックを theme.json を介してスタイルを設定するには、そのブロックをサーバに登録する必要があります。そうしなければ、ブロックは theme.json で割り当てられたスタイルを認識、適用できません。

次の図は、ブロックの登録プロセスの詳細を示します。

PHP によるブロックの登録 (サーバーサイド)

サーバー上でのブロック登録は通常、プラグインのメイン PHP ファイルの、init フックで呼ばれる register_block_type() 関数で行われます。この関数は block.json ファイルに保存されたメタデータを読み込むことで、ブロックタイプの登録を簡素化します。

この関数はブロックタイプの登録のために設計されており、このコンテキストでは主に2つのパラメータを使用しますが、より多くのバリエーションがあります。

$block_type (string): block.json ファイルがあるディレクトリへのパスか、名前が異なる場合はメタデータファイルの完全なパスです。このパラメータは WordPress にブロックの構成の場所を伝えます。
$args (array): オプションのパラメータで、ブロックタイプの追加の引数を指定できます。デフォルトでは空の配列ですが、様々なオプションを指定でき、その1つが $render_callback です。このコールバックはフロントエンドでのブロックのレンダーに使用され、 block.json の render プロパティの代替となります。

開発プロセスにおいて、block.json ファイルは通常、コードのコンパイルの一環として src (ソース) ディレクトリから build (ビルド) ディレクトリに移動されます。このため、ブロックを登録する際には、 $block_type パスが build ディレクトリ内の block.json ファイルを指していることを確認してください。

register_block_type() 関数は成功すると登録したブロックタイプ (WP_Block_Type) を返し、失敗すると false を返します。以下は render_callback を使用した簡単な例です。

register_block_type(
	__DIR__ . '/build',
	array(
		'render_callback' => 'render_block_core_notice',
	)
);

以下は init フックを含む、より完全な例です。

function minimal_block_ca6eda___register_block() {
	register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'minimal_block_ca6eda___register_block' );

完全なブロックの例の中の上のコードを参照してください。

JavaScript によるブロックの登録（クライアントサイド）

ブロックがすでにサーバーに登録されている場合は、@wordpress/blocks パッケージの registerBlockType メソッドを使用して、JavaScript でクライアントサイドの設定を登録するだけで済みます。一点、ブロックの block.json ファイルで定義されたブロック名と同じ名前を使用することに注意してください。以下はその例です。

import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'my-plugin/notice', {
	edit: Edit,
	// ... 他のクライアントサイドの設定
} );

一般には、メタデータファイルを使用する利点セクションで説明した特徴により、PHP を使用したサーバー上でのブロックの登録が推奨ですが、クライアントサイドのみでブロックを登録することもできます。registerBlockType メソッドを使用すると、メタデータを使用してブロックタイプを登録できます。

関数は2つの引数を取ります。

$blockNameOrMetadata (string|Object): ブロックタイプ名の文字列か、ブロックのメタデータを含むオブジェクト。メタデータは通常 block.json ファイルから読み込まれます。
$settings (Object): ブロックのクライアントサイドの設定を含むオブジェクト。

wp-scripts などのビルドプロセスを使用する場合には、block.json の内容 (またはその他の .json ファイルの内容) を直接 JavaScript ファイル内にインポートできます。

2番目のパラメータとして渡される settings オブジェクトには多くのプロパティがありますが、最も重要なのは以下の2つです。

edit: ブロックのエディターで使用される React コンポーネント。
save: データベースに保存される静的な HTML マークアップを返す関数。

registerBlockType() 関数は成功した場合に登録したブロックタイプ (WPBlock)、失敗した場合に undefined を返します。以下に例を示します。

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';
import metadata from './block.json';

const Edit = () => <p { ...useBlockProps() }>Hello World - Block Editor</p>;
const save = () => <p { ...useBlockProps.save() }>Hello World - Frontend</p>;

registerBlockType( metadata.name, {
	edit: Edit,
	save,
} );

完全なブロックの例の中の上のコードを参照してください。