【WordPress】register_block_style の使い方｜ブロックにスタイルバリエーションを追加する方法

ブロックエディターで引用ブロックやボタンブロックを選ぶと、サイドバーに「スタイル」という項目が現れ、「デフォルト」「大」といった見た目の候補を切り替えられます。この候補は自分で増やすことができ、その登録に使うのが register_block_style() です。この記事では、PHP でスタイルを追加する基本の書き方から、引数の意味、CSS の当て方、既存スタイルを消す unregister_block_style()、JavaScript 版との使い分けまでを順に解説します。

ブロックスタイルは is-style-〇〇 クラスの付け外しでできている

ブロックスタイル（スタイルバリエーション）は、難しい仕組みではありません。ユーザーがサイドバーでスタイルを選ぶと、そのブロックのラッパー要素に is-style-〇〇 というクラスが1つ付くだけです。あとはそのクラスに CSS を当てれば、見た目が切り替わります。

たとえば引用ブロックに blue-quote という名前のスタイルを登録し、それを選ぶと、保存される HTML は次のようになります。wp-block-quote はブロック本来のクラス、is-style-blue-quote が登録したスタイルによって追加されたクラスです。

<blockquote class="wp-block-quote is-style-blue-quote">
  <p>引用したい文章がここに入ります。</p>
</blockquote>

つまり、やることは「スタイルの候補をエディターに登録する」ことと「そのクラス向けの CSS を用意する」ことの2つです。register_block_style() はこの両方をまとめて面倒を見てくれます。

register_block_style の基本的な使い方

register_block_style() は WordPress 5.3 で追加された関数で、第1引数に対象のブロック名、第2引数にスタイルの設定を配列で渡します。ブロックの登録が済んだあとに呼ぶ必要があるので、init アクションフックの中で実行します。

<?php
add_action( 'init', 'mytheme_register_block_styles' );

function mytheme_register_block_styles() {
    register_block_style(
        'core/quote', // 対象のブロック名（名前空間から書く）
        array(
            'name'         => 'blue-quote',  // is-style-blue-quote になる
            'label'        => '青い引用',      // サイドバーに表示される名前
            'inline_style' => '.wp-block-quote.is-style-blue-quote { border-left: 4px solid #2271b1; color: #2271b1; }',
        )
    );
}

これだけで、引用ブロックを選択したときのサイドバーに「青い引用」が追加されます。name に指定した文字列がそのままクラス名の後ろに付き、is-style-blue-quote が出力されます。label は編集者が目にする表示名なので、日本語で分かりやすく付けて構いません。

inline_style に書いた CSS は、WordPress が編集画面とフロント側の両方で読み込みます。エディター用に別途 CSS を用意しなくても、その場で見た目が反映されるのがこの関数の便利なところです。

第2引数に指定できる項目

第2引数 $style_properties に渡せるキーは次のとおりです。実質的に必要なのは name と label、そして CSS を渡すための inline_style か style_handle のどちらかです。

name にスペースを含めると登録が失敗し、_doing_it_wrong() の警告が出ます。クラス名の一部になる以上、blue-quote のようなハイフン区切りにしておくのが安全です。

WordPress 6.6 からは第1引数に配列を渡せるようになり、array( 'core/quote', 'core/pullquote' ) のように書けば、同じスタイルを複数のブロックにまとめて登録できます。

is_default を使うときの注意

is_default を true にしたスタイルは「何も選んでいない状態＝このスタイル」という扱いになります。そのため、そのスタイルを選んでいる間は is-style-〇〇 クラスが HTML に出力されません。既定にしたスタイルの CSS は is-style- 付きのセレクタではなく、.wp-block-quote のようなブロック本来のクラスに当てる必要があります。この点を知らないと「既定にした途端に見た目が消えた」ということが起こります。

CSS を別ファイルで管理する（style_handle）

スタイルが増えてくると、CSS を PHP の文字列で書き続けるのは苦しくなります。そんなときは、あらかじめ wp_register_style() でスタイルシートを登録しておき、そのハンドル名を style_handle に渡します。

<?php
add_action( 'init', 'mytheme_register_block_styles' );

function mytheme_register_block_styles() {
    // まず CSS ファイルをハンドル名付きで登録しておく（読み込みはまだしない）
    wp_register_style(
        'mytheme-block-styles',
        get_theme_file_uri( '/css/block-styles.css' ),
        array(),
        '1.0.0'
    );

    register_block_style(
        'core/quote',
        array(
            'name'         => 'blue-quote',
            'label'        => '青い引用',
            'style_handle' => 'mytheme-block-styles', // 上で登録したハンドル名
        )
    );
}

