WordPressで複合ブロック（InnerBlocks）とパターンを使いUI部品を再利用する方法

カード、料金表、CTA（申し込みへの誘導枠）のように、複数のブロックを組み合わせたUI部品をサイト内で使い回すには、用途に応じて「ブロックパターン」「同期パターン」「InnerBlocks を使った自作の複合ブロック」の3つを使い分けます。なお、WordPressに「CompositeBlock」という名前の公式APIはありません。この記事では、複数のブロックをまとめた部品を一般に「複合ブロック」と呼び、それぞれの作り方と選び方、構造を崩されないためのロックの設定、変更時に起きやすいエラーへの対処を説明します。

再利用の3つの方法と使い分け

まず、3つの方法の違いを整理します。

判断の目安は次のとおりです。

• 毎回中身を変える「ひな形」として使いたい: ブロックパターン。記事中の比較表やFAQの枠など
• 全ページで同じ内容を表示し、1か所で直したい: 同期パターン。共通のお知らせ枠やCTAなど
• 見た目と構造を固定し、編集者には中身だけを入力させたい: InnerBlocks の自作ブロック。デザインを崩されたくない社内向けの部品など

開発の手間が少ない順に試し、足りないときに次の方法へ進むのが現実的です。

方法1: ブロックパターンをテーマに登録する

テーマ（子テーマを含む）の patterns フォルダにPHPファイルを置くと、ファイル先頭のコメントを読み取ってパターンとして自動で登録されます（WordPress 6.0以降）。

<?php
/**
 * Title: 紹介カード
 * Slug: mysite/feature-card
 * Categories: featured
 * Description: 画像・見出し・説明文・ボタンをまとめたカード
 */
?>
<!-- wp:group {"className":"mysite-card","layout":{"type":"constrained"}} -->
<div class="wp-block-group mysite-card">
	<!-- wp:image {"sizeSlug":"medium"} -->
	<figure class="wp-block-image size-medium"><img alt=""/></figure>
	<!-- /wp:image -->
	<!-- wp:heading {"level":3} -->
	<h3 class="wp-block-heading">カードの見出し</h3>
	<!-- /wp:heading -->
	<!-- wp:paragraph -->
	<p>ここに説明文が入ります。</p>
	<!-- /wp:paragraph -->
	<!-- wp:buttons -->
	<div class="wp-block-buttons"><!-- wp:button -->
	<div class="wp-block-button"><a class="wp-block-button__link wp-element-button">詳しく見る</a></div>
	<!-- /wp:button --></div>
	<!-- /wp:buttons -->
</div>
<!-- /wp:group -->

ブロックのマークアップを手で書くのは間違えやすいので、一度エディター上で部品を組み立て、コードエディターに切り替えてコピーすると間違いを減らせます。Slug には他と重ならない接頭辞を付けてください。テーマを使わずに登録したい場合は、プラグインから register_block_pattern() を init フックで呼ぶ方法もあります。

パターンは挿入した時点で通常のブロックとしてページに展開されるため、後からパターンのファイルを修正しても、既に挿入済みのページは変わりません。

方法2: 同期パターンで1か所の修正を全体に反映する

同期パターンは、かつて「再利用ブロック」と呼ばれていた機能です。エディターで部品を選択し、ブロックのオプションメニューからパターンを作成する際に「同期」を有効にすると、挿入したすべての箇所が同じ元データを参照します。元を編集すると、使われているページすべての表示が変わります。

同期パターンのデータは wp_block という投稿タイプとしてデータベースに保存されるため、テーマを変更しても残ります。

全箇所が同じ内容になるのが基本ですが、WordPress 6.6 以降では、パターンの中の特定のブロックについて「上書き」を許可すると、デザインは共通のまま見出しや本文だけをページごとに変えられるようになりました。この機能は内部的には Block Bindings API の core/pattern-overrides ソースを使っています。設定項目の名前や対応ブロックはバージョンによって変わるため、利用中の環境で確認してください（2026年10月現在）。

