ハウツーガイド - プラグインサイドバー（Plugin Sidebar）

概要
始める前に
ステップバイステップガイド
追加リソース
結論
- 注意

概要

プラグインにサイドバーを追加する方法。サイドバーはエディターの最右端の領域です。プラグインは、InspectorControls（ギアアイコン）の隣に展開可能な追加のアイコンを追加できます。

例のサイドバー

注：このチュートリアルはカスタムサイドバーを扱っています。サイドバーにコントロールを追加したい場合は、ブロックツールバーと設定サイドバーを参照してください。

始める前に

このチュートリアルは、既存のプラグインセットアップがあり、PHPおよびJavaScriptコードを追加する準備ができていることを前提としています。WordPressプラグインの紹介と、ブロックエディターを拡張するためのJavaScriptの使用方法については、JavaScriptの始め方チュートリアルを参照してください。

ステップバイステップガイド

ステップ1：サイドバーを立ち上げる

最初のステップは、エディターに新しいプラグインが独自のサイドバーを持つことを伝えることです。registerPlugin、PluginSidebar、およびcreateElementユーティリティをそれぞれ@wordpress/plugins、@wordpress/editor、reactパッケージから使用します。

次のコードをplugin-sidebar.jsというJavaScriptファイルに追加し、プラグインのディレクトリ内に保存します：

( function ( wp, React ) {
   var el = React.createElement;
   var registerPlugin = wp.plugins.registerPlugin;
   var PluginSidebar = wp.editor.PluginSidebar;
   registerPlugin( 'my-plugin-sidebar', {
   render: function () {
   return el(
   PluginSidebar,
   {
   name: 'my-plugin-sidebar',
   icon: 'admin-post',
   title: 'My plugin sidebar',
   },
   'Meta field'
   );
   },
   } );
} )( window.wp, window.React );

このコードが機能するためには、これらのユーティリティがブラウザで利用可能である必要があるため、wp-plugins、wp-edit-post、およびreactをスクリプトの依存関係として指定する必要があります。

スクリプトを登録し、依存関係を指定するためのPHPコードは次のとおりです：

<?php
/*
Plugin Name: Sidebar plugin
*/
function sidebar_plugin_register() {
   wp_register_script(
   'plugin-sidebar-js',
   plugins_url( 'plugin-sidebar.js', __FILE__ ),
   array( 'wp-plugins', 'wp-editor', 'react' )
   );
}
add_action( 'init', 'sidebar_plugin_register' );
function sidebar_plugin_script_enqueue() {
   wp_enqueue_script( 'plugin-sidebar-js' );
}
add_action( 'enqueue_block_editor_assets', 'sidebar_plugin_script_enqueue' );

このプラグインをインストールして有効化すると、エディターの右上にタックに似た新しいアイコンが表示されます。それをクリックすると、プラグインのサイドバーが開きます：

サイドバーの立ち上げ

ステップ2：サイドバーのスタイルを調整し、コントロールを追加する

サイドバーが立ち上がったら、次のステップは必要なコンポーネントと基本的なスタイリングでそれを満たすことです。

メタフィールドの値を視覚化および編集するために、入力コンポーネントを使用します。@wordpress/componentsパッケージには再利用可能な多くのコンポーネントが含まれており、特にTextControlは入力フィールドを作成することを目的としています：

( function ( wp ) {
   var el = React.createElement;
   var registerPlugin = wp.plugins.registerPlugin;
   var PluginSidebar = wp.editor.PluginSidebar;
   var TextControl = wp.components.TextControl;
   registerPlugin( 'my-plugin-sidebar', {
   render: function () {
   return el(
   PluginSidebar,
   {
   name: 'my-plugin-sidebar',
   icon: 'admin-post',
   title: 'My plugin sidebar',
   },
   el(
   'div',
   { className: 'plugin-sidebar-content' },
   el( TextControl, {
   label: 'Meta Block Field',
   value: 'Initial value',
   onChange: function ( content ) {
   console.log( 'content changed to ', content );
   },
   } )
   )
   );
   },
   } );
} )( window.wp );

この新しいコードでplugin-sidebar.jsを更新します。新しいユーティリティwp.componentsが@wordpress/componentsパッケージから使用されていることに注意してください。PHPファイルのwp_register_script関数の依存関係にwp-componentsを追加することを忘れないでください。

このコードは次のことを導入します：

スタイルをターゲットにするためにplugin-sidebar-content CSSクラスをdiv要素に追加、
プレーンな'Meta field'テキストの代わりにTextControlコンポーネントを使用します。

新しいCSSクラスが利用可能になったので、少しスタイルを追加できます。プラグインディレクトリ内にplugin-sidebar.cssという新しいファイルを作成し、次のようにパディングを追加します：

.plugin-sidebar-content {
   padding: 16px;
}

