register_block_type() 関数を利用したWordPressブロックタイプの登録方法について解説

register_block_type()関数を利用することで、WordPressブロックエディタ用のブロックを簡単に登録できます。

ブロック名やエディタ用・フロントエンド用のスクリプト、スタイル、カスタム属性などを配列で設定し、柔軟なブロック制御が可能です。

また、block.jsonを用いた自動登録方法もあり、ファイル配置やパス指定に注意することで、スムーズな実装が実現できます。

register_block_type()関数の基本理解

関数の役割と動作の概要

WordPressのブロックエディタで新たなブロックを登録するために、register_block_type()関数は中心的な役割を果たします。

この関数は、ブロックの名前(名前空間付きの文字列)と、ブロックの動作・外観に関する各種設定情報を受け取ります。

設定情報には、エディタ用やフロントエンド用のスクリプト、スタイル、カスタム属性、動的レンダリング処理用のコールバック関数などが含まれ、これらをまとめることでブロックの挙動全体を決定します。

たとえば、ブロックエディタ上で編集・操作するための専用スクリプトや、公開ページでの表示用スタイルがこの設定情報によって登録されます。

以下に簡単な例を示します。

// 基本的なブロックの登録例
register_block_type( 'my-plugin/sample-block', array(
    'editor_script'   => 'my-plugin-editor-script',  // エディタ用のJavaScriptハンドル
    'editor_style'    => 'my-plugin-editor-style',   // エディタ用のCSSハンドル
    'script'          => 'my-plugin-frontend-script',// フロントエンド用のJavaScriptハンドル
    'style'           => 'my-plugin-frontend-style', // フロントエンド用のCSSハンドル
) );

// ブロックエディタに「my-plugin/sample-block」が表示され、各種スクリプト・スタイルが適用される例

主な引数と設定項目

register_block_type()関数は、主に以下の引数を用いてブロックの設定を行います。

• ブロック名

名前空間付きの文字列(例: my-plugin/sample-block)で、ブロックの識別に使用されます。

• オプション配列

ブロックの特性や動作を指定する連想配列です。

主な設定項目には、以下のようなものがあります。

• editor_script: エディタ側で読み込むJavaScriptのハンドル
• editor_style: エディタ側で読み込むCSSのハンドル
• script: フロントエンド用のJavaScriptハンドル
• style: フロントエンド用のCSSハンドル
• attributes: ブロック独自の属性設定
• render_callback: PHPで動的にHTMLを生成するためのコールバック関数

これらの設定項目を組み合わせることで、柔軟にブロックの挙動や表示内容を制御することができます。

block.jsonを利用した自動登録

block.jsonの役割と設置場所

WordPressでは、ブロックの詳細なメタデータや設定情報を記述したblock.jsonを利用することで、コード内の設定を簡略化し、構成管理が容易になります。

block.jsonファイルには、ブロック名、説明、カテゴリー、アイコン、スクリプトやスタイルのハンドル、属性設定などが記述されます。

このファイルは、ブロックごとに専用のディレクトリ内に配置する必要があります。

推奨ディレクトリ構造

プラグインの場合、以下のようなディレクトリ構造で配置することが推奨されます。

my-plugin
├── build
└── sample-block
    ├── block.json
    ├── editor.js
    └── style.css

この構造により、ブロックに関連するファイルがひとまとまりになり、管理やデバッグがしやすくなります。

正しいファイル命名規則

ブロックの自動登録機能を利用するためには、ファイル名は必ずblock.jsonとする必要があります。

大文字小文字の違いやスペース、その他の修飾があると、WordPressが正しく認識できず、ブロックが登録されません。

また、ディレクトリパスの指定時、必ずこのファイルが存在するディレクトリを指定するよう注意してください。

block.jsonと個別設定の統合方法

block.jsonを利用すると、ブロックに必要な基本設定はファイル内で一元管理できます。

一方で、特定のケースで個別に上書きしたい設定がある場合、register_block_type()関数の第二引数に配列として個別設定を渡すこともできます。

