ハウツーガイド - エディタでのアセットのエンキュー（Enqueueing assets in the Editor）

エディター対エディターコンテンツ
アセットのキューイングシナリオ
後方互換性と既知の問題

エディター対エディターコンテンツ

アセットをエディターにキューイングする前に、まずターゲットにしようとしているものを特定する必要があります。

エディター内のユーザー生成コンテンツ（ブロック）にスタイリングやJavaScriptを追加したいですか？それとも、エディターのユーザーインターフェース（UI）コンポーネントを変更したり、エディターAPIと対話したりしたいですか？これには、カスタムブロックコントロールの作成からブロックのバリエーションの登録まで、さまざまなことが含まれます。

これらの質問への回答に応じて使用する異なるフックがあり、ブロックやテーマを構築している場合は、考慮すべき追加のアプローチがあります。以下の指定されたセクションを参照してください。

アセットのキューイングシナリオ

エディターのスクリプトとスタイル

エディター自体（すなわち、ユーザー生成コンテンツではない）にアセットをキューイングする必要がある場合は、標準の wp_enqueue_script および wp_enqueue_style 関数と組み合わせて、 enqueue_block_editor_assets フックを使用する必要があります。

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

/**
 * Enqueue Editor assets.
 */
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() チェックを使用することで実現できます。

/**
 * Enqueue content assets but only in the Editor.
 */
function example_enqueue_editor_content_assets() {
   if ( is_admin() ) {
   wp_enqueue_script(
   'example-editor-content-scripts',
   plugins_url( 'content-scripts.js', __FILE__ )
   );
   wp_enqueue_style(
   'example-editor-content-styles',
   plugins_url( 'content-styles.css', __FILE__ )
   );
   }
}
add_action( 'enqueue_block_assets', 'example_enqueue_editor_content_assets' );

また、フック block_editor_settings_all を使用してエディター設定を直接変更することもできます。この方法は実装が少し複雑ですが、より大きな柔軟性を提供します。enqueue_block_assets がニーズを満たさない場合にのみ使用すべきです。

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

/**
 * Modify the Editor settings by adding custom styles.
 *
 * @param array  $editor_settings An array containing the current Editor settings.
 * @param string $editor_context  The context of the editor.
 *
 * @return array Modified editor settings with the added custom CSS style.
 */
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 はブロック自体に特に必要なすべてのスクリプトとスタイルをキューイングするための推奨方法です。エディター、フロントエンド、またはその両方のためにアセットをキューイングできます。詳細については Block Metadata 記事を参照してください。

テーマのスクリプトとスタイル

テーマ内でエディターJavaScriptをキューイングする必要がある場合は、上記のように enqueue_block_assets または enqueue_block_editor_assets を使用できます。エディター専用のスタイルシートは、ほぼ常に add_editor_style() または wp_enqueue_block_style() で追加されるべきです。

wp_enqueue_block_style() 関数を使用すると、エディターとフロントエンドでブロックごとのスタイルシートを読み込むことができます。theme.json と組み合わせることで、ブロックのスタイリングに最適な方法の一つです。詳細については、WordPress Developer Blogの記事 Leveraging theme.json and per-block styles for more performant themes を参照してください。

後方互換性と既知の問題

一般的なルールとして、iframe化されたエディターにアセットをキューイングすると、エディターがiframe化されていない場合でも、WordPress 6.3+を使用している限り、アセットもキューイングされます。逆は常に真ではありません。

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

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

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

このガイドに記載されている方法を使用して問題が発生した場合は、以前に報告されていない場合、問題を提出してください GitHubで。