開発プラットフォーム - カスタムブロックエディタの構築（Building a custom block editor）

はじめに
コード構文
構築するもの
プラグインのセットアップと構成
エディタの「コア」
カスタム「ブロックエディタ」ページの作成
カスタムブロックエディタの登録とレンダリング
コンポーネントのレビュー
カスタム
まとめ

はじめに

多くのパッケージとコンポーネントを持つGutenbergのコードベースは、最初は圧倒されるかもしれません。しかし、その核心はブロックの管理と編集にあります。したがって、エディタに取り組む場合、ブロック編集が基本的にどのように機能するかを理解することが不可欠です。

このガイドでは、WordPress内で完全に機能するカスタムブロックエディタの「インスタンス」を構築する方法を説明します。その過程で、ブロックエディタがどのように機能するかを理解するために、主要なパッケージとコンポーネントを紹介します。

この記事の終わりまでには、ブロックエディタの内部動作をしっかりと理解し、自分自身のブロックエディタインスタンスを作成する準備が整います。

このガイドで使用されるコードは、付随するWordPressプラグインからダウンロードできます。このプラグインのデモコードは、重要なリソースです。

コード構文

このガイドのコードスニペットは、JSX構文を使用しています。ただし、好みに応じてプレーンJavaScriptを使用することもできます。しかし、JSXに慣れると、多くの開発者はそれを読み書きするのが簡単だと感じるため、Block Editor Handbookのすべてのコード例はこの構文を使用しています。

構築するもの

このガイドを通じて、(ほぼ)完全に機能するブロックエディタインスタンスを作成します。結果は次のようになります:

カスタムWordPress管理ページ内に例のブロックで埋め込まれたスタンドアロンエディタインスタンス

見た目は似ていますが、このエディタはWordPressで投稿やページを作成する際に馴染みのあるブロックエディタとは異なります。代わりに、「ブロックエディタ」と呼ばれるカスタムWordPress管理ページ内に存在する完全にカスタムのインスタンスになります。

このエディタには次の機能があります:

すべてのコアブロックを追加および編集する機能。
視覚的スタイルとメイン/サイドバーのレイアウトに慣れ親しんだもの。
ページのリロード間での基本的なブロックの永続性。

プラグインのセットアップと構成

カスタムエディタはWordPressプラグインとして構築されます。シンプルに保つために、プラグインはStandalone Block Editor Demoと名付けられます。なぜなら、それが行うことだからです。

プラグインのファイル構造は次のようになります:

alt text

ここでは、何が起こっているのかの簡単な概要を示します:

plugin.php – コメントメタデータを持つ標準的なプラグイン「エントリ」ファイルで、init.phpが必要です。
init.php – メインプラグインロジックの初期化を処理します。
src/ (ディレクトリ) – ここにJavaScriptとCSSのソースファイルが格納されます。これらのファイルはプラグインによって直接キューに追加されません。
webpack.config.js – カスタムCSSスタイルを許可するために、@wordpress/scripts npmパッケージによって提供されるデフォルトを拡張するカスタムWebpack設定です。

上記に示されていない唯一の項目はbuild/ディレクトリで、ここに@wordpress/scriptsによって出力されたコンパイル済みJSおよびCSSファイルがあります。これらのファイルはプラグインによって別々にキューに追加されます。

このガイドを通じて、ファイル名の参照は各コードスニペットの先頭にコメントとして配置されるので、追跡できます。

基本的なファイル構造が整ったので、必要なパッケージを見てみましょう。

エディタの「コア」

WordPressエディタは多くの動く部分で構成されていますが、そのコアは@wordpress/block-editorパッケージであり、これは自身のREADMEファイルで最もよく要約されます:

このモジュールは、スタンドアロンのブロックエディタを作成して使用することを可能にします。
完璧です。これはカスタムブロックエディタインスタンスを作成するために使用する主要なパッケージです。しかしまず、エディタのためのホームを作成する必要があります。

カスタム「ブロックエディタ」ページの作成

WordPress管理内にカスタムブロックエディタインスタンスを収容するカスタムページを作成することから始めましょう。

WordPressでカスタム管理ページを作成するプロセスにすでに慣れている場合は、先に進むことをお勧めします。

ページの登録

これを行うには、標準のWordPress add_menu_page()ヘルパーを使用してカスタム管理ページを登録する必要があります:

// File: init.php
add_menu_page(
   'Standalone Block Editor',         // Visible page name
   'Block Editor',                    // Menu label
   'edit_posts',                      // Required capability
   'getdavesbe',                      // Hook/slug of page
   'getdave_sbe_render_block_editor', // Function to render the page
   'dashicons-welcome-widgets-menus'  // Custom icon
);

 <a name="adding-the-target-html"></a>