スクリプトを登録し、JavaScriptファイルとともにenqueue_block_editor_assetsで読み込むようにキューに追加します。

これらの変更の後、PHPコードは次のようになります：

<?php
/*
Plugin Name: Sidebar example
*/
function sidebar_plugin_register() {
   wp_register_script(
   'plugin-sidebar-js',
   plugins_url( 'plugin-sidebar.js', __FILE__ ),
   array(
   'react',
   'wp-plugins',
   'wp-editor',
   'wp-components'
   )
   );
   wp_register_style(
   'plugin-sidebar-css',
   plugins_url( 'plugin-sidebar.css', __FILE__ )
   );
}
add_action( 'init', 'sidebar_plugin_register' );
function sidebar_plugin_script_enqueue() {
   wp_enqueue_script( 'plugin-sidebar-js' );
   wp_enqueue_style( 'plugin-sidebar-css' );
}
add_action( 'enqueue_block_editor_assets', 'sidebar_plugin_script_enqueue' );

エディターを再読み込みし、サイドバーを開きます：

スタイルとコントロールのあるサイドバー

このコードはまだユーザーがデータを保存または取得することを許可していないため、次のステップではメタブロックフィールドに接続する方法に焦点を当てます。

ステップ3：メタフィールドを登録する


注：このフィールドはREST APIで利用可能である必要があります。なぜなら、それがブロックエディターがデータにアクセスする方法だからです。  
プラグインの`````init`````コールバック関数にPHPコードを追加します：  
``````bash
register_post_meta( 'post', 'sidebar_plugin_meta_block_field', array(
   'show_in_rest' => true,
   'single' => true,
   'type' => 'string',
) );
`

確認するために、ブロックエディターストアをクエリしてフィールドが読み込まれているか確認します。実装後、エディターページを再読み込みし、ブラウザの開発者コンソールを開きます。このJavaScriptスニペットをコンソールで使用して確認します：

wp.data.select( 'core/editor' ).getCurrentPost().meta;

この関数は、登録したメタフィールドを含むオブジェクトを返します。

コードがundefinedを返す場合は、投稿タイプがcustom-fieldsをサポートしていることを確認してください。投稿を登録する際またはadd_post_type_support関数で行います。

ステップ4：入力コントロールを初期化する

エディターストアにフィールドが利用可能になったので、UIに表示できるようになります。機能を追加する際にコードをクリーンに保つために、入力コントロールを関数に抽出します。

( function ( wp ) {
   var el = React.createElement;
   var registerPlugin = wp.plugins.registerPlugin;
   var PluginSidebar = wp.editor.PluginSidebar;
   var TextControl = wp.components.TextControl;
   var MetaBlockField = function () {
   return el( TextControl, {
   label: 'Meta Block Field',
   value: 'Initial value',
   onChange: function ( content ) {
   console.log( 'content changed to ', content );
   },
   } );
   };
   registerPlugin( 'my-plugin-sidebar', {
   render: function () {
   return el(
   PluginSidebar,
   {
   name: 'my-plugin-sidebar',
   icon: 'admin-post',
   title: 'My plugin sidebar',
   },
   el(
   'div',
   { className: 'plugin-sidebar-content' },
   el( MetaBlockField )
   )
   );
   },
   } );
} )( window.wp );


`````useSelect`````関数は、コンポーネントが読み込まれるときにデータを取得し、データが変更された場合に更新します。`````useSelect`````を使用したコードの更新は次のとおりです：  
``````bash
( function ( wp ) {
   var el = React.createElement;
   var registerPlugin = wp.plugins.registerPlugin;
   var PluginSidebar = wp.editor.PluginSidebar;
   var Text = wp.components.TextControl;
   var useSelect = wp.data.useSelect;
   var MetaBlockField = function () {
   var metaFieldValue = useSelect( function ( select ) {
   return select( 'core/editor' ).getEditedPostAttribute(
   'meta'
   )[ 'sidebar_plugin_meta_block_field' ];
   }, [] );
   return el( Text, {
   label: 'Meta Block Field',
   value: metaFieldValue,
   onChange: function ( content ) {
   console.log( 'content has changed to ', content );
   },
   } );
   };
   registerPlugin( 'my-plugin-sidebar', {
   render: function () {
   return el(
   PluginSidebar,
   {
   name: 'my-plugin-sidebar',
   icon: 'admin-post',
   title: 'My plugin sidebar',
   },
   el(
   'div',
   { className: 'plugin-sidebar-content' },
   el( MetaBlockField )
   )
   );
   },
   } );
} )( window.wp );
`


