ブロックエディターの基本ブロック

ブロックエディターでは、スラッシュコマンド（/）の入力やブロックメニューから、さまざまな種類のブロックを挿入できます。ここでは、基本とレイアウトのブロックについて説明します。

基本

段落

Ver. 3.2.0 以降で利用できます。

通常のテキストを記述するためのブロックです。デフォルトのブロックタイプであり、見出しやリスト以外のテキストは段落として扱われます。Enter を押すと次の段落になり、Shift + Enter で改行が挿入されます。

<p>...</p>

見出し

Ver. 3.2.0 以降で利用できます。

見出しレベル1〜6に対応するブロックです。文書の構造化やアウトラインの作成に使用します。

リスト

Ver. 3.2.0 以降で利用できます。

順序なしリスト（箇条書き）を挿入します。

<ul><li>...</li></ul>

番号付きリスト

Ver. 3.2.0 以降で利用できます。

順序付きリストを挿入します。

<ol><li>...</li></ol>

引用

Ver. 3.2.0 以降で利用できます。

引用文を記述するためのブロックです。

<blockquote>...</blockquote>

コード

Ver. 3.2.0 以降で利用できます。

コードブロックを挿入します。等幅フォントで表示され、改行やスペースがそのまま保持されます。

<pre><code>...</code></pre>

画像

Ver. 3.2.0 以降で利用できます。

メディアから画像を挿入するブロックです。メディアライブラリと連携し、大元のメディアで画像を差し替えると同一メディアIDを持つすべての画像ブロックが自動で更新されます。

編集メニューで設定できる項目：

• 配置: 左・中央・右

• 画像サイズ: 編集画面設定 > ブロックエディター設定で登録した選択肢（例: 100%, 75%, 66%）から選択。

• キャプション・代替テキスト: アクセシビリティやSEOのためにも設定を推奨

• リンク: 画像クリック時のリンク先、別タブで開くの有無

• 拡大表示: デフォルトで有効。SmartPhoto によるライトボックス表示。

• メイン画像に設定: 編集画面にメディアのカスタムフィールド（blockEditorConfig.setMainImageMark で指定）がある場合、そのフィールドに選択中の画像をセット可能

その他：

• HTMLをコピー&ペーストしたとき、画像のURLが自サイト内の同一パスに存在するファイルを指している場合、相対パスに自動変換される

• ペーストやURLで挿入した画像（メディア未登録）は、画像を選択した状態で表示されるアップロードボタンからメディアライブラリに登録できる

<div class="media-image-block align-{left|center|right}" data-type="imageBlock" data-align="..." data-width="..." data-mid="..." data-eid="..." data-no-lightbox="false">
  <figure style="max-width: ...;">
    <a href="..."><img src="..." alt="..." loading="lazy" data-mid="..." /></a>
    <figcaption class="caption">...</figcaption>
  </figure>
</div>

ファイル

Ver. 3.2.0 以降で利用できます。

メディアからファイル（PDF、Word、Excel など）を挿入するブロックです。画像以外のファイルをダウンロードリンクとして配置できます。

表示形式：

• アイコン表示（デフォルト）: ファイル種別のアイコンとキャプションを表示

• ボタン表示: リンク風のボタンとして表示。キャプションの設定が必須

編集メニューで設定できる項目：

• 配置: 左・中央・右（デフォルト: 左）

• キャプション・代替テキスト: ボタン表示時はキャプションがリンクテキストになる

• 別タブで開く: リンクを target="_blank" で開くかどうか

• メディア選択・編集: メディアライブラリからファイルを選択・差し替え

<div class="media-file-block align-{left|center|right}" data-type="fileBlock" data-display-type="icon|button" data-icon="..." data-extension="..." data-file-size="...">
  <a href="...">
    <img src="..." alt="..." />
    <p class="caption">...</p>
  </a>
</div>

※ 別タブで開くが有効な場合は target="_blank" と rel="noopener noreferrer" が付与されます。

リンクボタン

Ver. 3.2.0 以降で利用できます。

ボタン風のリンクを挿入するブロックです。ブロック内でテキストを直接編集でき、そのテキストがボタンのラベルになります。CTA（Call to Action）やダウンロードリンクなどに適しています。

編集メニューで設定できる項目：

• 配置: 左・中央・右（デフォルト: 中央）