たとえば、block.jsonで定義されたエディタ用スクリプトの設定を、プラグイン内の条件によって変更する場合、以下のように記述することが可能です。

// block.jsonに定義された内容に対して個別設定を上書きする例
register_block_type( plugin_dir_path( __FILE__ ) . 'build/sample-block', array(
    'editor_script' => 'custom-editor-script', // block.jsonの設定を上書き
    'attributes'    => array(
        'customText' => array(
            'type'    => 'string',
            'default' => '初期値テキスト',
        ),
    ),
) );

// この設定により、エディタ用のスクリプトが「custom-editor-script」に上書きされ、カスタム属性「customText」も追加される

エディタ・フロントエンド用スクリプト＆スタイルの設定

エディタ側の設定

エディタ用スクリプトの指定方法

ブロックエディタでブロックの挙動を向上させるため、エディタ用スクリプトの登録は重要です。

editor_scriptプロパティに、既に登録済みのJavaScriptハンドルを指定します。

以下はエディタ用スクリプトを指定する例です。

// エディタ用スクリプトをブロックに関連付ける例
register_block_type( 'my-plugin/sample-block', array(
    'editor_script' => 'my-plugin-editor-script', // 登録済みのスクリプトハンドル
) );

// ブロックエディタで「my-plugin/sample-block」が、指定したエディタ用スクリプトで動作する

エディタ用スタイルの指定方法

エディタ内でブロックの見た目を整えるため、editor_styleプロパティで専用のCSSを指定します。

この設定により、エディタ上での表示がフロントエンドとは異なったデザインとなり、編集しやすくなります。

// エディタ専用のCSSを設定する例
register_block_type( 'my-plugin/sample-block', array(
    'editor_style' => 'my-plugin-editor-style', // 登録済みのスタイルハンドル
) );

// エディタ上でブロックがカスタムスタイルを適用して表示される

フロントエンド側の設定

フロントエンド用スクリプトの指定方法

ユーザーが閲覧するウェブサイト上でブロックの動作を実現するため、フロントエンド用スクリプトはscriptプロパティを使用して指定します。

このスクリプトはページロード時に読み込まれ、インタラクティブな機能(例えばアニメーションや動的要素の制御)を提供します。

// フロントエンド用スクリプトを設定する例
register_block_type( 'my-plugin/sample-block', array(
    'script' => 'my-plugin-frontend-script', // 登録済みのスクリプトハンドル
) );

// ページ上でブロックが動的に動作し、ユーザーのインタラクションに反応する

フロントエンド用スタイルの指定方法

フロントエンドに表示されるブロックの見た目は、styleプロパティで読み込むCSSによって定義されます。

エディタ用スタイルと分離して管理することにより、公開ページでのデザインを柔軟に調整できます。

// フロントエンド用のCSSを設定する例
register_block_type( 'my-plugin/sample-block', array(
    'style' => 'my-plugin-frontend-style', // 登録済みのスタイルハンドル
) );

// 公開ページでブロックが指定したスタイルで適切に表示される

ブロック属性の定義と利用

基本属性の設定

属性の型とデフォルト値の指定

ブロックごとに固有のデータや表示内容を管理するため、属性を定義します。

各属性は、typeプロパティによって型(例えばstring、number、booleanなど)が指定され、defaultプロパティで初期値を設定できます。

以下に、基本的な属性定義の例を示します。

// 基本属性を定義する例
register_block_type( 'my-plugin/sample-block', array(
    'attributes' => array(
        'textContent' => array(
            'type'    => 'string',
            'default' => '初期テキスト', // 初期表示されるテキスト
        ),
        'fontSize' => array(
            'type'    => 'number',
            'default' => 16, // 初期フォントサイズ(px)
        ),
    ),
) );

// ブロックを追加した際、textContentは「初期テキスト」、fontSizeは16が自動的に使用される

カスタム属性の設定時の注意点

カスタム属性を設定する場合、以下の点に注意してください。

