段落ブロックをちょっとだけカスタマイズした

説明

ブロックエディターを使っていくと、段落ブロックの文字修飾機能が物足りない。そこで今回は標準の段落ブロックを機能拡張し、選択したテキスト範囲をマーカーで線を引くイメージの機能を実装してみた。

ブロックエディターハンドブックを読む

いきなり独自ブロックを実装するのは大変そうなので、手始めに既存ブロックのカスタマイズをしようと思う。検索サイトを使って断片的なページはいくつか見つかったが、全体像を理解するうえで「フォーマット API 入門」が役に立った。

enqueue_block_editor_assetsアクションを使う

今回の実装は独自プラグインとし、PHPファイルは次の通り。JavaScriptファイルの読み込みは、enqueue_block_editor_assetsアクションを使用して wp_enqueue_script関数で行っている。

<?php
/**
 * Plugin Name: 段落ブロック向けのマーカー
 */

function paragraph_marker_enqueue_editor_assets() {
	wp_enqueue_script( 'paragraph-marker-js',
		plugins_url( 'paragraph-marker.js', __FILE__ ),
		array( 'wp-rich-text' )
	);
}

add_action( 'enqueue_block_editor_assets', 'paragraph_marker_enqueue_editor_assets' );

ここでのポイントは、wp_enqueue_script関数の第3パラメータに依存関係があるパッケージ名を指定するところ。現実的には省略しても問題なく動作すると思われるが、JavaScriptファイルがロードされる順番に影響するので、できるだけ正確に記述するのが無難だろう。

registerFormatType関数で「文字修飾」を登録

上記で指定したparagraph-marker.js（ES5）の内容はまずは次の通りとする。

( function ( wp ) {
	var paragraphMarkingButton = function ( props ) {
		return wp.element.createElement(
			wp.blockEditor.RichTextToolbarButton,
			{
				icon: 'admin-customizer',
				title: 'マーキング',
				onClick: function () {
					props.onChange(
						wp.richText.toggleFormat(
							props.value,
							{
								type: 'paragraph-ex/marking',
							}
						)
					);
					props.onFocus();
				},
			}
		);
	}

	wp.richText.registerFormatType(
		'paragraph-ex/marking',
		{
			title: 'マーキング',
			tagName: 'mark',
			className: null,
			edit: paragraphMarkingButton
		}
	);
} )( window.wp );

wp.richText.registerFormatType関数は、段落ブロックの本文部分を構成するリッチテキスト（エディター）に文字修飾を登録する関数である。リッチテキストの選択範囲に対して何らかの処理を行う場合はこの関数が便利そうだ。

registerFormatType関数の第1パラメータには文字修飾のタイプ名を「〇〇/〇〇」の形式でユニークなものを指定する。もしタイプ名が「/」で挟まれていない場合はエラーになるので注意が必要だ。

registerFormatType関数の第2パラメータには文字修飾の設定内容を示すオブジェクトを指定する。オブジェクトの内容としてtitleには文字修飾の名前を、tagNameには選択範囲を囲むHTML要素の名前を指定する。classNameにはそのHTML要素のclass属性値を指定し、class属性が不要な場合はnullを指定する（classNameプロパティそのものを省略するとエラーになる）。editには文字修飾を変更する関数（イベントハンドラ）を指定する。

editプロパティのpropsパラメータが働き者

上記のeditプロパティに指定したparagraphMarkingButton関数は、フォーカスを受け取ったり、文字が入力されたりといった多くのタイミングで頻繁に呼び出される。処理内容としては、propsというパラメータを受け取り、wp.element.createElement関数でUI要素を生成して、それを返すだけだ。

createElement関数の第1パラメータには、UI要素を生成する関数名かHTML要素の名前を指定する。上記で指定したwp.blockEditor.RichTextToolbarButton関数（コンポーネント）は、従来リッチテキストのツールバーにボタン要素を生成していたが、現在はツールバーの「_ｖ」ボタンをクリックして表示されるメニュー要素を生成するように変更されている。

またWordPress 5.3より前のバージョンではwp.editor.RichTextToolbarButton関数が使用されていたが、現在こちらは非推奨となっており、こちらを使用している場合はブラウザの検証ツールのコンソールに次のメッセージが出力される。

wp.editor.RichTextToolbarButton is deprecated since version 5.3. Please use wp.blockEditor.RichTextToolbarButton instead.

createElement関数の第2パラメータには、生成するUI要素の設定内容を示すオブジェクトを指定する。 オブジェクトの内容としてiconにはアイコン名（dashiconsのクラス名から先頭の'dashicons-'を取ったもの）を、titleにはメニューに表示される名前を指定する。この2つはどちらも省略可能である（両方を省略した場合はメニュー項目が空になる）。またメニュー内容の表示位置は、titleの内容でソートされるようになっている。

onClickにはメニューがクリックされた際に呼び出されるイベントハンドラを指定する。このイベントハンドラでは、wp.richText.toggleFormat関数を使ってmark要素で囲む／mark要素を外すのトグル処理した内容をprops.onChange関数を呼び出してリッチテキストを更新。その後、props.onFocus関数を呼び出し、リッチテキストにフォーカスを移している。このonFocus関数の呼び出しは、参考にした「フォーマット API 入門」には記載されていないが、ツールバーのボタンやメニューをクリックすると、そのUI要素にフォーカスが移ったままになるので、リッチテキストにフォーカスを戻す方が使い勝手はよい。

さてcreateElement関数の第3パラメータには子要素を指定できるが、ツールバーのボタンやメニューの場合はそのような要素が不要なため、ここでは省略している。

mark要素向けのスタイルを追加

mark要素のスタイルは、Chromeのデフォルトでは背景色が黄色に設定されている。このままでは少し味気ないので、ピンクの蛍光マーカーで線を引いた雰囲気にしてみた。

実際にPHPファイルに追加したコードは次の通り。ブロックエディター向けはadmin_footerアクションで、フロントエンド側にはwp_footerアクションでインラインスタイルを出力している。

function paragraph_marker_footer_style() {
?>
<style type="text/css">
mark { background: linear-gradient(transparent 50%, #ffa0a0 60%, #ffd0d0 90%, transparent); }
</style>
<?php
}

global $pagenow;
if ( is_admin() && in_array( $pagenow, array( 'post.php', 'post-new.php' ) ) ) {
	add_action( 'admin_footer', 'paragraph_marker_footer_style', 999 );
}

add_action( 'wp_footer', 'paragraph_marker_footer_style', 999 );

今回は標準の段落ブロックに文字修飾として「マーキング」を追加してみた。テキストに文字修飾を付け外す処理はtoggleFormat関数に任せられるので、開発者はregisterFormatType関数で指定するtagNameとclassNameの組み合わせ、そのスタイル内容に集中できる。ブロックエディターのカスタマイズ方法が少しわかってきた感じだ。（続き）