• リンクURL: クリック時の遷移先

• 別タブで開く: target="_blank" の有無

操作：

• ブロックを選択してテキストを入力すると、ボタンに表示される文言を編集できる

• Enter で次のブロックへ、Backspace で空の場合はブロック削除

<div class="link-button-block align-{left|center|right}" data-type="linkButton" data-align="...">
  <a href="..." class="link-button-block-link" data-type="button">ボタンのテキスト</a>
</div>

テーブル

Ver. 3.2.0 以降で利用できます。

表を挿入するブロックです。デフォルトで3行×3列のテーブルが作成されます。行・列の追加・削除、セルの結合、ヘッダー行の設定、横スクロール表示の設定が可能です。

<div class="tableWrapper"><table>...</table></div>

区切り線

Ver. 3.2.0 以降で利用できます。

文章の途中に区切り線を挿入するブロックです。セクションの区切りなどに使用します。

<div data-type="horizontalRule"><hr></div>

レイアウト

1カラム

Ver. 3.2.20 以降で利用できます。

コンテンツを1カラムの枠で囲みます。枠の中では通常どおりブロックの追加・編集ができます。ブロックタイプの設定でクラスを指定すると、そのクラスを付けた枠として挿入できるため、背景色や余白を付けた囲みを作るときに使えます。

初期設定ではブロックメニューに表示されません。利用する場合は、編集画面設定 > ブロックエディター設定 のブロックタイプに「1カラム」を追加してください。

<div data-type="columns" data-layout="one-column">
  <div data-type="column">...</div>
</div>

2カラムに分割

Ver. 3.2.0 以降で利用できます。

コンテンツを2カラムのレイアウトに分割します。各カラム内で通常通りブロックの追加・編集が可能です。

<div data-type="columns" data-layout="two-column">
  <div data-type="column">...</div>
  <div data-type="column">...</div>
</div>

3カラムに分割

Ver. 3.2.0 以降で利用できます。

コンテンツを3カラムのレイアウトに分割します。

<div data-type="columns" data-layout="three-column">
  <div data-type="column">...</div>
  <div data-type="column">...</div>
  <div data-type="column">...</div>
</div>

グループ

Ver. 3.2.36 以降で利用できます。

複数のブロックを 1 つのグループにまとめられます。グループごとに HTML 要素とクラス名を指定でき、グループ内・外のブロック移動にも対応しています。セクションや装飾用コンテナとして、まとまりのあるコンテンツを作る場合に使用します。

選択できる要素は div、section、article、aside、header、footer、nav です。section、aside、nav には、内容を区別できるよう aria-label を設定できます。

出力HTML

section を選び、クラス名とラベルを設定した場合は次のように出力されます。

<section data-type="group" data-tag="section" class="section-intro" aria-label="サービス紹介">
  <h2>サービス紹介</h2>
  <p>...</p>
</section>

その他の基本ブロック

HTML

Ver. 3.2.36 以降で利用できます。

HTML を直接入力して、編集画面内でプレビューを確認できます。テキストブロックとは別に、HTML を明示的に編集したい場合に使用します。

保存するHTML

HTML ブロックは、編集用の機能タグとして保存されます。data-block-props には、入力したHTMLを含むJSONをBase64でエンコードした値を指定します。

<acms-block-editor-function-tag
  data-block-type="html"
  data-block-props="eyJodG1sIjoiPHA+5Lu75oSP44GuSFRNTDwvcD4ifQ==">
</acms-block-editor-function-tag>

公開時のHTML

公開時には機能タグが展開され、html に指定した内容がそのまま出力されます。

<p>任意のHTML</p>

危険なタグの除去（strip_dangerous_tag）が on の場合は、公開時に HTMLPurifier を通り、許可リストにない iframe・script などは削除されます（新規インストール時の既定は on）。

編集画面のプレビュー

HTML ブロックのプレビューは、管理画面を保護するため sandbox を適用した iframe 内で表示します。そのため、YouTube など外部サービスの埋め込み、外部スクリプト、外部サイトとの通信を利用する HTML は、プレビューでは正しく表示・動作しないことがあります。必ず閲覧ページで確認してください。プレビューに閲覧画面と同じスタイルを適用する方法は、HTML ブロックのプレビューにスタイルを適用するを参照してください。

CSV・APIから入稿する場合

