書式ツールバー API

概要

書式 API (Format API) を使用すると開発者は、書式ツールバーにカスタムボタンを追加し、選択したテキストに対して「書式」(format) を適用できます。たとえば「太字」は、書式ツールバーの標準ボタンの一例です。

WordPress の世界で「書式」とは、テキストレベルのセマンティクスでの HTML タグを指します。選択したテキストに特別な意味を与えられます。たとえばこのチュートリアルでは、書式ツールバーにフックされたボタンが、選択したテキストを <samp> HTML タグでラップします。

はじめる前に

このガイドでは、すでに WordPress プラグインと JavaScript の読み込みに精通していることを前提としています。必要に応じて、プラグインハンドブックまたは JavaScript チュートリアルを参照してください。

以下が必要です。

WordPress 開発環境
最小のプラグインの有効化と、編集可能なセットアップ
JavaScript のビルドとエンキューが可能なセットアップ

セットアップのリファレンスとして、完全な書式 API サンプルを参照してください。

ステップバイステップガイド

このガイドでは、変更対象の JavaScript ファイルを src/index.js として参照します。各ステップの後で npm run build を実行すると build/index.js が作成され、投稿エディタ画面に読み込まれます。

ステップ 1: 新しい書式を登録する

まず、新しい書式を登録するために、src/index.js に以下を追加します。

import { registerFormatType } from '@wordpress/rich-text';

registerFormatType( 'my-custom-format/sample-output', {
	title: 'Sample output',
	tagName: 'samp',
	className: null,
} );

利用可能な書式タイプの一覧は core/rich-text ストア内で管理されます。ストアを照会し、作成したカスタム書式が利用可能かどうかを確認できます。

ブラウザーのコンソールで以下を実行してください。

wp.data.select( 'core/rich-text' ).getFormatTypes();

作成したものを含む書式タイプの配列が返されます。

ステップ 2: ツールバーにボタンを追加する

書式が利用可能になったところで、 UI にボタンを追加します。edit プロパティにコンポーネントを登録します。

RichTextToolbarButton コンポーネントを使用して、src/index.js を更新してください。

import { registerFormatType } from '@wordpress/rich-text';
import { RichTextToolbarButton } from '@wordpress/block-editor';

const MyCustomButton = ( props ) => {
	return (
		<RichTextToolbarButton
			icon="editor-code"
			title="Sample output"
			onClick={ () => {
				console.log( 'toggle format' );
			} }
		/>
	);
};

registerFormatType( 'my-custom-format/sample-output', {
	title: 'Sample output',
	tagName: 'samp',
	className: null,
	edit: MyCustomButton,
} );

期待どおりに動作するかを確認します。ビルドし、リロードし、テキストを内部に含む任意のブロック、例えば段落ブロックを選択してください。書式ツールバーに新しいボタンが追加されていることを確認してください。

ボタンをクリックし、console.log のメッセージ「toggle format」をチェックしてください。

ボタンやメッセージが見つからない場合、正しく JavaScript をビルドし、ロードしていることを再度確認してください。また console.log に他のエラーがないか確認してください。

ステップ 3: クリックされたら書式を適用する

次にボタンを更新して、クリックされた時に書式を適用します。

この例で <samp> タグ書式は、選択したテキストがタグを持つか持たないかの2つの状態を取ります。そこで、RichText パッケージから toggleFormat メソッドを使用します。

src/index.js を更新し、onClick アクションを変更します。

import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
import { RichTextToolbarButton } from '@wordpress/block-editor';

const MyCustomButton = ( { isActive, onChange, value } ) => {
	return (
		<RichTextToolbarButton
			icon="editor-code"
			title="Sample output"
			onClick={ () => {
				onChange(
					toggleFormat( value, {
						type: 'my-custom-format/sample-output',
					} )
				);
			} }
			isActive={ isActive }
		/>
	);
};

registerFormatType( 'my-custom-format/sample-output', {
	title: 'Sample output',
	tagName: 'samp',
	className: null,
	edit: MyCustomButton,
} );

動作していることを確認します。まず、ビルドしてリロードし、次にテキスト選択をして、ボタンをクリックします。ブラウザは、周囲のテキストとは異なる方法で選択したテキストを表示するはずです。

また、HTMLビュー（コードエディタで Ctrl＋Shift＋Alt＋M）に切り替えると、選択したテキストがHTMLタグ<samp>で囲まれていることを確認できます。

登録の際に className オプションを使用すると、タグにカスタムクラスを追加できます。このクラスとカスタム CSS を使用して、要素に対して希望のスタイルを適用できます。

ステップ 4: 特定のブロックにのみボタンを表示する (オプション)

デフォルトではボタンはすべてのリッチテキストツールバー、たとえば画像のキャプション、ボタン、段落等でレンダーされます。特定のタイプのブロックでのみボタンをレンダーできます。これには data API を使用します。

次のサンプルコードは、「段落」ブロックでのみボタンを表示します。

import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
import { RichTextToolbarButton } from '@wordpress/block-editor';
import { useSelect } from '@wordpress/data';

function ConditionalButton( { isActive, onChange, value } ) {
	const selectedBlock = useSelect( ( select ) => {
		return select( 'core/block-editor' ).getSelectedBlock();
	}, [] );

	if ( selectedBlock && selectedBlock.name !== 'core/paragraph' ) {
		return null;
	}

	return (
		<RichTextToolbarButton
			icon="editor-code"
			title="Sample output"
			onClick={ () => {
				onChange(
					toggleFormat( value, {
						type: 'my-custom-format/sample-output',
					} )
				);
			} }
			isActive={ isActive }
		/>
	);
}

registerFormatType( 'my-custom-format/sample-output', {
	title: 'Sample output',
	tagName: 'samp',
	className: null,
	edit: ConditionalButton,
} );

ステップ5: ドロップダウンの外側にボタンを追加する (オプション)

RichTextToolbarButton コンポーネントを使用すると、ボタンはデフォルトではドロップダウンメニューに追加されます。BlockControls コンポーネントを使用すると、ボタンを直接ツールバーに追加できます。

import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
import { BlockControls } from '@wordpress/block-editor';
import { ToolbarGroup, ToolbarButton } from '@wordpress/components';

const MyCustomButton = ( { isActive, onChange, value } ) => {
	return (
		<BlockControls>
			<ToolbarGroup>
				<ToolbarButton
					icon="editor-code"
					title="Sample output"
					onClick={ () => {
						onChange(
							toggleFormat( value, {
								type: 'my-custom-format/sample-output',
							} )
						);
					} }
					isActive={ isActive }
				/>
			</ToolbarGroup>
		</BlockControls>
	);
};

registerFormatType( 'my-custom-format/sample-output', {
	title: 'Sample output',
	tagName: 'samp',
	className: null,
	edit: MyCustomButton,
} );