• 属性の型を正確に指定することで、ブロックエディタでの検証と自動補完が有効になります。
• 格納するデータが複雑な場合、オブジェクトや配列の構造を適切に設計する必要があります。
• デフォルト値を設定しておくと、ユーザーが値を明示的に変更しなかった場合でも、意図した挙動が維持されます。
• 場合によっては、動的な設定のためにレンダリングコールバックと連携させる必要があることもあります。

動的レンダリング処理の実装

レンダリングコールバック関数の役割

動的なコンテンツ生成が必要なブロックの場合、render_callbackプロパティに指定したPHP関数が呼び出されます。

この関数は、ブロックが表示される際に実行され、ブロックの属性情報を元に動的にHTMLを出力する役割を果たします。

たとえば、最新の投稿リストや動的な内容を生成する際に利用されます。

PHPによる動的HTML生成の実装方法

レンダリングコールバック関数内では、ブロックの属性を利用してHTMLを組み立てます。

以下は、シンプルな動的HTML生成の例です。

// PHPのレンダリングコールバック関数の例
function sample_block_render_callback( $attributes, $content ) {
    // attributesからテキスト内容を取得、存在しない場合はデフォルト値を設定
    $text = isset( $attributes['textContent'] ) ? esc_html( $attributes['textContent'] ) : 'デフォルトテキスト';
    // HTMLを返す。必要に応じて、追加の属性やクラスを設定可能
    return '<div class="sample-block">' . $text . '</div>';
}
// レンダリングコールバックを登録する例
register_block_type( 'my-plugin/sample-block', array(
    'render_callback' => 'sample_block_render_callback',
) );

<!-- 表示例 -->
<div class="sample-block">初期テキスト</div>

デバッグと設定ミスへの対処

エラーメッセージの確認方法

ブロック登録が思った通りに動作しない場合、まずはエラーメッセージの確認が重要です。

WordPressのデバッグモードを有効にすることで、詳細なエラーメッセージがログに記録され、問題の箇所を特定しやすくなります。

例えば、以下の設定をwp-config.phpに追加すると、エラーログが有効になります。

// wp-config.phpのデバッグ設定例
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

// エラーが発生した場合、wp-content/debug.logに詳細なエラーメッセージが記録される

WP_Block_Type_Registryの活用方法

ブロックが正しく登録されているかを確認するために、グローバルなブロックレジストリであるWP_Block_Type_Registryを利用できます。

このクラスを使用して、特定のブロックの情報を取得することで、登録の成否や設定内容をチェックすることが可能です。

// WP_Block_Type_Registryを利用してブロック情報を確認する例
$block_type = WP_Block_Type_Registry::get_instance()->get_registered( 'my-plugin/sample-block' );
if ( ! $block_type ) {
    error_log( 'ブロック登録に問題が発生している可能性があります。' );
}

// ブロック情報が正しく登録されていない場合、エラーログに「ブロック登録に問題が発生している可能性があります。」と記録される

よくある設定ミスとその対応策

以下の点に注意することで、よくある設定ミスを防ぐことができます。

• block.jsonが正しいディレクトリに存在し、ファイル名が正しく指定されているか確認する
• 登録時に指定したディレクトリパスが正しいこと、特に相対パスの場合にテーマやプラグインのルートを基準にしているか確認する
• 各スクリプトやスタイルのハンドルが正しく登録され、依存関係が満たされているかをチェックする
• レンダリングコールバック関数内で、属性の値が正しく取得できるか、エスケープ処理が適切に行われているかを確認する

これらのチェックポイントを意識することで、ブロック登録や動作におけるトラブルシューティングがスムーズに進められることが期待できます。

まとめ

この記事では、WordPressのブロックエディタ向けブロック登録の基本から、block.jsonを利用した自動登録、エディタ・フロントエンドそれぞれのスクリプトやスタイルの設定方法を学べます。

また、ブロック属性の定義や動的レンダリング処理、デバッグ方法、設定ミスへの対策についても具体的なサンプルコードを交えて説明しています。

これにより、ブロック開発の全体的な流れとポイントが理解できる内容となっています。