【WordPress】Gutenberg をカスタマイズするための情報

1. はじめに

WordPress の バージョン 5 から、「Gutenberg」というツールを使って記事を編集するようになりました。

本記事では、Gutenberg をカスタマイズするための情報をまとめていきます。

2. ツールバーにボタンを追加する

記事編集中、

1. 特定の文字列を選択し 、
2. ツールバー上に用意したボタンを押すと、
3. その部分が <span class="foo"> と </span> で囲まれて（ソースコードレベルで）
4. foo クラスで定義された視覚的効果が与えられる

といった動作を自作する方法です。

これを実現する方法は、gutenberg/docs/designers-developers/developers/tutorials/format-api at master · WordPress/gutenberg（リンク切れ）に書いてあり、基本的にはこれを真似ればできます。

但し、2019年5月時点では、1つのHTML要素に対して複数のボタンを登録することができないようです。例えば <span class="foo">...</span> を挿入するボタンと、<span class="bar">...</span> を挿入するボタンを両方追加することはできません（バグ？）。Gutenberg のリポジトリに対策コードが追加されていますが、まだ WordPress のリリースには組み込まれていません（下記リンク先を参照）。

使えるアイコン

• Dashicons | WordPress Developer Resources

情報源

• gutenberg/docs/designers-developers/developers/tutorials/format-api at master · WordPress/gutenberg（リンク切れ）
• Fix 13776: Format is already registered to handle class name by gziolo · Pull Request #15072 · WordPress/gutenberg

関連ソースコード

• gutenberg/register-format-type.js at master · WordPress/gutenberg
• gutenberg/selectors.js at master · WordPress/gutenberg

3. 自作ブロックを追加する

gutenberg/docs/designers-developers/developers/tutorials/block-tutorial（リンク切れ）にあるドキュメントを読んで真似することで自作ブロックを追加することができます。

wp-cli を使って雛形を生成する

WP-CLI には、ブロックの雛形ファイルを生成するコマンドが用意されています。

コマンド例

wp scaffold block my-block --title="MyBlock" --plugin=my-plugin

• my-block は、このブロックの内部的な名前になります。
• --title="MyBlock" では、このブロックの名前を指定しています。
• --plugin=my-plugin では、既に存在している my-plugin というプラグインの中にブロックの雛形ファイルを追加することを指示しています。

参考

• wp-cli/scaffold-command: Generates code for post types, taxonomies, blocks, plugins, child themes, etc.
• gutenberg/generate-blocks-with-wp-cli.md at master · WordPress/gutenberg（リンク切れ）

情報源

• gutenberg/docs/designers-developers/developers/tutorials/format-api at master · WordPress/gutenberg（リンク切れ）

関連ソースコード

• gutenberg/register-format-type.js at master · WordPress/gutenberg
• gutenberg/selectors.js at master · WordPress/gutenberg

4. フィルタを使って既存の機能に手を加える

既存の機能に手を加えたい場合は、フィルターフックが使えます。いろいろな種類のフックにフィルター処理を追加することにより、対象となる値を変更することができます。

以下は、Block Filters に載っているサンプルコードに説明を加えたものです。

PHPコード

add_action( 'init', function() {
        // JSファイルを事前に登録する
	wp_register_script(
                // 登録するJSファイルの登録名
		'my-filter-js',
                // 登録するJSファイル
		plugins_url( 'my-filter.js', __FILE__ ),
                // 依存しているスクリプト(wp-includes/script-loader.php 内で登録されている)
		array( 'wp-rich-text', 'wp-element', 'wp-editor', 'wp-compose', 'wp-data' )
	);
});

add_action( 'enqueue_block_editor_assets', function() {
        // 登録したJSファイルを読み込む
	wp_enqueue_script( 'my-filter-js' );
});

my-filter.js ファイル

/**
 * Block type 'core/image' の要素に手を加える
 *
 * @param {object} element
 * @param {object} blockType
 * @param {object} attributes
 *
 * @return The element.
 */
function convertImageUrlToRelative( element, blockType, attributes ) {
        // 目的のブロックでなければ何もせず element を返す
	if ( 'core/image' !== blockType.name ) {
		return element;
	}

        // ブロックが 'core/image' であれば、element に手を加える

	// （ここのコードは省略）

        // element を返す
	return element;
}

wp.hooks.addFilter(
        // フック名 (hookName)
	'blocks.getSaveElement',
        // 名前空間 (namespace)
	'my-filters/do-something',
        // コールバック関数
	convertImageUrlToRelative
);

関連ソースコード

• gutenberg/register-format-type.js at master · WordPress/gutenberg
• gutenberg/selectors.js at master · WordPress/gutenberg

情報源

• Block Filters | Block Editor Handbook | WordPress Developer Resources
• wp_register_script() | Function | WordPress Developer Resources
• wp_enqueue_script() | Function | WordPress Developer Resources
• @wordpress/hooks | Block Editor Handbook | WordPress Developer Resources

5. 関連情報