WordPressのテーマでカスタムブロックパターンを登録する方法

自作のブロックパターンをテーマに登録するには、テーマの patterns フォルダにPHPファイルを置く方法と、register_block_pattern() 関数で登録する方法の2つがあります。WordPress 6.0 以降であれば、ファイルを置くだけで読み込まれる patterns フォルダ方式が扱いやすく、おすすめです。この記事では、パターンの中身の作り方、ファイルの書き方、独自カテゴリーの登録、翻訳と画像の扱い、表示されないときの確認方法までを、テーマ開発者の立場から説明します。

既存テーマに同梱されたパターンを使う側の操作は、別記事「Twenty Twenty-Fourテーマでパターンブロックを活用してページを作る方法」で扱っています。本記事はパターンを作って登録する側の話です。

作業前の準備

配布されているテーマ（Twenty Twenty-Four や市販テーマなど）を直接編集すると、テーマの更新で追加したファイルが消えます。既存テーマにパターンを足したい場合は、子テーマを作ってそちらに置いてください。自作テーマであれば、テーマのフォルダに直接追加して構いません。

また、本番サイトで試す前に、ローカル環境やステージング環境で動作を確認し、本番に反映する前にはバックアップを取っておくと安心です。

パターンの中身はエディターで作ってコピーする

パターンの実体は、ブロックエディターが保存するブロックのマークアップ（<!-- wp:paragraph --> のようなコメント付きのHTML）です。手で書くと記述の誤りでブロックが壊れやすいため、次の手順で作るのが確実性の高い方法です。

1. 投稿や固定ページの編集画面で、パターンにしたいレイアウトをブロックで組みます。
2. 外側のグループブロックを選び、ツールバーのオプションメニューから「コピー」を選びます。あるいは、右上のオプションメニューから「コードエディター」に切り替えて、該当部分を選択してコピーします。
3. コピーしたマークアップを、次の手順で作るパターンファイルに貼り付けます。

色や余白は、パレットの色やテーマのプリセットから選んでおくのがコツです。任意のカラーコードを直接指定すると、サイトのスタイルを変えたときにそのパターンだけ取り残されます。

patternsフォルダにファイルを置いて登録する

テーマ（または子テーマ）のフォルダに patterns フォルダを作り、その中に hero-cta.php のようなファイルを置きます。ファイルの先頭のコメントに、パターンの情報を書きます。

<?php
/**
 * Title: ヒーロー（ボタン付き）
 * Slug: mytheme/hero-cta
 * Categories: mytheme-sections, banner
 * Keywords: ヒーロー, 見出し, ボタン
 * Description: 大きな見出しと説明文、ボタンを並べたセクションです。
 * Viewport Width: 1200
 */
?>
<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
	<!-- wp:heading {"textAlign":"center","level":2} -->
	<h2 class="wp-block-heading has-text-align-center"><?php echo esc_html__( 'サービスの特長を一言で', 'mytheme' ); ?></h2>
	<!-- /wp:heading -->

	<!-- wp:paragraph {"align":"center"} -->
	<p class="has-text-align-center"><?php echo esc_html__( 'ここに説明文が入ります。', 'mytheme' ); ?></p>
	<!-- /wp:paragraph -->

	<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
	<div class="wp-block-buttons">
		<!-- wp:button -->
		<div class="wp-block-button"><a class="wp-block-button__link wp-element-button" href="<?php echo esc_url( home_url( '/contact/' ) ); ?>"><?php echo esc_html__( 'お問い合わせ', 'mytheme' ); ?></a></div>
		<!-- /wp:button -->
	</div>
	<!-- /wp:buttons -->
</div>
<!-- /wp:group -->

先頭コメントの主な項目は次のとおりです。

• Title（必須）：挿入ツールに表示される名前。
• Slug（必須）：テーマ名/パターン名 の形で、ほかと重ならない識別子を付けます。
• Categories：表示するカテゴリーのスラッグをカンマ区切りで書きます。banner や call-to-action などのコアのカテゴリーも指定できます。
• Keywords：検索でヒットさせたい語。
• Description：パターンの説明。
• Viewport Width：一覧でのプレビューの幅。
• Block Types：特定のブロックに関連付けるときに使います。core/post-content を指定すると、新規ページ作成時に表示されるページ全体のパターンの候補になります。
• Post Types：特定の投稿タイプでのみ使えるように絞り込みます。
• Inserter：no にすると挿入ツールには表示されず、テンプレートからの読み込み専用になります。