注：`````getEditedPostAttribute`````呼び出しは、ユーザーがまだ保存していない編集を含む投稿の最新の値を取得するために使用されます。  
コードを更新し、再読み込みし、サイドバーを開くことで動作を確認します。入力の内容はもはや`````Initial value`````ではなく、空の文字列です。ユーザーはまだ値を入力できませんが、ストア内の値が変更された場合にコンポーネントが更新されることを確認できます。ブラウザのコンソールを開き、実行します：  
``````bash
wp.data
   .dispatch( 'core/editor' )
   .editPost( { meta: { sidebar_plugin_meta_block_field: 'hello world!' } } );
`

入力コンポーネントの内容が変化するのを観察できます。

ステップ5：入力の内容が変更されたときにメタフィールドを更新する

最後のステップは、入力内容が変更されたときにメタフィールドを更新することです。


``````bash
( function ( wp ) {
   var el = React.createElement;
   var registerPlugin = wp.plugins.registerPlugin;
   var PluginSidebar = wp.editor.PluginSidebar;
   var TextControl = wp.components.TextControl;
   var useSelect = wp.data.useSelect;
   var useDispatch = wp.data.useDispatch;
   var MetaBlockField = function ( props ) {
   var metaFieldValue = useSelect( function ( select ) {
   return select( 'core/editor' ).getEditedPostAttribute(
   'meta'
   )[ 'sidebar_plugin_meta_block_field' ];
   }, [] );
   var editPost = useDispatch( 'core/editor' ).editPost;
   return el( TextControl, {
   label: 'Meta Block Field',
   value: metaFieldValue,
   onChange: function ( content ) {
   editPost( {
   meta: { sidebar_plugin_meta_block_field: content },
   } );
   },
   } );
   };
   registerPlugin( 'my-plugin-sidebar', {
   render: function () {
   return el(
   PluginSidebar,
   {
   name: 'my-plugin-sidebar',
   icon: 'admin-post',
   title: 'My plugin sidebar',
   },
   el(
   'div',
   { className: 'plugin-sidebar-content' },
   el( MetaBlockField )
   )
   );
   },
   } );
} )( window.wp );
`

更新後、ユーザーが入力すると、入力コントロールはeditPostを呼び出し、各キー入力でエディターストアを更新します。

JavaScriptを更新し、サイドバーを読み込み、入力フィールドに入力します。入力コントロールに何かを入力し、ブラウザの開発者コンソールでJavaScriptスニペットを実行することで、保存されていることを確認できます：

wp.data.select( 'core/editor' ).getEditedPostAttribute( 'meta' )[
   'sidebar_plugin_meta_block_field'
];

表示されるメッセージは、入力した内容であるべきです。

投稿を保存すると、保存後に再読み込みし、入力コントロールが最後に入力した値で初期化されていることを確認することで、データベースに正しく保存されていることを確認できます。

追加リソース

@wordpress/dataパッケージで作業するためのドキュメント。

このガイドで使用される関数：

結論

これで、post_metaの内容を更新するために使用できるカスタムサイドバーができました。

完全な例が利用可能です。plugin-sidebarの例をblock-development-examplesリポジトリからダウンロードしてください。

注意

エディターの「設定」ページの「パネル」でカスタムフィールドを有効にしている場合（右上の三点リーダーを介して）、この場合sidebar_plugin_meta_block_fieldと同じ名前のフィールドがエディタウィンドウの下部にあるカスタムフィールドパネルにも表示されます。これらの2つのフィールドは同じメタプロパティにアクセスできます。

テキストコントロールとカスタムフィールド

投稿を保存すると、TextControlの値が最初に保存され、カスタムフィールドの値が2番目に保存されるため、最終的にデータベースに永続化されるのはカスタムフィールドの値です。したがって、TextControlの値を変更しても、最終的に保存されるのはカスタムフィールドの値です。

カスタムフィールドが有効になっていない場合、この問題は発生しません。

カスタムフィールドを有効にし、サイドバーに投稿メタを持たせる必要がある場合、2つの解決策があります：

1. メタフィールドの名前の前にアンダースコアを付けると、上記の例では_sidebar_plugin_meta_block_fieldになります。これは、投稿メタがプライベートとして扱われるべきであることを示し、投稿のカスタムフィールドセクションには表示されません。この解決策では、投稿を保存するとエラーが生成されますが、register_post_metaに渡されるargs配列にauth_callbackプロパティを追加し、最終的にtrueを返す関数を追加することで解決できます。詳細については、argsページのドキュメントを参照してください。
2. TextControlのonChange関数で、Valueフィールドのテキストエリアをターゲットにし、そこにTextControlメタフィールドの値と同じ値を設定します。これにより、両方の場所で値が同じになり、TextControlで値が変更されると、データベースに保存されることが保証されます。

return el( TextControl, {
  label: 'Meta Block Field',
  value: metaFieldValue,
  onChange: function ( content ) {
   editPost( {
   meta: { sidebar_plugin_meta_block_field: content }
   })
   document.querySelector( {the-value-textarea} ).innerHTML = content;
  },
} );