.wp-block-quote.is-style-blue-quote {
  border-left: 4px solid #2271b1;
  padding-left: 16px;
  color: #2271b1;
  font-style: normal;
}

style_handle で指定したスタイルシートも、inline_style と同じく編集画面とフロントの両方で読み込まれます。複数のブロックスタイルで1つの CSS ファイルを共有したい場合は、それぞれの register_block_style() で同じハンドル名を指定すれば問題ありません。

ボタンブロックに独自スタイルを追加する

実際によくあるのは、ボタンブロックに自社デザインのバリエーションを足すケースです。ボタンブロックはブロック名が core/button（ボタンをまとめる親は core/buttons）で、リンク要素に wp-block-button__link クラスが付きます。is-style- クラスが付くのは外側の .wp-block-button なので、セレクタは「外側のクラス＋内側のリンク」という形になります。

<?php
add_action( 'init', 'mytheme_register_button_styles' );

function mytheme_register_button_styles() {
    register_block_style(
        'core/button',
        array(
            'name'         => 'arrow',
            'label'        => '矢印つき',
            'inline_style' => '
                .wp-block-button.is-style-arrow .wp-block-button__link {
                    position: relative;
                    padding-right: 40px;
                }
                .wp-block-button.is-style-arrow .wp-block-button__link::after {
                    content: "→";
                    position: absolute;
                    right: 16px;
                }
            ',
        )
    );
}

登録したあとにボタンブロックを選択すると、サイドバーの「スタイル」に「矢印つき」が並びます。選ぶだけで矢印付きのボタンになるので、編集する人が CSS クラスを手入力する必要がなくなり、表記ゆれも起きません。同じ考え方で、見出しブロック（core/heading）や段落ブロック（core/paragraph）にも自由にスタイルを足せます。

不要なスタイルを一覧から外す

逆に、使わせたくないスタイルを候補から消したいこともあります。そのための関数が unregister_block_style() で、ブロック名とスタイル名の2つを渡します。

<?php
add_action( 'init', 'mytheme_unregister_block_styles', 20 ); // 登録より後の優先度で呼ぶ

function mytheme_unregister_block_styles() {
    unregister_block_style( 'core/quote', 'blue-quote' );
}

ただし、この PHP 版で外せるのは register_block_style() でサーバー側に登録されたスタイルだけです。コアのブロックが最初から持っている「大きい引用」のようなスタイルは、ブロック側の定義としてエディターに読み込まれるため、PHP から外そうとしても消えないことがあります。コアの既定スタイルを確実に消したい場合は、次に説明する JavaScript の unregisterBlockStyle() を使います。

// エディターの準備が終わってから実行する
wp.domReady( function () {
    // 引用ブロックの「大」スタイルを候補から外す
    wp.blocks.unregisterBlockStyle( 'core/quote', 'large' );
} );

<?php
// エディター画面でだけ JS を読み込む
add_action( 'enqueue_block_editor_assets', 'mytheme_enqueue_editor_js' );

function mytheme_enqueue_editor_js() {
    wp_enqueue_script(
        'mytheme-editor',
        get_theme_file_uri( '/js/editor.js' ),
        array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ), // 依存を明示する
        '1.0.0',
        true
    );
}

依存に wp-edit-post を入れ、処理を wp.domReady() で包むのは、ブロックが登録され切る前に解除を実行してしまう競合を避けるためです。ここを省くと、環境やタイミングによって「消えたり消えなかったり」する不安定な挙動になります。

JavaScript の registerBlockStyle との違い

スタイルの登録には JavaScript 版の wp.blocks.registerBlockStyle() もあります。書き方はほぼ同じで、キー名がキャメルケース（isDefault）になる点が違います。

wp.domReady( function () {
    wp.blocks.registerBlockStyle( 'core/quote', {
        name: 'blue-quote',
        label: '青い引用',
    } );
} );

両者の一番の違いは「CSS の面倒を見てくれるかどうか」です。JavaScript 版は編集画面のスタイル候補に項目を足すだけで、CSS には一切関与しません。そのため、フロント用と編集画面用の CSS を自分で読み込む処理を別に書く必要があります。一方 PHP 版は inline_style や style_handle を渡せば、WordPress が編集画面とフロントの両方に読み込んでくれます。

もう1つの違いは、登録が行われる場所です。PHP 版はサーバー側の登録なので、テーマやプラグインの PHP だけで完結し、ビルド環境も要りません。JavaScript 版はエディターが読み込まれたときにブラウザ上で登録されます。

使い分けとしては、スタイルの追加は PHP の register_block_style() を基本にするのが分かりやすく、既存スタイルの削除など JavaScript でしかできない操作だけを JS 側に書く、という形が扱いやすいでしょう。両方で同じ name を登録すると設定が上書きし合って混乱するので、1つのスタイルはどちらか一方で登録します。