### ターゲットHTMLの追加
ブロックエディタはReact駆動のアプリケーションであるため、JavaScriptがブロックエディタをレンダリングできるカスタムページにいくつかのHTMLを出力する必要があります。  
上記のステップで参照された`````getdave_sbe_render_block_editor`````関数を使用しましょう。  
``````bash
// File: init.php
function getdave_sbe_render_block_editor() {
   ?>
   <div
   id="getdave-sbe-block-editor"
   class="getdave-sbe-block-editor"
   >
   Loading Editor...
   </div>
   <?php
}
`

この関数は基本的なプレースホルダーHTMLを出力します。id属性getdave-sbe-block-editorに注意してください。これはすぐに使用されます。

JavaScriptとCSSのキュー追加

ターゲットHTMLが整ったので、カスタム管理ページで実行されるJavaScriptとCSSをキューに追加できます。

これを行うには、admin_enqueue_scriptsにフックしましょう。

まず、カスタムコードがカスタム管理ページでのみ実行されることを確認する必要があります。したがって、コールバック関数の先頭で、ページがページの識別子と一致しない場合は早期に終了します:

// File: init.php
function getdave_sbe_block_editor_init( $hook ) {
   // Exit if not the correct page.
   if ( 'toplevel_page_getdavesbe' !== $hook ) {
   return;
   }
}
add_action( 'admin_enqueue_scripts', 'getdave_sbe_block_editor_init' );

これが整ったら、標準のWordPress wp_enqueue_script()関数を使用してメインJavaScriptファイルを安全に登録できます:

// File: init.php
wp_enqueue_script( $script_handle, $script_url, $script_asset['dependencies'], $script_asset['version'] );

時間とスペースを節約するために、$script_変数の割り当ては省略されています。これらをこちらで確認できます。

スクリプト依存関係の第3引数$script_asset['dependencies']に注意してください。これらの依存関係は、@wordpress/dependency-extraction-webpack-pluginを使用して動的に生成され、

WordPressが提供するスクリプトがビルドされたバンドルに含まれないことを保証します。

また、カスタムCSSスタイルとWordPressのデフォルトフォーマットライブラリの両方を登録して、いくつかの素晴らしいデフォルトスタイリングを活用する必要があります:

// File: init.php
// Enqueue default editor styles.
wp_enqueue_style( 'wp-format-library' );
// Enqueue custom styles.
wp_enqueue_style(
   'getdave-sbe-styles',                       // Handle
   plugins_url( 'build/index.css', __FILE__ ), // Block editor CSS
   array( 'wp-edit-blocks' ),                  // Dependency to include the CSS after it
   filemtime( __DIR__ . '/build/index.css' )
);

エディタ設定のインライン化

@wordpress/block-editorパッケージを見てみると、エディタのデフォルト設定を構成するために設定オブジェクトを受け入れることがわかります。これらはサーバー側で利用可能であるため、JavaScript内で使用できるように公開する必要があります。

これを行うために、グローバルwindow.getdaveSbeSettingsオブジェクトに割り当てられた設定オブジェクトをJSONとしてインライン化することにしましょう:

// File: init.php
// Get custom editor settings.
$settings = getdave_sbe_get_block_editor_settings();
// Inline all settings.
wp_add_inline_script( $script_handle, 'window.getdaveSbeSettings = ' . wp_json_encode( $settings ) . ';' );

カスタムブロックエディタの登録とレンダリング

上記のPHPが管理ページを作成するために整ったので、今やJavaScriptを使用してページのHTMLにブロックエディタをレンダリングする準備が整いました。

まず、メインのsrc/index.jsファイルを開きます。次に、必要なJavaScriptパッケージをプルインし、CSSスタイルをインポートします。Sassを使用する場合は、デフォルトの@wordpress/scripts Webpack設定を拡張する必要があります。

// File: src/index.js
// External dependencies.
import { createRoot } from 'react-dom';
// WordPress dependencies.
import domReady from '@wordpress/dom-ready';
import { registerCoreBlocks } from '@wordpress/block-library';
// Internal dependencies.
import Editor from './editor';
import './styles.scss';

次に、DOMが準備できたら、次のことを行う関数を実行する必要があります:

window.getdaveSbeSettingsからエディタ設定を取得します（以前にPHPからインライン化されたもの）。
registerCoreBlocksを使用してすべてのコアWordPressブロックを登録します。
カスタム管理ページの待機中の<div>に<Editor>コンポーネントをレンダリングします。

domReady( function () {
   const root = createRoot( document.getElementById( 'getdave-sbe-block-editor' ) );
   const settings = window.getdaveSbeSettings || {};
   registerCoreBlocks();
   root.render(
   <Editor settings={ settings } />
   );
} );

PHPからエディタをレンダリングすることは、不要なJSグローバルを作成せずに可能です。これについての例は、GutenbergプラグインのEdit Siteパッケージをチェックしてください。

コンポーネントのレビュー

上記のコードで使用され、付随するプラグインのsrc/editor.jsに存在する<Editor>コンポーネントを詳しく見てみましょう。

その名前にもかかわらず、これは実際のブロックエディタのコアではありません。むしろ、カスタムエディタの主要なボディを形成するコンポーネントを含むラッパーコンポーネントです。

依存関係


``````bash
// File: src/editor.js
import Notices from 'components/notices';
import Header from 'components/header';
import Sidebar from 'components/sidebar';
import BlockEditor from 'components/block-editor';
`

