オリジナルブロックを作る

ブロックエディターに、独自のブロック（オリジナルブロック）を追加します。

全体像

オリジナルブロックは2つの部分でできています。

ブロックメニューに表示するかどうかは、管理者が編集設定で選びます。 プラグイン側は「使える種類を提供する」までを行い、メニューへの表示は設定に任せる形です。

ブロックの定義と要素の定義を登録する

次の例は、注意書きを目立たせる「コールアウト」ブロックを追加します。ブロックの定義と要素の定義は、どちらも setup(ctx) の中で登録します。

ACMS.adminReady(() => {
  ACMS.plugins.register('acme-blocks', {
    setup(ctx) {
      // 要素の定義: エディターが扱える「callout」要素を追加する
      ctx.blockEditor.registerExtension('callout', ({ core }) =>
        core.Node.create({
          name: 'callout',
          group: 'block',
          content: 'paragraph+',
          parseHTML: () => [{ tag: 'div[data-callout]' }],
          renderHTML: () => ['div', { 'data-callout': '' }, 0],
        })
      );

      // ブロックの定義: メニューに出すラベルと、挿入したときの動作
      ctx.blockEditor.registerBlockDefinition('callout', () => ({
        label: 'コールアウト',
        description: '注意書きを目立たせるブロック',
        icon: 'info',
        isTextMenu: false,
        aliases: ['callout', 'note'],
        createActions: (cmd, actionCtx) => ({
          action: (editor) => {
            actionCtx.recordUsage(cmd);
            editor
              .chain()
              .focus()
              .insertContent({ type: 'callout', content: [{ type: 'paragraph' }] })
              .run();
          },
          convert: () => {},
          isDisabled: (editor) => editor.isActive('callout'),
          isActive: (editor) => editor.isActive('callout'),
        }),
      }));
    },
  });
});

ブロックの定義に指定できる項目は次のとおりです。

createActions が返すもの:

上の例のように、他のブロックからの変換に対応しない場合は、convert を何もしない関数にします。

既存のブロック（段落・見出し・画像など）の組み合わせで表現できる場合は、要素の定義（registerExtension）は不要で、ブロックの定義（registerBlockDefinition）だけで足ります。

ブロックエディターは Tiptap をベースにしています。要素の定義方法は Tiptap のドキュメントを参照してください。

ブロックメニューに表示する

登録しただけではメニューに出ません。管理画面で表示する設定を行います。

1. 管理画面の「編集設定」→「ブロックエディター設定」→「ブロックメニュー」を開きます。編集画面セットを使っているサイトでは、使っているセットの「ブロックエディター設定」を開きます（使っていないセットに保存しても、メニューには出ません）。
2. 「追加」で行を増やし、「ブロック」の選択肢から、登録したブロックを選びます。選択肢には**「プラグイン」の分類**が追加されており、ブロックの定義の label（例: 「コールアウト」）で表示されます。
3. 保存します。

PHP 側の追加実装は必要ありません。 選択肢は、登録されているブロックの種類から自動的に作られます。

保存した HTML からタグが消える場合

ブロックが出力する HTML は、保存時や表示時に、不正な HTML を防ぐための仕組み（HTML のサニタイズ）を通ります。多くの標準の HTML 要素と、Ver. 3.2.36 以降では data- で始まる属性が、そのまま通ります。上の例の <div data-callout> も、Ver. 3.2.36 以降では設定なしで保存されます。Ver. 3.2.35 以前では、data- 属性も次の Hook で許可が必要です（$def->addAttribute('div', 'data-callout', 'CDATA');）。

独自の要素名（例: <acme-note>）や、標準にない属性を出力する場合は、取り除かれないように PHP 側で許可します。extension/acms/Hook.php に、次のメソッドを追加してください。

public function extendsHtmlPurifierDefinition(\HTMLPurifier_HTMLDefinition $def, \HTMLPurifier_Config $config): void
{
    $def->addElement('acme-note', 'Block', 'Flow', 'Common');
}

許可する要素・属性の定義はキャッシュされます。変更したあとは、ダッシュボードからキャッシュをクリアしてください。詳細は フック処理 を参照してください。

関連ページ

• ブロックエディターの基本 — ブロックエディター自体の使い方
• 機能の登録（レジストリ）
• 開発環境と型定義 — TypeScript で書く場合

変更履歴