登録したスタイルが一覧に出てこないとき

コードを書いたのにサイドバーの「スタイル」に項目が増えない、という場合は次の順で確認していくと原因を絞り込めます。

init フックの中で呼んでいるか

register_block_style() を functions.php の直下でそのまま呼ぶと、ブロックタイプの登録が終わる前に実行されてしまい、うまく反映されないことがあります。必ず add_action( 'init', ... ) の中で呼びましょう。反対に、フックのタイミングが遅すぎても（wp_enqueue_scripts など）エディター側の一覧には間に合いません。

ブロック名が名前空間から書けているか

第1引数は quote ではなく core/quote のように、名前空間を含めたフルネームで指定します。ブロック名が分からないときは、エディターで対象のブロックを選び、右上のオプションメニューから「コードエディター」に切り替えると、<!-- wp:quote --> のようなブロックコメントで確認できます。コアブロックはこの表記だと名前空間が省略されているので、頭に core/ を付けたものが正式なブロック名です。

name にスペースや大文字が入っていないか

name にスペースが含まれていると登録自体が拒否され、一覧に出てきません。クラス名として使われる値なので、半角小文字とハイフンだけで組み立てるのが確実です。あわせて、キャッシュ系プラグインを使っている場合は、管理画面のアセットが古いまま配信されていないかも確認してみてください。

エディターだけ見た目が違うとき

「フロントでは正しく表示されるのに、編集画面では変化がない」というのもよくある症状です。原因はほとんどの場合、CSS の読み込み方にあります。

CSS を wp_enqueue_scripts だけで読み込んでいる

wp_enqueue_scripts はフロント表示のためのフックなので、ここで読み込んだ CSS は編集画面には届きません。register_block_style() の inline_style や style_handle を使えばこの問題は起きませんが、自分で CSS を読み込みたい場合は enqueue_block_assets フックを使います。このフックはフロントと編集画面の両方で実行されます。

<?php
// フロントと編集画面の両方に同じ CSS を読み込む
add_action( 'enqueue_block_assets', 'mytheme_enqueue_block_styles_css' );

function mytheme_enqueue_block_styles_css() {
    wp_enqueue_style(
        'mytheme-block-styles',
        get_theme_file_uri( '/css/block-styles.css' ),
        array(),
        '1.0.0'
    );
}

テーマのエディタースタイルを使う

テーマ全体の見た目を編集画面にも反映させたい場合は、add_theme_support( 'editor-styles' ) と add_editor_style() でエディター用のスタイルシートを指定する方法もあります。この方法で読み込んだ CSS は WordPress 側で編集領域向けに調整されるため、テーマの基本デザインを揃える用途に向いています。ただしブロックスタイル単位で管理したいなら、CSS が自動で両方に読み込まれる register_block_style() のほうが素直です。

自作ブロックなら block.json の editorStyle を使う

自分で作ったブロックにスタイルを追加している場合は、block.json の style（フロントと編集画面の両方）と editorStyle（編集画面のみ）でスタイルシートを指定できます。編集画面だけで必要な調整――たとえばプレースホルダーの見た目など――は editorStyle に、実際の表示に関わる CSS は style に分けて書くと管理しやすくなります。

セレクタの詳細度が足りていない

読み込みは正しいのに一部のプロパティだけ効かない、という場合は、コアやテーマの CSS に負けている可能性があります。ブラウザの開発者ツールで対象要素を調べ、どのルールが勝っているかを確認してください。.wp-block-quote.is-style-blue-quote のようにブロック本来のクラスと is-style- クラスを重ねて書くだけでも詳細度が上がり、多くのケースはこれで解決します。

まとめ

register_block_style() は、ブロックエディターの「スタイル」に独自の選択肢を追加する関数です。init フックの中で、ブロック名と name / label、そして inline_style か style_handle を渡して登録すれば、is-style-〇〇 クラスと対応する CSS が編集画面・フロントの両方で有効になります。既定にする is_default はクラスが出力されなくなる点だけ覚えておきましょう。不要なスタイルを消すときは unregister_block_style()、コアの既定スタイルが対象なら JavaScript の unregisterBlockStyle() を使い分けます。編集する人がクラス名を手入力しなくてよくなるので、複数人で運用するサイトほど効果の大きい仕組みです。

参考ページ

• register_block_style() – WordPress Developer Resources
• unregister_block_style() – WordPress Developer Resources
• Styles – Block Editor Handbook | WordPress Developer Resources
• Metadata in block.json – Block Editor Handbook | WordPress Developer Resources