関数

register_block_script_handle() の仕組みと登録方法を解説

2025-02-19更新日: 2025-02-19

register_block_script_handle() は、WordPress のブロックエディタで使用するスクリプトを自動的に登録する関数です。

ブロックのメタデータからスクリプトのパスや依存関係、バージョン情報などを取得し、wp_register_script() を用いて登録します。

既に登録済みの場合はそのハンドルを返し、重複登録を防ぎます。

また、翻訳設定にも対応しているため、開発環境で安心して利用できる仕組みとなっています。

目次から探す

メタデータの処理
- フィールド値の取得と検証
- 配列データのインデックス処理
ファイルパスの正規化とアセット取得
スクリプトハンドルの生成
- 一意なハンドルの作成
- 命名規則と remove_block_asset_path_prefix() の適用
スクリプト登録処理
翻訳設定の適用
- wp_set_script_translations() の実装
- スクリプト依存関係への翻訳設定適用
まとめ

メタデータの処理

WordPress のブロック固有の情報は、配列として格納されることが多く、まずは必要な情報を取得して正しい値であるかを確認する必要があります。

以下では、メタデータからスクリプトに関連するフィールド値を取得し、その整合性を検証する方法を説明します。

フィールド値の取得と検証

メタデータ内に設定されたキー(例：viewScript や editorScript)からスクリプトのパスまたはハンドルを取得します。

まず、対象のキーが存在するかどうかを empty()関数などで確認し、値が存在しない場合は早期に処理を終了させます。

また、取得した値が配列の場合もあるため、そのまま使用できるかを判断します。

以下のサンプルコードは、メタデータからフィールド値を取得して検証する方法を示しています。

// サンプル: メタデータからフィールド値を取得して検証する例
if ( empty( $metadata[ $field_name ] ) ) {
    return false; // 指定されたキーが存在しない場合は false を返す
}
$script_value = $metadata[ $field_name ];
// フィールド値が配列の場合、指定されたインデックスから値を抽出
if ( is_array( $script_value ) ) {
    if ( empty( $script_value[ $index ] ) ) {
        return false; // 指定したインデックスが存在しない場合は false を返す
    }
    $script_value = $script_value[ $index ];
}

// フィールド値の検証に成功すると、正確なスクリプトパスまたはハンドルが取得される

配列データのインデックス処理

スクリプト情報が配列形式で格納される場合、特定のインデックスを指定して値を処理する必要があります。

複数のスクリプトが一括で設定されているときに、どのスクリプトを対象とするかを決定するためにインデックスが利用され、既定値は一般に 0 が使われることが多いです。

各配列要素ごとに値が存在するかを確認し、存在しなければエラーとして処理を中断する仕組みが採用されます。

// サンプル: 配列データ内の特定インデックスを指定してスクリプト情報を取得する例
$script_values = $metadata[ $field_name ];
if ( is_array( $script_values ) ) {
    // 指定のインデックスが配列内に存在するかをチェック
    if ( ! isset( $script_values[ $index ] ) ) {
        return false; // 存在しないインデックスの場合は false を返す
    }
    $selected_script = $script_values[ $index ];
}

// 配列内の特定インデックスから正確なスクリプト情報が取得される

ファイルパスの正規化とアセット取得

スクリプトのファイルパスは、サーバー内の絶対パスや相対パスとして格納されることが多いため、正しいパスに変換する必要があります。

ここでは、正規化手法を用いてパスを調整し、アセットファイルが存在するかを確認し、正確な URL を取得する手順を説明します。

ファイルパスの正規化手法

ファイルパスの正規化には、PHP 標準の realpath()関数と WordPress の wp_normalize_path()関数を組み合わせて使用します。

realpath() は実際のファイルシステム上のパスを返すため、相対パスやシンボリックリンクなどが含まれている場合にも正しい絶対パスを取得することが可能です。

その後、wp_normalize_path() により OS に依存しない形式へ変換します。

// サンプル: ファイルパスの正規化処理例
$file_path = '/var/www/html/wp-content/plugins/my-plugin/build/script.js';
$absolute_path = realpath( $file_path );
$normalized_path = wp_normalize_path( $absolute_path );

// $normalized_path には 'wp-content/plugins/my-plugin/build/script.js' の正しいパスが格納される

パスプレフィックスの除去

スクリプトのファイルパスには、ブロック固有のパスプレフィックスが含まれている場合があります。

このプレフィックスは、関数 remove_block_asset_path_prefix() を利用して除去することで、正確な相対パスを取得するのに役立ちます。

これにより、アセット取得時のパス不整合が防止され、後続の処理がスムーズに進む仕組みです。

// サンプル: パスプレフィックス除去処理例
$raw_script_path = $metadata[ $field_name ];
$script_path = remove_block_asset_path_prefix( $raw_script_path );

// $script_path にはパスプレフィックスが除去された正確なファイルパスが設定される

アセットファイルの存在確認

ファイルパスが正規化され、不要なプレフィックスが除去された後、実際に該当のアセットファイルが存在するかチェックします。

存在するファイルでなければ、以降の処理は行わずエラーが返されます。

ここでは、正規化したパスと実ファイルの存在確認の手順を用いて正確な情報を取得します。

realpath と wp_normalize_path の利用

realpath() と wp_normalize_path() を併用することで、サーバー内に存在するファイルの正確なパスを取得し、ファイルが存在するかどうかを検証します。

// サンプル: 実際のファイル存在確認例
$absolute_path = realpath( $path . '/' . $script_path );
if ( ! $absolute_path ) {
    return false; // ファイルが存在しない場合は false を返す
}
$normalized_path = wp_normalize_path( $absolute_path );

// $normalized_path で存在するファイルの正確なパスが取得される

get_block_asset_url() による URL 取得

ファイルパスが正規化された後、WordPress の get_block_asset_url()関数を利用することで、スクリプトに対応する正確な URL を生成します。

この URL は、プラグインディレクトリやテーマディレクトリに基づいて自動的に生成されるため、HTTP 経由でスクリプトを正しく読み込むことが可能となります。

// サンプル: 正規化されたパスからアセット URL を生成する例
$script_url = get_block_asset_url( $normalized_path );
echo $script_url; // 例: 'http://example.com/wp-content/plugins/my-plugin/build/script.js'

// 出力例: 'http://example.com/wp-content/plugins/my-plugin/build/script.js'

スクリプトハンドルの生成

スクリプトハンドルは、WordPress のスクリプト登録において一意に識別するための重要な要素です。

ここでは、ユニークなハンドルを作成し、適切な命名規約に基づいて整理する方法を説明します。

一意なハンドルの作成

スクリプトハンドルは、通常、ブロック名やフィールド名、インデックスなどを組み合わせることで一意な値を生成します。

この一意性を確保するために、関数 generate_block_asset_handle() などが利用され、同名のスクリプトが同一ハンドルによって重複登録されることを防ぎます。

// サンプル: 一意なスクリプトハンドルの作成例
$script_handle = generate_block_asset_handle( $metadata['name'], $field_name, $index );
echo $script_handle; // 例: 'my-block-script-handle'

// 出力例: 'my-block-script-handle'

命名規則と remove_block_asset_path_prefix() の適用

スクリプトハンドルを生成する際、命名規則に従って接頭辞や特定のパターンを調整する必要があります。

特に、ファイルパスから不要なプレフィックスを除去するために remove_block_asset_path_prefix() を活用する点がポイントです。

これにより、ハンドル名が整理され、プラグインやテーマ間での衝突を防止できます。

// サンプル: プレフィックスを除去した上でハンドルを生成する例
$raw_path = $metadata[ $field_name ];
$clean_path = remove_block_asset_path_prefix( $raw_path );
$script_handle = generate_block_asset_handle( $metadata['name'], $clean_path, $index );

// 出力例: 整理された一意のスクリプトハンドルが取得される

スクリプト登録処理

取得したスクリプト情報と一意なハンドルをもとに、WordPress の wp_register_script()関数を利用して実際にスクリプトを登録します。

登録時には依存関係やバージョン情報などのパラメータを正しく設定することが重要です。

wp_register_script() の呼び出し

スクリプトの登録は、先に生成されたハンドルと URL、依存関係、バージョン情報を引数として wp_register_script() を呼び出すことで実現します。