CSVインポートなど編集画面を通さずに登録する場合は、data-block-props を作る代わりに、入稿用タグ <acms-block-editor-html-block> でHTMLを囲んで指定できます。取り込み時に上記の機能タグへ変換して保存されるため、編集画面ではHTMLブロックとして表示・編集できます。

<acms-block-editor-html-block>
  <div class="custom">任意のHTML</div>
</acms-block-editor-html-block>

• タグの中身は加工せず、そのままHTMLブロックの内容になります（前後の空白は除きます）。閉じていないタグや <script> の中身も書いたとおりに保持されます。

• 中身は最初の </acms-block-editor-html-block> までです。HTMLブロックを入れ子にすることはできません（入れ子にした場合は警告が出ます）。

• 危険なタグの除去など公開時のサニタイズは、通常のHTMLブロックと同じです。

埋め込み（oEmbed）

Ver. 3.2.36 以降で利用できます。

ブロックメニューまたはスラッシュコマンドから「埋め込み」を選び、外部サービスの URL を貼り付けます。配置、表示サイズ、キャプションを設定できます。

主な対応サービス

URL から oEmbed で埋め込み情報を取得し、サイトの許可リスト（iframe・script の許可ホスト）に合う場合に埋め込みとして表示します。既定の設定で埋め込みとして表示できる主なサービスは次のとおりです。

• 動画: YouTube、Vimeo

• SNS: X、TikTok、Bluesky

• 音声: Spotify、SoundCloud

対応状況や返される形式は、各サービス側の仕様変更により変わることがあります。

保存するHTML

埋め込みブロックも編集用の機能タグとして保存されます。data-block-props には URL、タイトル、提供元、埋め込みHTML、配置、表示サイズ、キャプションなどをJSONとして持ちます。手作業で作るより、ブロックエディターで作成した値やエクスポートした値を利用することを推奨します。

<acms-block-editor-function-tag
  data-block-type="embed"
  data-block-props="...">
</acms-block-editor-function-tag>

公開時のHTML

許可された埋め込みHTMLがある場合は、figure 内の data-embed-content に展開されます。埋め込みHTMLが取得できない、または許可されない場合は、URL・タイトル・説明などを使ったリンクカードとして出力されます。

<div class="embed-block align-left" data-type="embedBlock" data-url="..." data-provider="..." data-align="left" data-width="100%">
  <figure style="width: 100%; max-width: 100%;">
    <div data-embed-content="" style="width: 100%;">...</div>
    <figcaption class="caption">...</figcaption>
  </figure>
</div>

埋め込みHTMLを取得できない、または許可されていない場合は、次の構造のリンクカードとして出力されます。見た目はテーマ側で実装してください。

<div class="embed-block-card acms-embed-link not-editor-style">
  <div class="embed-block-card-image-container acms-embed-link-image-container">
    <img src="..." alt="" loading="lazy" decoding="async">
  </div>
  <div class="embed-block-card-content acms-embed-link-content">
    <a href="..." class="embed-block-card-title acms-embed-link-title">タイトル</a>
    <span class="embed-block-card-provider acms-embed-link-site-name">提供元</span>
    <span class="embed-block-card-description acms-embed-link-description">説明</span>
  </div>
</div>

編集画面のプレビュー

• iframe だけで構成される埋め込み（YouTube など）は、そのまま編集画面に表示します。

• script を使う埋め込み（X、TikTok、Bluesky など）は、サーバーで再サニタイズした HTML を隔離した iframe 内で表示します。管理画面を保護するため、プレビューで実行する script は、公開側の許可ホストのうち埋め込みウィジェットの配信元（block_editor_embed_preview_script_allowed_hosts）に限ります。

• プレビューできない場合は、「プレビューできません」というメッセージと URL のリンクを表示します。

埋め込み先の仕様によっては、プレビューと閲覧ページで表示や動作が異なることがあります。必ず閲覧ページで確認してください。

CSV・APIから入稿する場合

埋め込みは、URLを指定した入稿用タグ <acms-block-editor-embed-block> で指定できます。取り込み時に、編集画面でURLを貼り付けたときと同じ仕組みで埋め込み情報を取得し、埋め込みブロックとして保存します。

<acms-block-editor-embed-block url="https://www.youtube.com/watch?v=xxxxxxxxxxx"></acms-block-editor-embed-block>