これらの中で最も重要なのは、内部コンポーネントBlockEditorとSidebarであり、これらはすぐに説明されます。

残りのコンポーネントは、主にエディタのレイアウトと周囲のユーザーインターフェース（UI）を形成する静的要素で構成されています。これらの要素には、ヘッダーや通知エリアなどが含まれます。

エディタのレンダリング

これらのコンポーネントが利用可能になったので、<Editor>コンポーネントを定義できます。

// File: src/editor.js
function Editor( { settings } ) {
   return (
   <DropZoneProvider>
   <div className="getdavesbe-block-editor-layout">
   <Notices />
   <Header />
   <Sidebar />
   <BlockEditor settings={ settings } />
   </div>
   </DropZoneProvider>
   );
}

このプロセスでは、エディタのレイアウトのコアがスキャフォールドされ、特定の機能をコンポーネント階層全体で利用可能にするいくつかの特殊なコンテキストプロバイダーが作成されます。

これらを詳しく見てみましょう:

<DropZoneProvider> – ドラッグアンドドロップ機能のためのドロップゾーンを使用可能にします
<Notices> – core/noticesストアにメッセージが送信された場合にレンダリングされる「スナックバー」通知を提供します
<Header> – エディタUIの上部に「スタンドアロンブロックエディタ」という静的タイトルをレンダリングします
<BlockEditor> – カスタムブロックエディタコンポーネント

キーボードナビゲーション

この基本的なコンポーネント構造が整ったので、残る唯一のことは、レイアウト内の異なる「領域」間でキーボードナビゲーションを提供するために、navigateRegions HOCで全てをラップすることです。

// File: src/editor.js
export default navigateRegions( Editor );

カスタム

今やコアレイアウトとコンポーネントが整いました。ブロックエディタ自体のカスタム実装を探求する時が来ました。

このコンポーネントは<BlockEditor>と呼ばれ、ここで魔法が起こります。


``````bash
// File: src/components/block-editor/index.js
return (
   <div className="getdavesbe-block-editor">
   <BlockEditorProvider
   value={ blocks }
   onInput={ updateBlocks }
   onChange={ persistBlocks }
   settings={ settings }
   >
   <Sidebar.InspectorFill>
   <BlockInspector />
   </Sidebar.InspectorFill>
   <BlockCanvas height="400px" />
   </BlockEditorProvider>
   </div>
);
`

重要なコンポーネントは<BlockEditorProvider>と<BlockList>です。これらを詳しく見てみましょう。

コンポーネントの理解

<BlockEditorProvider>は階層内で最も重要なコンポーネントの1つです。新しいブロックエディタのための新しいブロック編集コンテキストを確立します。

その結果、これはこのプロジェクトの全体的な目標にとって基本的です。


``````bash
// File: src/components/block-editor/index.js
<BlockEditorProvider
   value={ blocks }           // Array of block objects
   onInput={ updateBlocks }   // Handler to manage Block updates
   onChange={ persistBlocks } // Handler to manage Block updates/persistence
   settings={ settings }      // Editor "settings" object
/>
`

BlockEditorプロパティ


