書式ツールバー API
Topics
- 概要
- はじめる前に
- ステップバイステップガイド
- トラブルシューティング
- 追加リソース
- まとめ
概要
書式 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,
} );
トラブルシューティング
エラーが発生する場合は、
- 最初に
npm run buildを実行したか、ダブルチェックしてください。 - ビルドプロセスで、構文エラーや問題が発生していないことを確認してください。
- JavaScript がエディター内にロードしていることを確認してください。
- コンソールにエラーメッセージが出ていないか確認してください。
追加リソース
このガイドで使用した参考文書です。
- RichText:
registerFormatType - Components:
RichTextToolbarButton - RichText:
applyFormat - RichText:
removeFormat - RichText:
toggleFormat
まとめ
このガイドでは、ツールバーにボタンを追加し、選択したテキストに書式を適用する方法を紹介しました。ぜひ試してみて、次にプラグインでどんなものが作れるか考えてみてください。
gutenberg-examples リポジトリから、書式 API サンプル をダウンロードしてください。
最終更新日: