概要

Format APIは、開発者がフォーマットツールバーにカスタムボタンを追加し、それをテキスト選択にフォーマットを適用することを可能にします。太字はフォーマットツールバーの標準ボタンの一例です。

Format APIツールバーのアニメーション例

WordPress用語では、フォーマットは、テキスト選択に特別な意味を与えるために使用されるテキストレベルの意味を持つHTMLタグです。たとえば、このチュートリアルでは、フォーマットツールバーにフックされるボタンが特定のテキスト選択を<samp> HTMLタグでラップします。

始める前に

このガイドは、すでにWordPressプラグインとそれにJavaScriptを読み込むことに慣れていることを前提としています。復習するには、プラグインハンドブックまたはJavaScriptチュートリアルを参照してください。

必要なもの:

  • WordPress開発環境
  • 編集の準備が整った最小限のプラグイン
  • ビルドとエンキュー用のJavaScript設定

完全なformat-apiの例が利用可能で、セットアップの参考にできます。

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

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

ステップ1: 新しいフォーマットを登録する

最初のステップは新しいフォーマットを登録することです。次のようにsrc/index.jsを追加します: 

  1. import { registerFormatType } from '@wordpress/rich-text';
  3. registerFormatType( 'my-custom-format/sample-output', {
  4.    title: 'Sample output',
  5.    tagName: 'samp',
  6.    className: null,
  7. } );

利用可能なフォーマットタイプのリストはcore/rich-textストアに保持されています。ストアをクエリして、カスタムフォーマットが利用可能になっているか確認できます。

このコードをブラウザのコンソールで実行して確認してください: 

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

フォーマットタイプを含む配列が返されます。

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

フォーマットが利用可能になったので、次のステップは、編集プロパティのためにコンポーネントを登録してUIにボタンを追加することです。 

  3. ``````bash
  4. import { registerFormatType } from '@wordpress/rich-text';
  5. import { RichTextToolbarButton } from '@wordpress/block-editor';
  7. const MyCustomButton = ( props ) => {
  8.    return (
  9.    <RichTextToolbarButton
  10.    icon="editor-code"
  11.    title="Sample output"
  12.    onClick={ () => {
  13.    console.log( 'toggle format' );
  14.    } }
  15.    />
  16.    );
  17. };
  19. registerFormatType( 'my-custom-format/sample-output', {
  20.    title: 'Sample output',
  21.    tagName: 'samp',
  22.    className: null,
  23.    edit: MyCustomButton,
  24. } );
  25. `

すべてが期待通りに動作しているか確認しましょう。ビルドしてリロードし、段落ブロックのようなテキストを含む任意のブロックを選択します。新しいボタンがフォーマットツールバーに追加されたことを確認してください。

カスタムボタン付きツールバー

ボタンをクリックし、コンソールログで「トグルフォーマット」メッセージを確認します。

ボタンやメッセージが表示されない場合は、JavaScriptが正しくビルドされ、読み込まれているか再確認し、コンソールログでエラーメッセージを確認してください。

ステップ3: クリック時にフォーマットを適用する

次は、クリック時にフォーマットを適用するようにボタンを更新します。

私たちの例では、<samp>タグフォーマットはバイナリです - テキスト選択がタグを持っているかどうかですので、RichTextパッケージのtoggleFormatメソッドを使用できます。 

  3. ``````bash
  4. import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
  5. import { RichTextToolbarButton } from '@wordpress/block-editor';
  7. const MyCustomButton = ( { isActive, onChange, value } ) => {
  8.    return (
  9.    <RichTextToolbarButton
  10.    icon="editor-code"
  11.    title="Sample output"
  12.    onClick={ () => {
  13.    onChange(
  14.    toggleFormat( value, {
  15.    type: 'my-custom-format/sample-output',
  16.    } )
  17.    );
  18.    } }
  19.    isActive={ isActive }
  20.    />
  21.    );
  22. };
  24. registerFormatType( 'my-custom-format/sample-output', {
  25.    title: 'Sample output',
  26.    tagName: 'samp',
  27.    className: null,
  28.    edit: MyCustomButton,
  29. } );
  30. `

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

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

登録時にclassNameオプションを使用して、タグに独自のカスタムクラスを追加します。そのクラスとカスタムCSSを使用して、その要素をターゲットにし、スタイルを自由に設定できます。

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

デフォルトでは、ボタンはすべてのリッチテキストツールバー（画像キャプション、ボタン、段落など）にレンダリングされます。特定のタイプのブロックにのみボタンをレンダリングするには、データAPIを使用します。

以下は、段落ブロックにのみボタンを表示する例です: 

  1. import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
  2. import { RichTextToolbarButton } from '@wordpress/block-editor';
  3. import { useSelect } from '@wordpress/data';
  5. function ConditionalButton( { isActive, onChange, value } ) {
  6.    const selectedBlock = useSelect( ( select ) => {
  7.    return select( 'core/block-editor' ).getSelectedBlock();
  8.    }, [] );
  10.    if ( selectedBlock && selectedBlock.name !== 'core/paragraph' ) {
  11.    return null;
  12.    }
  14.    return (
  15.    <RichTextToolbarButton
  16.    icon="editor-code"
  17.    title="Sample output"
  18.    onClick={ () => {
  19.    onChange(
  20.    toggleFormat( value, {
  21.    type: 'my-custom-format/sample-output',
  22.    } )
  23.    );
  24.    } }
  25.    isActive={ isActive }
  26.    />
  27.    );
  28. }
  30. registerFormatType( 'my-custom-format/sample-output', {
  31.    title: 'Sample output',
  32.    tagName: 'samp',
  33.    className: null,
  34.    edit: ConditionalButton,
  35. } );

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

  3. ``````bash
  4. import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
  5. import { BlockControls } from '@wordpress/block-editor';
  6. import { ToolbarGroup, ToolbarButton } from '@wordpress/components';
  8. const MyCustomButton = ( { isActive, onChange, value } ) => {
  9.    return (
  10.    <BlockControls>
  11.    <ToolbarGroup>
  12.    <ToolbarButton
  13.    icon="editor-code"
  14.    title="Sample output"
  15.    onClick={ () => {
  16.    onChange(
  17.    toggleFormat( value, {
  18.    type: 'my-custom-format/sample-output',
  19.    } )
  20.    );
  21.    } }
  22.    isActive={ isActive }
  23.    />
  24.    </ToolbarGroup>
  25.    </BlockControls>
  26.    );
  27. };
  29. registerFormatType( 'my-custom-format/sample-output', {
  30.    title: 'Sample output',
  31.    tagName: 'samp',
  32.    className: null,
  33.    edit: MyCustomButton,
  34. } );
  35. `

トラブルシューティング

エラーが発生した場合:

  • まずnpm run buildを実行していることを再確認してください。
  • ビルドプロセスに構文エラーや問題がないことを確認してください。
  • エディタでJavaScriptが読み込まれていることを確認してください。
  • コンソールエラーメッセージを確認してください。

追加リソース

このガイドで使用された参考文献:

結論

このガイドでは、ツールバーにボタンを追加し、それを選択したテキストにフォーマットを適用する方法を示しました。試してみて、次のプラグインで何が作れるか見てみてください。

format-apiの例をblock-development-examplesリポジトリからダウンロードしてください。