内部的には、`````registry`````（[`````withRegistryProvider````` HOC](https://github.com/WordPress/gutenberg/blob/e38dbe958c04d8089695eb686d4f5caff2707505/packages/block-editor/src/components/provider/index.js#L158)を介して）にサブスクライブすることによってこれを行い、ブロック変更イベントをリッスンし、ブロックの変更が永続的であったかどうかを判断し、その後、適切な`````onChange|Input`````ハンドラを呼び出します。  
このシンプルなプロジェクトの目的のために、これらの機能により、次のことが可能になります:  
- 現在のブロックの配列を`````blocks`````として状態に保存します。 
- `````blocks`````を呼び出すことによって`````onInput`````の状態をメモリ内で更新します。  
- `````localStorage`````にブロックの基本的な永続性を`````onChange`````を使用して処理します。これは[ブロックの更新が「コミットされた」と見なされるときに発火します](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/provider#onchange)。  
また、コンポーネントが`````settings`````プロパティを受け入れることを思い出す価値があります。ここに、`````init.php`````内でJSONとしてインライン化されたエディタ設定を追加します。これらの設定を使用して、カスタムカラー、利用可能な画像サイズ、[その他多くの機能](https://github.com/WordPress/gutenberg/tree/4c472c3443513d070a50ba1e96f3a476861447b3/packages/block-editor#SETTINGS_DEFAULTS)を構成できます。  
 <a name="understanding-the-blocklist-component"></a>
### <BlockList>コンポーネントの理解
`````<BlockEditorProvider>`````と並んで、次に興味深いコンポーネントは[`````<BlockList>`````](https://github.com/WordPress/gutenberg/blob/e38dbe958c04d8089695eb686d4f5caff2707505/packages/block-editor/src/components/block-list/index.js)です。  
これは、**エディタにブロックのリストをレンダリングする**という役割を持つ最も重要なコンポーネントの1つです。  
これは、`````<BlockEditorProvider>`````の子として配置されることによって部分的に実現され、エディタ内の現在のブロックの状態に関するすべての情報に完全にアクセスできます。
#### BlockListはどのように機能しますか？
`````<BlockList>`````は、ブロックのリストをレンダリングするために、いくつかの他の低レベルのコンポーネントに依存しています。  
これらのコンポーネントの階層は次のように*近似*できます:  
``````bash
// Pseudo code for example purposes only.
<BlockList>
   /* renders a list of blocks from the rootClientId. */
   <BlockListBlock>
   /* renders a single block from the BlockList. */
   <BlockEdit>
   /* renders the standard editable area of a block. */
   <Component /> /* renders the block UI as defined by its `edit()` implementation.
   */
   </BlockEdit>
   </BlockListBlock>
</BlockList>
`

これがブロックのリストをレンダリングするためにどのように機能するかの概要です:

<BlockList>はすべてのブロックclientIdsをループし、
各ブロックを<BlockListBlock />を介してレンダリングします。
<BlockListBlock />は、独自のサブコンポーネント<BlockEdit>を使用して個々のブロックをレンダリングします。
最後に、https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-edit/edit.jsはComponentプレースホルダーコンポーネントを使用してレンダリングされます。

 <a name="reviewing-the-sidebar"></a>
## サイドバーのレビュー
`````<BlockEditor>`````のレンダリング内にも、`````<Sidebar>`````コンポーネントがあります。  
``````bash
// File: src/components/block-editor/index.js
return (
   <div className="getdavesbe-block-editor">
   <BlockEditorProvider>
   <Sidebar.InspectorFill> /* <-- SIDEBAR */
   <BlockInspector />
   </Sidebar.InspectorFill>
   <BlockCanvas height="400px" />
   </BlockEditorProvider>
   </div>
);
`

これは、<BlockInspector>コンポーネントを介して高度なブロック設定を表示するために部分的に使用されます。

<Sidebar.InspectorFill>
   <BlockInspector />
</Sidebar.InspectorFill>

しかし、鋭い目を持つ読者の中には、<Editor>（src/editor.js）コンポーネントのレイアウト内に<Sidebar>コンポーネントが存在することにすでに気づいている方もいるでしょう:

// File: src/editor.js
<Notices />
<Header />
<Sidebar /> // <-- What's this?
<BlockEditor settings={ settings } />


Slot/Fillを利用して`````Fill`````（`````<Sidebar.InspectorFill>`````）を公開し、その後`````<BlockEditor>`````コンポーネント内でインポートされてレンダリングされます（上記を参照）。  
これが整ったら、`````<BlockInspector />`````を`````Sidebar.InspectorFill`````の子としてレンダリングできます。これにより、`````<BlockInspector>`````を`````<BlockEditorProvider>`````のReactコンテキスト内に保持しつつ、DOM内の別の場所（つまり、`````<Sidebar>`````）にレンダリングできるようになります。  
これは過度に複雑に思えるかもしれませんが、`````<BlockInspector>`````が現在のブロックに関する情報にアクセスできるようにするために必要です。Slot/Fillがなければ、このセットアップを達成するのは非常に困難です。  
これで、カスタム`````<BlockEditor>`````のレンダリングが完了しました。  
[`````<BlockInspector>`````](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-inspector/index.js)  
自体は、[`````<InspectorControls>`````](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/inspector-controls)のために`````Slot`````をレンダリングします。これにより、ブロックの`````edit()`````定義内に`````<InspectorControls>>`````コンポーネントをレンダリングし、エディタのサイドバー内に表示できるようになります。このコンポーネントをさらに詳しく探求することをお勧めします。  
 <a name="block-persistence"></a>
## ブロックの永続性
カスタムブロックエディタを作成する旅は長い道のりでした。しかし、触れるべき重要な領域が1つ残っています - ブロックの永続性。言い換えれば、ページのリフレッシュ間でブロックが保存され、利用可能であることです。  
![alt text](https://cdn.hedaai.com/projects/wordpress/c2767c2d0327d2c7063a919c04e1a1a8.gif)  
これは単なる*実験*であるため、このガイドではブラウザの`````localStorage````` APIを利用してブロックデータの保存を処理することにしました。実際のシナリオでは、より信頼性が高く堅牢なシステム（例えば、データベース）を選択することになるでしょう。  
とはいえ、ブロックを保存する方法を詳しく見てみましょう。  
 <a name="storing-blocks-in-state"></a>
### 状態にブロックを保存する
`````src/components/block-editor/index.js`````ファイルを見てみると、ブロックを配列として保存するための状態が作成されていることに気づくでしょう:  
``````bash
// File: src/components/block-editor/index.js
const [ blocks, updateBlocks ] = useState( [] );
`

前述のように、blocksは「制御された」コンポーネント<BlockEditorProvider>にそのvalueプロパティとして渡されます。この「水和」により、初期のブロックセットが与えられます。同様に、updateBlocksセッターはonInputコールバックに接続され、<BlockEditorProvider>内でのブロックの変更と同期されることを保証します。

ブロックデータの保存

今、onChangeハンドラに目を向けると、次のように定義された関数persistBlocks()に接続されていることに気づくでしょう:

// File: src/components/block-editor/index.js
function persistBlocks( newBlocks ) {
   updateBlocks( newBlocks );
   window.localStorage.setItem( 'getdavesbeBlocks', serialize( newBlocks ) );
}

この関数は、「コミットされた」ブロック変更の配列を受け入れ、状態セッターupdateBlocksを呼び出します。また、ブロックをキーgetdavesbeBlocksの下でLocalStorageに保存します。これを実現するために、ブロックデータはGutenberg「ブロック文法」形式にシリアライズされ、文字列として安全に保存できます。

DeveloperToolsを開いてLocalStorageを検査すると、エディタ内で変更が発生するたびにシリアライズされたブロックデータが保存され、更新されているのがわかります。以下はその形式の例です:

<!-- wp:heading -->
<h2>An experiment with a standalone Block Editor in the WordPress admin</h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p>This is an experiment to discover how easy (or otherwise) it is to create a standalone instance of the Block Editor in the WordPress admin.</p>
<!-- /wp:paragraph -->

以前のブロックデータの取得

永続性が整っているのは良いことですが、そのデータが取得され、ページの完全なリロード時にエディタ内で復元される場合にのみ役立ちます。

データにアクセスすることは副作用であるため、これを処理するためにuseEffectフックを使用する必要があります。

// File: src/components/block-editor/index.js
useEffect( () => {
   const storedBlocks = window.localStorage.getItem( 'getdavesbeBlocks' );
   if ( storedBlocks && storedBlocks.length ) {
   updateBlocks( () => parse( storedBlocks ) );
   createInfoNotice( 'Blocks loaded', {
   type: 'snackbar',
   isDismissible: true,
   } );
   }
}, [] );

このハンドラは:

ローカルストレージからシリアライズされたブロックデータを取得します。
シリアライズされたブロックをparse()ユーティリティを使用してJavaScriptオブジェクトに戻します。
状態セッターupdateBlocksを呼び出し、blocksの値をLocalStorageから取得したブロックを反映するように更新します。

これらの操作の結果、制御された<BlockEditorProvider>コンポーネントがLocalStorageから復元されたブロックで更新され、エディタがこれらのブロックを表示します。

最後に、ブロックが復元されたことを示す通知を生成したいと思います。これは「スナックバー」通知として<Notice>コンポーネントに表示されます。

まとめ

このガイドを完了したことをおめでとうございます。これで、ブロックエディタがどのように機能するかについての理解が深まったはずです。

あなたが構築したカスタムブロックエディタの完全なコードはGitHubで入手可能です。ダウンロードして自分で試してみてください。実験して、さらに進めてみてください。