【WordPress】PHPファイルで管理！ブロックパターンを自作・自動登録

2026年8月18日2026年8月24日

【WordPress】PHPファイルで管理！ブロックパターンを自作・自動登録する実践ガイド

WordPressのブロックエディタ（Gutenberg）で、レイアウト崩れを防ぎつつ効率的な運用を実現する最強の手法が「カスタム・ブロックパターン」の活用です。

プラグインを使わずに、テーマ内にPHPファイルとしてブロックパターンを定義・自動登録する実装フローに絞って解説します。

1. なぜ「ファイル管理」でブロックパターンを作るのか？

管理画面から登録する簡易的な方法もありますが、テーマ内にコード（ファイル）として管理することで以下のメリットが得られます。

Gitでコード管理・バージョン管理ができる
本番環境とローカル環境での同期・展開がスムーズ
PHP関数やショートコードを組み込んだ動的なロジックが書ける

2. ディレクトリ構造の設計

パターン本体（HTML/PHP）、CSS、JS、および登録ロジックをきれいに分離した構造を作ります。

wp-content/themes/your-theme/
  ├── functions.php
  ├── patterns/               ← パターン本体（1ファイル = 1パターン）
  │   ├── sec-title.php
  │   └── card-grid.php
  ├── inc/
  │   └── block-patterns.php  ← 自動読み込み・登録＆CSS/JS読込処理
  └── assets/
      ├── css/
      │   ├── block-patterns.css ← パターン共通・固有スタイル
      │   └── editor-style.css   ← エディタ表示調整用CSS（任意）
      └── js/
          └── block-patterns.js  ← アコーディオン等の共通・固有JS

3. パターンファイルの作成

patterns/ フォルダの中に、作成したいパーツごとのPHPファイルを用意します。

パターン定義の例（patterns/card-grid.php）

ファイルの先頭にタイトルやディスクリプションなどを記述し、配下にブロック構造を定義します。

「WordPressのブロックコメント（等）の書き方がわからない…」という場合でも問題ありません。例えばFigmaのデザインデータからAI（Cursorなど）に指示を投げれば、そのままパターン登録用のPHPファイルを一瞬で生成できます。

<?php
/**
 * Title: 特長紹介（画像＋テキスト3列）
 * Slug: mytheme/card-grid
 * Categories: mytheme-parts
 * Description: 3列並びのカード型コンポーネント
 */
?>
<!-- wp:group {"className":"custom-card-grid"} -->
<div class="wp-block-group custom-card-grid">
  <!-- wp:heading {"level":2} -->
  <h2>ここにタイトルが入ります</h2>
  <!-- /wp:heading -->
  
  <!-- wp:image -->
  <figure class="wp-block-image"><img src="https://via.placeholder.com/600x400" alt=""/></figure>
  <!-- /wp:image -->

  <!-- wp:paragraph -->
  <p>ここに説明文が入ります。</p>
  <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

4. CSSとJSの書き方

ブロックパターンの見た目（CSS）や動き（JS）は、「表側のサイト（フロント）」と「管理画面の編集エリア（エディタ）」の両方に適用させると、クライアントが編集する際にわかりやすくなり、良いと思います。

CSSの書き方（assets/css/block-patterns.css）

フロント表示と管理画面エディタ（.editor-styles-wrapper）の双方でデザインを一致させるため、:is() を使ってスコープを絞るのがおすすめです。

/* パターン用のCSS例 */
:is(.entry-content, .editor-styles-wrapper) .custom-card-grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 20px;
}

JSの書き方（assets/js/block-patterns.js）

アコーディオンやトグルメニューなど動的な装飾をする場合は、管理画面側のプレビューでも動くようにイベントを定義します。

document.addEventListener('DOMContentLoaded', () => {
  // アコーディオン等の発火処理
});

5. パターンの自動登録とCSS/JSの読み込み処理

inc/block-patterns.php を作成し、「独自カテゴリの登録」「PHPファイルの一括自動登録」「CSS/JSのフロント・エディタ両方への読み込み」をまとめて記述します。この記述により、管理画面で一つひとつパターンを登録しなくても自動で一括登録されます。

<?php
/**
 * ブロックパターンの自動登録 & CSS/JS読み込み処理
 */

function mytheme_register_block_patterns() {
    // 独自カテゴリの登録
    register_block_pattern_category(
        'mytheme-parts',
        array( 'label' => __( 'カスタム共通パーツ', 'mytheme' ) )
    );

    // patternsディレクトリ内のPHPファイルをすべて取得して登録
    $pattern_files = glob( get_theme_file_path( '/patterns/*.php' ) );

    foreach ( $pattern_files as $file ) {
        register_block_pattern_from_file(
            'mytheme/' . basename( $file, '.php' ),
            $file
        );
    }
}
add_action( 'init', 'mytheme_register_block_patterns' );

/**
 * パターン用CSS/JSの読み込み（フロント & エディタ両方）
 */
function mytheme_enqueue_pattern_assets() {
    // CSSの読み込み
    wp_enqueue_style(
        'mytheme-pattern-styles',
        get_theme_file_uri( '/assets/css/block-patterns.css' ),
        array(),
        '1.0.0'
    );

    // JSの読み込み
    wp_enqueue_script(
        'mytheme-pattern-scripts',
        get_theme_file_uri( '/assets/js/block-patterns.js' ),
        array(),
        '1.0.0',
        true
    );
}
// 表側（フロント）への適用
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_pattern_assets' );
// 管理画面エディタへの適用
add_action( 'enqueue_block_editor_assets', 'mytheme_enqueue_pattern_assets' );

最後に、functions.php でこのファイルを読み込みます。

// functions.php
require_once get_theme_file_path( '/inc/block-patterns.php' );

6. 実際の運用フロー（管理画面でのパターン配置手順）

プログラム側の準備が完了したら、実際にWordPressの管理画面からページを組み立てていきます。

投稿・固定ページの編集画面を開く
新規作成または既存の固定ページ編集画面を開きます。
ブロック追加ボタン（＋）をクリック
画面左上の「＋」（ブロック挿入ツール）アイコンをクリックします。
「パターン」タブを選択
パネル上部にある「ブロック」の隣の「パターン」タブに切り替えます。
独自カテゴリを選択
カテゴリのドロップダウンまたはリストから、登録した「カスタム共通パーツ」（プログラムで指定したカテゴリ名）を選択します。
配置したいパターンをクリック
登録したパターンのサムネイル/プレビュー一覧が表示されるので、挿入したいパーツをクリック（またはエディタ上にドラッグ＆ドロップ）します。
テキストや画像を差し替えて保存
エディタ上に挿入されたブロックの仮テキストや画像を、実際のコンテンツに書き換えてプレビュー確認後、公開します。