• url は必須です。id・class を指定するとブロックに引き継がれます。

• 埋め込みHTMLが取得できず、OGPなどのページ情報だけ取得できた場合は、リンクカードとして保存されます。

• URLが不正な場合や取得に失敗した場合は、インポートを止めずに通常のリンクの段落へ変換し、警告を残します（http・https 以外のURLはリンクにせず、文字列として残します）。

• 埋め込み情報を取得するのは取り込み時の一度だけで、公開時に外部へ取りに行くことはありません。同じURLは一度の取り込みの中で繰り返し取得しません。

• 閉じタグは省略できます。タグの中身を書いた場合、中身は埋め込みには使われず通常の本文として残ります。

ブロックエディターのHTMLをデータとして登録する

ブロックエディターは、入力したHTMLを編集用のデータとして保存し、公開時に画像・ファイル・埋め込みなどを必要なHTMLへ整形して出力します。CSVインポートや外部システムからの登録では、このページにある編集用HTMLをフィールド値として登録してください。閲覧ページに出力されたHTMLをコピーするのではなく、エディターで保存・エクスポートされたHTMLを使うと、再編集できる状態を保てます。

CSVインポートでは、カスタムフィールドは フィールド名@block-editor、本文ユニットは unit@block-editor[1] の列にHTMLを入れます。CSVではセル内のHTMLをCSVの規則に従って引用符で囲みます。

entry_title,my_block_field@block-editor,unit@block-editor[1]
サンプル,"<p>カスタムフィールドの本文</p>","<h2>本文の見出し</h2><p>本文</p>"

APIなどからブロックエディターフィールドへ登録する実装でも、同じ編集用HTMLを渡します。段落・見出し・リスト・グループなどはこのページのHTML例を組み合わせて生成できます。HTMLブロックと埋め込みブロックは、data-block-props を生成する代わりに、上記の入稿用タグ（<acms-block-editor-html-block> / <acms-block-editor-embed-block>）を使えます。（入稿用タグは Ver. 3.2.36 以降で利用できます）

CSVインポートで埋め込みの取得に失敗した行は、処理ログに警告が表示され、「失敗した行をダウンロード」の対象になります。インポート完了時には「メディア取込のみ失敗した件数」と「埋め込みの取得のみ失敗した件数」が別々に表示されます。ドライランでは埋め込みの取得は行わず、URLの形式だけを確認します。

画像・ファイルブロックでは data-mid などメディアに紐づく情報も保存されます。別環境へ移す場合は、メディアのインポートとIDの対応付けもあわせて行ってください。

プラグイン（拡張アプリ）から入稿用タグを追加する

Ver. 3.2.36 以降で利用できます。

独自ブロックを追加したプラグイン（拡張アプリ）では、block-editor.authoring-tags にハンドラ（Acms\Services\BlockEditor\Contracts\AuthoringTagHandler の実装）を登録すると、独自の入稿用タグをCSVインポートなどで使えるようになります。同じタグ名を登録するとコアの入稿用タグも差し替えられます。独自に本文を登録する処理を実装する場合は、Application::make('block-editor.authoring')->convert($html) を通すと、CSVインポートと同じ変換が行われます。

// 拡張アプリの ServiceProvider::init()
use Acms\Services\BlockEditor\Authoring\AuthoringContext;
use Acms\Services\BlockEditor\Authoring\AuthoringTag;
use Acms\Services\BlockEditor\Contracts\AuthoringTagHandler;
use Acms\Services\BlockEditor\FunctionTag;

Application::make('block-editor.authoring-tags')->register(new class implements AuthoringTagHandler {
    public function getTagName(): string
    {
        return 'my-plugin-callout'; // カスタム要素名（acms-block-editor- 以外の接頭辞）
    }

    public function convert(AuthoringTag $tag, AuthoringContext $context): string
    {
        return FunctionTag::render('my-plugin-callout', [
            'tone' => $tag->attribute('tone', 'info'),
            'body' => $context->convert(trim($tag->innerHtml)),
        ]);
    }
});

AuthoringTag からは属性（attribute()）とタグの中身（innerHtml）を、AuthoringContext からは警告の記録（warn()）や中身の入稿用タグの変換（convert()）を利用できます。公開時の展開は block-editor.function-tags に登録したハンドラが、編集画面での表示は対応するTiptap拡張が担います。