成功するとスクリプトはキューに登録され、以降の処理で正しく読み込まれるようになります。

// サンプル: スクリプト登録処理の例
$register_success = wp_register_script( $script_handle, $script_uri, $dependencies, $script_version, $args );
if ( ! $register_success ) {
    return false; // 登録に失敗した場合は false を返す
}
echo $script_handle; // 登録に成功するとハンドルを返す

// 出力例: 'my-block-script-handle'

依存関係とバージョン情報の管理

スクリプト登録時には、依存する他のスクリプトやライブラリ、バージョン情報を正しく設定する必要があります。

これにより、必要なリソースが適切な順序で読み込まれ、互換性も保たれます。

例えば、翻訳対応のためには wp-i18n に依存する場合などが考えられます。

// サンプル: 依存関係とバージョン情報の設定例
$dependencies = isset( $script_asset['dependencies'] ) ? $script_asset['dependencies'] : array();
$script_version = isset( $script_asset['version'] ) ? $script_asset['version'] : $metadata['version'];
$args = array();
// ロード戦略などの追加パラメータ設定例
if ( 'viewScript' === $field_name && $script_uri ) {
    $args['strategy'] = 'defer';
}

// $dependencies には依存するスクリプトが、$script_version には適用されるバージョンが格納される

登録済みチェックの仕組み

スクリプトを再登録するのを防ぐために、登録済みかどうかを事前に確認する仕組みが用意されています。

このチェックにより、重複登録を防ぎ、パフォーマンスの低下やエラーを防止できます。

wp_script_is() による確認

WordPress の wp_script_is() を利用して、すでに指定されたハンドルが登録済みか確認します。

登録済みの場合はそのハンドルを用いて以降の処理を行い、重複して登録する必要がないように制御されます。

// サンプル: 登録済みの確認例
if ( wp_script_is( $script_handle, 'registered' ) ) {
    // すでに登録されている場合、再登録せずにハンドルを返す
    return $script_handle;
}

// 出力例: 既存のハンドル 'my-block-script-handle' をそのまま利用

翻訳設定の適用

WordPress の国際化機能を活用するため、登録されたスクリプトに対して翻訳設定を適用することが可能です。

スクリプトが wp-i18n に依存している場合、翻訳済み文字列の設定によりユーザー向けのローカライズが行われます。

wp_set_script_translations() の実装

スクリプトの翻訳設定は、wp_set_script_translations()関数を用いて実装されます。

この関数は、登録されたスクリプトに対して指定のテキストドメインの翻訳済み文字列を読み込み、適用する役割を果たします。

登録前にスクリプトが正しく登録されていることを確認してから実行します。

// サンプル: スクリプトの翻訳設定を適用する例
$script_handle = 'my-block-script';
$textdomain = 'my-plugin'; // テキストドメインの指定
if ( wp_script_is( $script_handle, 'registered' ) ) {
    wp_set_script_translations( $script_handle, $textdomain );
}

// 出力例: 翻訳設定が適用され、ユーザーの言語環境に合わせた文字列が読み込まれる

スクリプト依存関係への翻訳設定適用

スクリプトが依存関係として wp-i18n を含む場合、翻訳設定は依存関係全体に対して適用されることが望まれます。

これにより、翻訳が必要なコンテキストにおいて、正しくローカライズされたメッセージが出力される仕組みになります。

処理の流れとしては、まず依存関係を確認し、翻訳機能が有効な環境であるか検証してから翻訳設定を呼び出します。

// サンプル: 依存関係に基づき翻訳設定を適用する例
if ( in_array( 'wp-i18n', $dependencies, true ) ) {
    wp_set_script_translations( $script_handle, $textdomain );
}

// 出力例: 'wp-i18n' に依存するスクリプトに翻訳設定が正常に適用される

まとめ

本記事では、register_block_script_handle()関数の動作をメタデータの解析からスクリプトの登録、翻訳設定の適用まで、各ステップごとにサンプルコードを交えて解説しました。

メタデータからの値取得と検証、ファイルパスの正規化やアセットURLの生成、さらに一意なハンドルの作成や依存関係管理の方法が理解できる内容となっています。