2025年06月27日
こんにちは! 今日もコーディングを楽しんでいますか?
このシリーズでは、WordPress の Gutenberg ブロックエディタに、自作のコードブロック=「カスタムコードブロック」を追加する手順を紹介しています。第1回では環境構築から最小構成のカスタムブロックの作成までを扱い、第2回では edit.js
と save.js
を中心に、実際の JSX コードによる編集・保存ロジックを解説しました。
そして今回の第3回では、以下の4点をテーマに、プロジェクトの完成に向けて仕上げていきます。
- 各 JavaScript ファイル(
index.js
,edit.js
,save.js
)の説明と、import
しているモジュールの整理 - プロジェクトルートにある PHP ファイルについて
npm run build
およびnpm run plugin-zip
による、ビルドおよびパッケージ作成- 作成したカスタムコードブロックを、実際の WordPress サイトに導入する手順
JavaScript 各ファイルの説明
ぜんかい紹介した JavaScript のコードですが、紹介が駆け足になってしまったので、ここで重要な箇所をピックアップして説明します。また import
しているモジュールについても、整理します。
edit.js
import
しているモジュール:
@wordpress/block-editor
@wordpress/components
@wordpress/icons
./editor.scss
- SCSS ファイルを CSS ファイルにトランスパイルするために
import
しています。
- SCSS ファイルを CSS ファイルにトランスパイルするために
以下コード:
/** 属性名とアイコンとの key/value 値。 */
const ICONS = {
info: { label: '情報', icon: cautionFilled },
warning: { label: '注意', icon: error },
error: { label: '警告', icon: notAllowed },
};
ここでは、ブロック属性である type
の値と、画面に表示するアイコン及び文字とを紐づけるための key/value オブジェクト ICONS
を定義しています。各 icon
プロパティの値は @wordpress/icons
からインポートしたモジュールで、
cautionFilled
: 丸に「!」のアイコン。error
: 三角に「!」のアイコン。notAllowed
: 「通行止め」のアイコン。
を表しています。ちなみに、これらの実体は SVG ファイルです。
{/* ツールバー */}
<BlockControls>
<ToolbarGroup>
{Object.entries(ICONS).map(([key, { label, icon }]) => (
{/* ツールバーに3種類のボタンを描画し、押したら再描画させる。 */}
<ToolbarButton
key={key}
icon={icon}
label={label}
isPressed={type === key}
onClick={() => setAttributes({ type: key })}
/>
))}
</ToolbarGroup>
</BlockControls>
<BlockControls>
タグは、カスタムコードブロックのツールバー(ブロックを選択した時に、その上部に表示される UI)に、要素を追加することを示すタグです。一方で、一般的なツールバーを示す<Toolbar>
タグもあるのですが、これは一般的なボタンがすでに入っているものです。カスタムコードブロックの場合、それらがじゃまになることもあるので、<BlockControls>
タグを使うようにしましょう。<ToolbarGroup>
タグは、複数の<ToolbarButton>
タグを一つのグループにまとめます。Object.entries(ICONS).map(([key, { label, icon }]) => JSX
は、 JSX 内における「オブジェクトによる描画ループ」としては一般的な手法です。Vue をご存知の方なら、「Vue の v-for ディレクティブに相当する」と考えるとよろしいと思います。<ToolbarButton>
タグは、ツールバー内に表示するボタンです。ここでは JSX によるループの中にあるため、{}
内にある JavaScript 変数は、そのループごとに渡される値になります。icon
属性は、@wordpress/icons
からインポートしたモジュール名を指定します。isPressed
属性は、そのボタンが「押されている」状態で描画するかどうかを、true/false
で指定します。onClick
属性は、そのボタンがクリックされたときの、イベントハンドラを記述します。この例では、setAttributes({ type: key })
によって、このカスタムコードブロックのtype
属性を変更し、再描画を行うようになっています。
{/* エディターのブロック本体。 */}
<aside {...useBlockProps({ className: `info-block ${type}` })}>
{/* アイコンを描画する。 */}
<Icon icon={ICONS[type].icon} className="info-icon" size={28} />
<div className={'content'}>
{/* このカスタムコードブロックは、いかなるコードブロックも入れ子にできる。 */}
<InnerBlocks allowedBlocks={null} />
</div>
</aside>
<aside {...useBlockProps()}>
は、「<aside>
タグをブロックラッパーとする」という意味です。引数の key/value データは、HTML タグ属性の宣言で、ここでは<aside class="info-block {type の値}">
となります。<Icon>
はタグのように見えますが、 @wordpress/icons が提供する SVG ベースの React コンポーネントです。Dashicons とは別の仕組みで、ブロックエディタ向けに用意されたアイコンセットを描画・再描画する HTML タグのように使うことができます。<InnerBlocks>
タグは、他のコードブロックを受け入れ、入れ子にするためのタグです。これによって、「段落」や「見出し」などのコードブロックを記述することができるようになります。
save.js
import
しているモジュール:
@wordpress/block-editor
@wordpress/icons
以下コード:
<div className={'content'}>
{/* edit 関数で編集した内容を、反映させる。 */}
<InnerBlocks.Content />
</div>
<InnerBlocks.Content>
タグは、 edit() 関数の<InnerBlocks>
タグ内に記載された「執筆内容」そのものを指すタグです。これによって、このカスタムコードブロックを使った編集内容が HTML として保存され、プレビューや公開が可能となります。
index.js
import
しているモジュール:
@wordpress/blocks
./styles.scss
- SCSS ファイルを CSS ファイルにトランスパイルするために
import
しています。
- SCSS ファイルを CSS ファイルにトランスパイルするために
./edit.js
- edit() 関数を取り込みます。
./save.js
- save() 関数を取り込みます。
./block.json
- JSON ファイルの構造体を
metadata
という名称で取り込みます。
- JSON ファイルの構造体を
import { registerBlockType } from '@wordpress/blocks';
import './style.scss';
import { Edit } from './edit';
import { save } from './save';
import metadata from './block.json';
// edit 関数と save 関数を、登録する。
registerBlockType(metadata.name, {
/**
* @see ./edit.js
*/
edit: Edit,
/**
* @see ./save.js
*/
save,
});
registerBlockType()
関数の第1引数は、block.json の"name"
属性をそのまま渡します。これはブロックの識別子です。
PHP ファイルについて
プロジェクトルートにある PHP ファイル(たとえば customblock-information.php
)は、WordPress にブロックを登録(インストール)するためのエントリーファイルです。block.json
を基にブロックを登録する記述が中心となります。
スキャフォールディング(第1回参照)でプロジェクトを作ったさい、このようなファイルができているはずです(和訳できるところは、できる限り和訳しています)。ここでは、このファイルについて説明します。
<?php
/**
* Plugin Name: 情報カスタムコードブロック
* Description: Create Block ツールで作った、ブロックのスキャフォールド例。
* Version: 0.1.0
* Requires at least: 6.7
* Requires PHP: 7.4
* Author: WordPress 投稿者
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: customblock-information
*
* @package CreateBlock
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // 直接実行させることは禁止。
}
/**
* `blocks-manifest.php` ファイルを使い、ブロックを登録します。これはブロックタイプの登録を高速化します。
* また自動的に、すべてのアセットも、ブロックエディターとの関係にしたがって
* 順番に登録(エンキュー)されるようになります。
*
* @see https://make.wordpress.org/core/2025/03/13/more-efficient-block-type-registration-in-6-8/
* @see https://make.wordpress.org/core/2024/10/17/new-block-type-registration-apis-to-improve-performance-in-wordpress-6-7/
*/
function create_block_customblock_information_block_init() {
/**
* ブロックのメタデータを `blocks-manifest.php` から登録し、さらに
* そのメタデータに基づいて、ブロックタイプを登録します。
* WordPress 6.7 で追加した「ブロックメタデータの登録処理」をさらに簡略化するため、
* WordPress 6.8 で追加しました。
*
* @see https://make.wordpress.org/core/2025/03/13/more-efficient-block-type-registration-in-6-8/
*/
if ( function_exists( 'wp_register_block_types_from_metadata_collection' ) ) {
wp_register_block_types_from_metadata_collection( __DIR__ . '/build', __DIR__ . '/build/blocks-manifest.php' );
return;
}
/**
* `blocks-manifest.php` ファイルから、メタデータを登録します。
* WordPress 6.7 で、ブロックタイプの登録を高速化するために追加しました。
*
* @see https://make.wordpress.org/core/2024/10/17/new-block-type-registration-apis-to-improve-performance-in-wordpress-6-7/
*/
if ( function_exists( 'wp_register_block_metadata_collection' ) ) {
wp_register_block_metadata_collection( __DIR__ . '/build', __DIR__ . '/build/blocks-manifest.php' );
}
/**
* `blocks-manifest.php` ファイルから、ブロックタイプを登録します。
*
* @see https://developer.wordpress.org/reference/functions/register_block_type/
*/
$manifest_data = require __DIR__ . '/build/blocks-manifest.php';
foreach ( array_keys( $manifest_data ) as $block_type ) {
register_block_type( __DIR__ . "/build/{$block_type}" );
}
}
add_action( 'init', 'create_block_customblock_information_block_init' );
ブロックの登録
この PHP コードの create_block_customblock_information_block_init()
関数について、コードを追いかけてみます。
重要:
コード内でたびたび出現する /build/blocks-manifest.php
は、block.json
の内容がそのまま、ビルド時に PHP の配列として変換されたものです。
/**
* ブロックのメタデータを `blocks-manifest.php` から登録し、さらに
* そのメタデータに基づいて、ブロックタイプを登録します。
* WordPress 6.7 で追加した「ブロックメタデータの登録処理」をさらに簡略化するため、
* WordPress 6.8 で追加しました。
*
* @see https://make.wordpress.org/core/2025/03/13/more-efficient-block-type-registration-in-6-8/
*/
if ( function_exists( 'wp_register_block_types_from_metadata_collection' ) ) {
wp_register_block_types_from_metadata_collection( __DIR__ . '/build', __DIR__ . '/build/blocks-manifest.php' );
return;
}
本シリーズ執筆時点では、WordPress のバージョンは 6.8 であることを想定しています。
wp_register_block_types_from_metadata_collection()
関数は、これ以降に記述された処理をすべて含んでいます(さらに、よりパフォーマンスが高いとされます)。そのため、この関数が使える WordPress 6.8 以降の環境であれば、それを行ったあと、return
で後続の処理を抜けています(アーリーリターン)。
以降の記述は、この関数が使えない場合のフォールバックです。ゆえに、ご自身の環境だけで使う(=第三者に配布しない)カスタムブロックで、かつ、この関数が使えることが自明であれば、関数全体は以下のように簡略化できます。
function create_block_customblock_information_block_init() {
// これでおしまい!
wp_register_block_types_from_metadata_collection( __DIR__ . '/build', __DIR__ . '/build/blocks-manifest.php' );
}
/**
* `blocks-manifest.php` ファイルから、メタデータを登録します。
* WordPress 6.7 で、ブロックタイプの登録を高速化するために追加しました。
*
* @see https://make.wordpress.org/core/2024/10/17/new-block-type-registration-apis-to-improve-performance-in-wordpress-6-7/
*/
if ( function_exists( 'wp_register_block_metadata_collection' ) ) {
wp_register_block_metadata_collection( __DIR__ . '/build', __DIR__ . '/build/blocks-manifest.php' );
}
wp_register_block_metadata_collection()
関数は、build/blocks-manifest.php から、カスタムブロックの情報(メタデータ)を高速に登録するための関数です。これは WordPress 6.7 以降限定の関数なので、それ未満の環境では実行させないための条件分岐が入っています。
/**
* `blocks-manifest.php` ファイルから、ブロックタイプを登録します。
*
* @see https://developer.wordpress.org/reference/functions/register_block_type/
*/
$manifest_data = require __DIR__ . '/build/blocks-manifest.php';
foreach ( array_keys( $manifest_data ) as $block_type ) {
register_block_type( __DIR__ . "/build/{$block_type}" );
}
この部分が、実際にカスタムコードブロックを WordPress に登録する処理となります。具体的には register_block_type()
関数です。
register_block_type(__DIR__ . '/build/ブロック識別子')
と記述することで、そのディレクトリにある blocks-manifest.php を自動的に参照し、JS/CSS の読み込みや属性設定が行われます。ここでは、foreach() {}
によって、ブロック識別子である customblock-information
が自動的に登録されるようになっています。
実は、最初のスキャフォールディングで生成されるプロジェクトは、複数のカスタムコードブロックを作るために調整されたものです。そのため、ここではそれぞれカスタムコードブロックのメタデータを、順番に登録するような処理になっています。 /src/customblock-information/(様々なファイル)
のように、 /src
直下にファイルが置かれていなかったり、 foreach() {}
によるループが記載されているのは、そのためです。
こんかいは、 customblock-information
という1つだけのカスタムコードブロックだけを登録することは自明です。つまり、ここは本来ループする必要はありません。なのでここは:
register_block_type( __DIR__ . "/build/customblock-information" );
と書いても全く同じ意味になります。
演習(自信のある方向け)
ひと通りカスタムコードブロックの作成ができた後、このプロジェクト全体を、「1つだけのカスタムコードブロックを作る」ように、ディレクトリ構造や各コードを修正してみてください。
※チェックポイント: /src/customblock-information/(様々なファイル)
の /customblock-information
の部分は、カスタムブロックを1つしか作らないなら不要ですよね。ファイルパスを変えた時に、矛盾が発生しないようにしましょう!
プラグインの説明
第三者がこのカスタムコードブロックをインストールした時、現時点だとダッシュボードにはこのように表示されることでしょう。
- プラグイン名:情報カスタムコードブロック
- プラグイン説明:Create Block ツールで作った、ブロックのスキャフォールド例。
- 制作者:WordPress 投稿者
block.json に書いたはずの情報とは異なりますね。実はこの部分は、以下の記載が反映されているのです!
<?php
/**
* Plugin Name: 情報カスタムコードブロック
* Description: Create Block ツールで作った、ブロックのスキャフォールド例。
* Version: 0.1.0
* Requires at least: 6.7
* Requires PHP: 7.4
* Author: WordPress 投稿者
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: customblock-information
*
* @package CreateBlock
*/
インストール後、ダッシュボード上に見える内容は、この PHP ファイル冒頭のコメントアウトされた内容となります。一方の block.json に記載した "title"
や "description"
、"icon"
などの情報は、投稿画面のブロックインサーターに表示される内容になります。
混乱のないよう、この内容は block.json の内容と合わせることをおすすめします。
<?php
/**
* Plugin Name: 情報ブロック
* Description: 情報、警告、エラーメッセージを表示するブロック
* Version: 0.1.0
* Requires at least: 6.7
* Requires PHP: 7.4
* Author: (ご自身のお名前)
* License: GPL-2.0-or-later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: customblock-information
*
* @package CreateBlock
*/
ビルドとパッケージ化
開発したカスタムブロックを WordPress で動作させるには、事前にビルドしておく必要があります。以下のコマンドを使います。
wp-scripts build --blocks-manifest
このコマンドは、block.json
に定義された情報に基づき、JS をビルドして build/
フォルダに配置します。これで本番用のファイルが準備されます。
wp-scripts
はグローバルにインストールしているわけではないので、このままこのコマンドを実行しても動作しません。以下のように npx
を先頭に付けて、「このプロジェクトで導入した wp-scripts
である」ことを明示してください。
npx wp-scripts build --blocks-manifest
または、もしスキャフォールディングでプロジェクトを作成している場合は、 npm run build
という短縮名が定義されていますので、そちらでもOKです。
npm run build
wp-scripts plugin-zip
このコマンドを実行すると、プラグインとしてインストール可能な ZIP ファイルが生成されます。これは WordPress の「プラグイン > 新規追加 > プラグインのアップロード」から導入するための、「インストールファイル」になります。
これも同様に、 npx
を先頭に付けて実行してください。
npx wp-scripts plugin-zip
または、もしスキャフォールディングでプロジェクトを作成している場合は、 npm run plugin-zip
という短縮名が定義されていますので、そちらでもOKです。
npm run plugin-zip
実際の WordPress への導入手順
開発したカスタムブロックを実際の WordPress サイトで使うには、以下の手順でインストールします。
1. ZIP ファイルを用意
上記の plugin-zip
コマンドで作成された .zip
ファイル(例:custom-code-block.zip
)を準備します。
2. WordPress 管理画面からアップロード
WordPress の管理画面にログインし、ダッシュボードより:
- 「プラグイン」→「新規追加」
- 「プラグインのアップロード」を選択
- ZIP ファイルを選択してアップロード
- アップロードに成功したら、「有効化」にチェックを付ける
3. 投稿・固定ページでブロックを利用
投稿画面のブロックインサーターで「情報」と検索すれば、作成したブロックが追加されているはずです。選択すれば、作成した「情報コードブロック」が記事に挿入され、そこに内容を記載することができます。
まとめ
お疲れ様でした! 以下は、こんかい作成した WordPress の「カスタムコードブロック」です。
さて、こんかいでこのシリーズは一区切りとなります。自作コードブロックの作成手順は、今後も改良されていくことが予想されますが、今の段階でも、いちど手を動かしながら作成手順を学んでおけば、より柔軟に変化についていくこともできるようになることでしょう。
それでは、よきコーディングライフを!