エディターでのアセットのエンキュー

このページはエディターにアセット (スクリプトとスタイル) をエンキューする際の、完全なリファレンスガイドとなることを目標としています。したがってここに紹介するアプローチは、推奨されるベストプラクティスです。ただし、WordPress 同様、この情報も進化します。定期的な情報の更新を心がけてください。

WordPress 6.3では、登録されたすべてのブロックが Block API version 3以上であり、かつ、旧来のメタボックスが登録されていなければ、投稿エディターは iframe 化されます。サイトエディターは常に iframe 化されます。このガイドでは、iframe エディターへのアセットのエンキューを想定します。その他の考慮事項については後方互換性のセクションを参照してください。

エディターが iframe 化された理由については、iframe 化 (テンプレート) エディターにおけるブロックを参照してください。

エディターでアセットをエンキューする前に、まず何に対してエンキューしようとしているのかをクリアにする必要があります。

エディターのユーザー生成コンテンツ (ブロック) に、スタイルや JavaScript を追加しようとしていますか ? あるいは、エディターのユーザーインターフェース (UI) コンポーネントを変更したり、エディターの API を操作しようとしていますか ? 後者にはカスタムブロックコントロールの作成から、ブロックバリエーションの登録までが含まれます。

質問への答えによって使用するフックが異なります。またブロックやテーマを作成する場合は、さらに検討しなければならないアプローチがあります。以下の該当するセクションを参照してください。

エディター自身にアセットをエンキューする場合 (逆に言えば、ユーザー生成コンテンツ (ブロック) のエンキューでない場合)、enqueue_block_editor_assets フックと、関連する標準の wp_enqueue_script 関数と wp_enqueue_style 関数を使用します。

例としては、カスタムインスペクタやツールバーコントロールの追加、ブロックスタイルや JavaScript のバリエーションの登録、エディタ ープラグインの登録などが考えられます。

/**
 * エディターアセットのエンキュー
 */
function example_enqueue_editor_assets() {
    wp_enqueue_script(
        'example-editor-scripts',
        plugins_url( 'editor-scripts.js', __FILE__ )
    );
    wp_enqueue_style(
        'example-editor-styles',
        plugins_url( 'editor-styles.css', __FILE__ ) 
    );
}
add_action( 'enqueue_block_editor_assets', 'example_enqueue_editor_assets' );

推奨される方法ではありませんが、後方互換性のため、enqueue_block_editor_assets を使用して、エディターコンテンツのスタイルを設定できることに注意してください。詳細は以下を参照してください。

WordPress 6.3から、enqueue_block_assets PHP アクションによって追加されたすべてのアセットは、iframe エディターでもキューに追加されるようになりました。詳しくは #48286を参照してください。

この方法はユーザー生成コンテンツ (ブロック) にアセットをエンキューする主要な方法で、フックはエディターとサイトフロントエンドの両方で発火します。エディター UI 用のアセットの追加や、エディター API とのやり取りでは使用しないでください。後方互換性については以下を参照してください。

場合によってはエディターにのみアセットを追加し、フロントエンドにはアセットを追加したくない場合もあります。このときは is_admin() をチェックします。

/**
 * コンテンツアセットのエンキュー。ただし、エディター内のみ
 */
function example_enqueue_editor_content_assets() {
    if ( is_admin() ) {
        wp_enqueue_script(
            'example-editor-content-scripts',
            plugins_url( 'constent-scripts.css', __FILE__ )
        );
        wp_enqueue_style(
            'example-editor-content-styles',
            plugins_url( 'constent-styles.css', __FILE__ )
        );
    }
}
add_action( 'enqueue_block_assets', 'example_enqueue_editor_content_assets' );

block_editor_settings_all フックを使用しても、エディターの設定を直接変更できます。実装は少し複雑になりますが、柔軟性は高くなります。enqueue_block_assets がニーズを満たさない場合にのみ使用してください。

以下の例では、すべての段落のデフォルトのテキスト色を green に設定します。

/**
 * カスタムスタイルを追加してエディター設定を変更する
 *
 * @param array  $editor_settings 現在のエディター設定を含む配列
 * @param string $editor_context  エディターのコンテキスト
 *
 * @return array カスタム CSS スタイルの追加で変更されたエディター設定
 */
function example_modify_editor_settings( $editor_settings, $editor_context ) {
    $editor_settings["styles"][] = array(
        "css" => 'p { color: green }'
    );

    return $editor_settings;
}
add_filter( 'block_editor_settings_all', 'example_modify_editor_settings', 10,2 );

このスタイルは iframe エディターの body にインライン化され、プレフィックス .editor-styles-wrapper が付きます。結果のマークアップは次のようになります。

<style>.editor-styles-wrapper p { color: green; }</style>

WordPress 6.3以降では、このエディター設定の変更方法を使用して JavaScript で、動的にスタイルを変更できます。詳細は #52767 を参照してください。

ブロックをビルドする際は block.json が、ブロック自体に必要なすべてのスクリプトとスタイルをエンキューする推奨の方法です。エディター用、フロントエンド用、またはその両方のアセットをエンキューできます。詳細についてはブロックのメタデータを参照してください。

テーマ内でエディター JavaScript をエンキューするには、前述のように enqueue_block_assets または enqueue_block_editor_assets を使用します。エディター固有のスタイルシートは、ほとんど常に add_editor_style() または wp_enqueue_block_style() で追加してください。

wp_enqueue_block_style() 関数を使用すると、エディター内とフロントエンドで、ブロック単位にスタイルシートを読み込めます。theme.json との組み合わせはブロックをスタイリングする最良の方法の1つです。詳細は WordPress Developer Blogの記事 Leveraging theme.json and per-block styles for more performant themes (theme.json とブロック単位のスタイルを活用したパフォーマンスの高いテーマの実現) を参照してください。

一般的なルールとして、WordPress 6.3以上を使用している限り、iframe エディターでアセットをエンキューすると、iframe 化されていないエディターでもエンキューされます。しかし、その逆が常に正しいとは限りません。

今ここで、WordPress 6.3との互換性を維持しながら、6.2以下との後方互換性が必要なプラグインやテーマを構築するとします。このとき enqueue_block_assets は使えません。このフックは6.3より前の iframe エディターのコンテンツにアセットをエンキューしないためです。

代わりに、エンキューされるスタイルシートがセレクタ .editor-styles-wrapper、.wp-block、.wp-block-* のうち少なくとも1つを含むなら、enqueue_block_editor_assetsを使用できます。コンソールに警告メッセージが記録されますが、フックはエディターのコンテンツにスタイルを適用します。

重要な注意として WordPress 6.3では、後方互換性のため、enqueue_block_assets によってエンキューされたアセットは、エディターの iframe の内側と外側の両方に読み込まれます。これによりエンキューするスクリプトライブラリによっては、問題が発生する可能性があります。このアプローチについては、Gutenberg GitHub リポジトリ で議論が行われています。

このガイドで説明した方法により、これまでに報告されていない問題が発生した場合は、GitHub で issue を送信 してください。

原文

最終更新日: 2023年12月22日