注意点として、同期パターンを編集すると影響範囲がサイト全体に及びます。修正前に、どのページで使われているかを把握しておくと安心です。

方法3: InnerBlocks で構造を固定した複合ブロックを作る

「見出しの位置を動かされたくない」「ボタンを消されたくない」といった要望には、自作ブロックの中にコアブロックを並べる InnerBlocks が向いています。外側のブロックが構造を決め、中の段落や画像は編集者が普通に入力できます。

開発環境は、公式の @wordpress/create-block で作るのが手軽です。Node.js が入った環境で次のように実行すると、block.json やビルド設定を含むプラグインのひな形ができます。

npx @wordpress/create-block@latest mysite-card

生成された src/edit.js を、テンプレートを持つ InnerBlocks に書き換えます。

import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

const TEMPLATE = [
	[ 'core/image', {} ],
	[ 'core/heading', { level: 3, placeholder: 'カードの見出し' } ],
	[ 'core/paragraph', { placeholder: '説明文を入力' } ],
	[ 'core/buttons', {}, [ [ 'core/button', { text: '詳しく見る' } ] ] ],
];

export default function Edit() {
	const blockProps = useBlockProps( { className: 'mysite-card' } );
	const innerBlocksProps = useInnerBlocksProps( blockProps, {
		template: TEMPLATE,
		templateLock: 'all',
	} );

	return <div { ...innerBlocksProps } />;
}

src/save.js では、中のブロックをそのまま保存します。

import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor';

export default function save() {
	const blockProps = useBlockProps.save( { className: 'mysite-card' } );
	const innerBlocksProps = useInnerBlocksProps.save( blockProps );

	return <div { ...innerBlocksProps } />;
}

npm run build でビルドし、プラグインを有効化するとインサーターに表示されます。

templateLock の選び方

templateLock で、編集者にどこまで変更を許すかを決めます。

• 'all': ブロックの追加・削除・並べ替えができない。中身の入力はできる
• 'insert': 追加と削除はできないが、並べ替えはできる
• 'contentOnly': テキストや画像など内容の編集だけを許可し、デザイン設定も触らせない
• false: ロックしない（テンプレートは初期配置としてだけ使われる）

迷ったら 'all' から始め、現場で「ボタンを2つにしたい」といった声が出たら緩めるとよいでしょう。中に入れてよいブロックの種類だけを制限したい場合は、allowedBlocks を指定します。

変更時のブロック検証エラーに注意する

自作ブロックで最もつまずきやすいのが、公開後に save.js の出力を変えたときに起きる「このブロックには、想定されていないか無効なコンテンツが含まれています」という表示です。ブロックエディターは、保存済みのHTMLと現在の save が出力するHTMLを比べ、一致しないと検証エラーにします。たとえばクラス名を1つ追加しただけでも、既存の投稿すべてでエラーになります。

公開後に出力を変える場合は、deprecated に旧バージョンの save を残しておくと、既存のブロックが自動で新しい形式に移行されます。見た目の変更だけで済むなら、マークアップは変えずにCSSだけを修正するのが安全です。

作業はステージング環境で行い、既存の投稿を開いてエラーが出ないことを確認してから本番に反映してください。同期パターンや自作ブロックの変更はサイト全体に影響するため、反映前にデータベースのバックアップも取っておきます。

まとめ

• WordPressに「CompositeBlock」という公式APIはなく、複合的なUI部品はパターンか InnerBlocks で作る
• ひな形として使うならブロックパターン、1か所の修正を全体に反映したいなら同期パターン
• 構造を固定したいなら InnerBlocks の自作ブロックを作り、template と templateLock で制御する
• 同期パターンの「上書き」を使うと、デザインを共通にしたまま中身だけページごとに変えられる
• 自作ブロックの save を変えるとブロック検証エラーになるため、deprecated で旧形式を残す

• WordPressのブロックパターンを作成する方法
• WordPressのテンプレートパーツとエリアの使い方