パターンファイルはPHPとして実行されるため、上の例のように翻訳関数やURLを出力する関数を使えます。テーマで表示する文字列は esc_html__() などでエスケープし、URLは esc_url() を通して出力してください。

このフォルダ方式はブロックテーマでもクラシックテーマでも使えますが、念のため自分の環境で挿入ツールに表示されるかを確認してください（2026年10月現在）。

独自のカテゴリーを登録する

上の例の mytheme-sections のような独自カテゴリーは、別途登録が必要です。テーマの functions.php に次を追加します。

<?php
add_action( 'init', function () {
	register_block_pattern_category(
		'mytheme-sections',
		array( 'label' => __( 'マイテーマ：セクション', 'mytheme' ) )
	);
} );

カテゴリーを登録しないままスラッグを指定すると、パターンは未分類扱いの場所に表示され、探しにくくなります。

register_block_pattern()で登録する方法

WordPress 6.0 より前の環境に対応する必要がある場合や、条件によって登録する・しないを切り替えたい場合は、register_block_pattern() を使います。マークアップを文字列として渡すため、別ファイルに書いた内容を読み込む形にすると、引用符のエスケープで悩まずに済みます。

<?php
add_action( 'init', function () {
	$file = get_theme_file_path( 'pattern-parts/hero-cta.html' );
	if ( ! file_exists( $file ) ) {
		return;
	}
	register_block_pattern(
		'mytheme/hero-cta-legacy',
		array(
			'title'      => __( 'ヒーロー（ボタン付き）', 'mytheme' ),
			'categories' => array( 'mytheme-sections' ),
			'keywords'   => array( 'hero', 'cta' ),
			'content'    => file_get_contents( $file ),
		)
	);
} );

patterns フォルダ方式と同じスラッグで二重に登録しないよう注意してください。同じスラッグが重なると、どちらかが登録されず、意図しない内容が表示される原因になります。

不要なパターンを非表示にする

自作パターンだけを並べたい場合は、WordPress コアが提供するパターンや、パターンディレクトリから読み込まれるパターンを止められます。

<?php
add_action( 'after_setup_theme', function () {
	// コア同梱のパターンを無効化
	remove_theme_support( 'core-block-patterns' );
} );

// WordPress.org のパターンディレクトリからの読み込みを止める
add_filter( 'should_load_remote_block_patterns', '__return_false' );

子テーマから親テーマのパターンを個別に外したいときは、unregister_block_pattern( 'スラッグ' ) を使います。親テーマのパターンが登録された後に実行する必要があるため、init フックの優先度を大きめ（例：20）にして呼び出します。

表示されないときの確認ポイント

パターンが挿入ツールに出てこない場合は、次の順に確認します。

• 先頭コメントの書式：Title: と Slug: があるか、コメントがPHPの開始タグの直後にあるかを確認します。項目名の綴りの誤りもよくある原因です。
• Inserter の指定：Inserter: no にしていないか。
• キャッシュ：WordPress 6.4 以降は、テーマのパターンファイルの一覧がキャッシュされるため、新しく追加したファイルがすぐに反映されないことがあります。開発環境では wp-config.php に define( 'WP_DEVELOPMENT_MODE', 'theme' ); を書くとキャッシュが使われなくなります。本番環境では設定せず、テーマのバージョン番号を上げて反映させるのが一般的です。
• ブロックの記述の誤り：挿入はできても「想定されていないか無効なコンテンツ」といった警告が出る場合は、マークアップのクラス名や属性の対応が崩れています。エディターで作り直してコピーし直すのが早道です。
• PHPのエラー：パターンファイルの記述ミスでエラーが出ていないか、開発環境で WP_DEBUG を有効にして確認します。

まとめ

• テーマへのパターン登録は、WordPress 6.0 以降なら patterns フォルダにPHPファイルを置く方式が扱いやすく、先頭コメントの Title と Slug が必須です。
• パターンの中身はエディターで組んでからコピーし、色や余白はプリセットから選んでおきます。
• 独自カテゴリーは register_block_pattern_category() で登録し、文字列のエスケープと翻訳関数を忘れずに使います。
• 古い環境や条件付きの登録には register_block_pattern() を使い、スラッグの重複に注意します。
• 表示されないときは、先頭コメント、Inserter、6.4以降のキャッシュ、ブロックの記述の順に確認します。配布テーマに追加する場合は子テーマで作業してください。

• WordPressで子テーマを作成する方法
• WordPressでFSE対応のブロックテーマを作る方法