WordPressでカスタムブロックを作成する

WordPressのブロックエディタでブロックを追加する方法を試してみます。
WordPressのバージョンは6.4.1を使用しています。

パッケージのインストール

今回は@wordpress/create-blockというパッケージを使用して、プラグインの形で追加していきます。
このパッケージは、カスタムブロックを追加するプラグインを作成するためのひな型として公式で用意されているツールになります。

まずターミナルでpluginsディレクトリへ移動して、create-blockをインストールします。

npx @wordpress/create-block add-block

今回は「add-block」という名前にしていますが、適宜変更してください。

少し待つとadd-blockフォルダが作成され、パッケージのインストールが完了します。
管理画面でプラグインを確認すると、Add Blockが追加されているのを確認できるので、有効にします。

ブロックエディタを確認してみると、ウェジットの項目にAdd Blockというブロックが追加されています。

ブロックを追加してみると、以下のような表示になります。

実際に投稿してみると、以下の内容で出力されました。

<p class="wp-block-create-block-add-block">Add Block – hello from the saved content!</p>

このように現時点ではひな形のまま使用しているので、特に意味のない内容になっています。

カスタムブロックの構成

カスタマイズしていく前に開発環境のファイル構成について確認してみます。
実際に変更していくのはsrcディレクトリ内で、ビルド後の内容がbuildディレクトリに出力されます。

• build
• src
  • block.json
  • edit.js
  • editor.scss
  • index.js
  • save.js
  • style.scss
• add-block.php

各ファイルの内容を確認してみます。(一部コメントなど省略しています。)
add-block.phpはプラグインとして動作するのに必要なファイルで、内容は以下の通りです。

<?php
/**
 * Plugin Name:       Add Block
 * Description:       Example block scaffolded with Create Block tool.
 * Requires at least: 6.1
 * Requires PHP:      7.0
 * Version:           0.1.0
 * Author:            The WordPress Contributors
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       add-block
 *
 * @package           create-block
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}

function add_block_add_block_block_init() {
	register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'add_block_add_block_block_init' );

先頭部分のコメントがプラグインの情報になるので、適宜変更してください。

次にsrc/block.jsonです。
このファイルは追加するブロックに関する情報を定義しています。

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	"apiVersion": 3,
	"name": "create-block/add-block",
	"version": "0.1.0",
	"title": "Add Block",
	"category": "widgets",
	"icon": "smiley",
	"description": "Example block scaffolded with Create Block tool.",
	"example": {},
	"supports": {
		"html": false
	},
	"textdomain": "add-block",
	"editorScript": "file:./index.js",
	"editorStyle": "file:./index.css",
	"style": "file:./style-index.css",
	"viewScript": "file:./view.js"
	}
}

例えばcategoryはブロックエディタでブロックの追加されるカテゴリ、titleやiconはそこに追加されたブロックのテキストやアイコンになります。
editorScriptやeditorStyle、styleは、カスタムブロックで使用するJavaScriptやCSSのパスになります。

次は上記のeditorScriptで指定されているsrc/index.jsです。

import { registerBlockType } from '@wordpress/blocks';

import './style.scss';

import Edit from './edit';
import save from './save';
import metadata from './block.json';

registerBlockType( metadata.name, {
	/**
	 * @see ./edit.js
	 */
	edit: Edit,

	/**
	 * @see ./save.js
	 */
	save,
} );

edit.jsとsave.jsをimportで取り込んでいます。

src/edit.jsはブロックエディタ上でのレンダリングに使用される内容になります。

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import './editor.scss';

export default function Edit() {
	return (
		<p { ...useBlockProps() }>
			{ __( 'Add Block – hello from the editor!', 'add-block' ) }
		</p>
	);
}

src/save.jsは投稿の保存時に使用されます。

import { useBlockProps } from '@wordpress/block-editor';

export default function save() {
	return (
		<p { ...useBlockProps.save() }>
			{ 'Add Block – hello from the saved content!' }
		</p>
	);
}

次にCSS(Sass)ファイルです。
src/style.scssはブロックエディタ上とサイトの両方に適用されます。

.wp-block-create-block-article {
	background-color: #21759b;
	color: #fff;
	padding: 2px;
}

ビルド後はファイル名が変わり、build/style-index.cssになります。

src/editor.scssはブロックエディタ上でのみ適用されます。

.wp-block-create-block-article {
	border: 1px dotted #f00;
}

こちらもビルド後はファイル名が変わり、build/index.cssになります。
以上が今回使用していくファイルです。

カスタムブロックの作成

では実際にひな形をカスタマイズしていきます。
ターミナルでadd-block(パッケージをインストールしたフォルダ)に移動して、開発環境を起動します。

npm run start

src/block.jsonにattributesの項目を追加します。

{
	"$schema": "https://schemas.wp.org/trunk/block.json",
	～略～
	"style": "file:./style-index.css",
	"viewScript": "file:./view.js",
	"attributes": {
		"message": {
			"type": "string",
			"source": "text",
			"selector": "div",
			"default": ""
		}
	}
}

attributesは保存方法について定義する項目で、上記の場合はmessage属性に対してtypeで型(文字列)、sourceでテキストフィールド、selectorでdivタグを指定しています。

attributesの内容はeditとsaveの両方の関数に渡して使用することができるので、src/edit.jsの内容を変更してみます。

import { __ } from '@wordpress/i18n';
import { useBlockProps } from '@wordpress/block-editor';
import { TextControl } from '@wordpress/components';
import './editor.scss';

export default function Edit({attributes, setAttributes}) {
	return (
		<div {...useBlockProps()}>
			<TextControl
				label={__('Message', 'add-block')}
				value={attributes.message}
				onChange={(val) => setAttributes({message: val})}
			/>
		</div>
	);
}

TextControlコンポーネントを使用していて、valueには先ほど設定したattributes.messageを設定、onChangeにはsetAttributesを使用してmessage属性の値が更新されるようにしています。

同じようにsrc/save.jsも変更します。

import { useBlockProps } from '@wordpress/block-editor';

export default function save({attributes}) {
	const blockProps = useBlockProps.save();
	return <div {...blockProps}>{attributes.message}</div>;
}

最後にsrc/style.scssで、背景をオレンジに変更してみます。

.wp-block-create-block-add-block {
	background-color: orange;
	color: #fff;
	padding: 2px;
}

これでカスタマイズができたので、実際に表示を確認してみます。
ブロックエディタでブロックを追加してみると、入力フィールドが表示されました。

「入力テスト」と入力して投稿してみると、サイト上の表示も問題なさそうでした。

サイト上に出力された内容は以下の通りです。

<div class="wp-block-create-block-add-block">入力テスト</div>