2026年6月16日

WordPressのBlock Bindings APIで独自のカスタムソースを登録してブロックにバインドする方法

カスタマイズ

Block Bindings API を使うと、段落や見出し、画像、ボタンといったコアブロックの内容を、投稿本文に直接書かずに外部の値から差し込めます。標準で用意されている投稿メタ（core/post-meta）以外の値を使いたいときは、register_block_bindings_source() で独自のソースを登録し、ブロックの metadata.bindings からそのソースを指定します。この記事では、サイト共通の会社情報や現在の年を出す「カスタムソース」を例に、PHPでの登録、ブロックへのバインド、エディター側の表示、安全に作るための注意点を説明します。

Block Bindings API の仕組み

Block Bindings API は WordPress 6.5 で導入された仕組みです。ブロックの属性（段落のテキストや画像のURLなど）と「ソース」を結び付け、ページを表示するときにソースから取得した値で属性を置き換えます。

コアにはあらかじめ次のようなソースが登録されています。

core/post-meta: 投稿のカスタムフィールドの値を使う
core/pattern-overrides: 同期パターンの中身をインスタンスごとに上書きする

これらで足りない場合に、自分でソースを登録します。たとえば、電話番号や所在地をオプションに保存しておき、フッターや会社概要ページの段落ブロックにバインドすれば、値を1か所変えるだけで全ページの表示が変わります。独自ブロックを開発しなくても、コアブロックのデザインやスタイル設定をそのまま使えるのが利点です。

バインドできるブロックと属性には制限があります。導入当初は、段落と見出しのテキスト、画像のURL・代替テキスト・タイトル、ボタンのテキストとリンクなどに限られていました。対応範囲はバージョンごとに広がっているので、利用中のWordPressのリリースノートや開発者向けドキュメントで確認してください（2026年10月現在）。

手順1: PHPでカスタムソースを登録する

ソースは init フックで登録します。コードは子テーマの functions.php か、自作プラグインに書きます。

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

function mysite_register_block_bindings_sources() {
	register_block_bindings_source(
		'mysite/site-info',
		array(
			'label'              => __( 'サイト情報', 'mysite' ),
			'get_value_callback' => 'mysite_site_info_binding_value',
		)
	);
}

function mysite_site_info_binding_value( array $source_args, $block_instance, string $attribute_name ) {
	if ( empty( $source_args['key'] ) ) {
		return null;
	}

	// 返してよい値だけを許可リストで定義する
	switch ( $source_args['key'] ) {
		case 'company_name':
			return esc_html( get_bloginfo( 'name' ) );
		case 'company_phone':
			return esc_html( get_option( 'mysite_company_phone', '' ) );
		case 'current_year':
			return esc_html( wp_date( 'Y' ) );
		default:
			return null;
	}
}

ソース名は 名前空間/スラッグ の形式で、英小文字・数字・ハイフンを使います。label はエディターで表示される名前です。

get_value_callback は、ブロックが表示されるたびに呼ばれ、3つの引数を受け取ります。

$source_args: ブロック側の args に書いた値（どの値を取り出すかの指定）
$block_instance: 対象のブロック（WP_Block オブジェクト）
$attribute_name: バインドされている属性名（content や url など）

戻り値が属性の値として使われます。null を返すと置き換えは行われず、ブロックに保存されている元の内容が表示されます。

mysite_company_phone というオプションは、この例のために用意した独自の値です。設定画面を作るか、WP-CLIの wp option update mysite_company_phone "03-0000-0000" などで登録しておきます。

手順2: ブロックにソースをバインドする

バインドの指定は、ブロックの metadata 属性に書きます。コードエディター（ブロックエディターの右上メニューから切り替えられる、ブロックのHTMLを直接編集するモード）で、段落ブロックを次のように書きます。

<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"mysite/site-info","args":{"key":"company_phone"}}}}} -->
<p>電話番号</p>
<!-- /wp:paragraph -->

bindings のキーが属性名（ここでは段落のテキストを表す content）、source がソース名、args がコールバックの $source_args に渡る値です。<p> の中に書いた「電話番号」は、ソースが null を返したときに表示される内容になります。

同様に、コピーライト表記では次のようにできます。

<!-- wp:paragraph {"metadata":{"bindings":{"content":{"source":"mysite/site-info","args":{"key":"current_year"}}}}} -->
<p>2026</p>
<!-- /wp:paragraph -->

保存してフロントエンドを表示し、段落の中身がソースの値に置き換わっていれば成功です。

毎回コードエディターで書くのは手間なので、実運用ではバインド済みのブロックをブロックパターンとして登録したり、ブロックバリエーションとしてインサーターに追加したりして、編集者が選ぶだけで使えるようにしておくと便利です。

手順3: 投稿の情報を使う（uses_context）

Query Loop の中で使う場合など、ブロックがどの投稿に属しているかを知りたいときは、uses_context を指定します。

register_block_bindings_source(
	'mysite/post-info',
	array(
		'label'              => __( '投稿情報', 'mysite' ),
		'get_value_callback' => 'mysite_post_info_binding_value',
		'uses_context'       => array( 'postId', 'postType' ),
	)
);

function mysite_post_info_binding_value( array $source_args, $block_instance, string $attribute_name ) {
	$post_id = $block_instance->context['postId'] ?? 0;
	if ( ! $post_id || 'reading_time' !== ( $source_args['key'] ?? '' ) ) {
		return null;
	}

	$text    = wp_strip_all_tags( get_post_field( 'post_content', $post_id ) );
	$minutes = max( 1, (int) ceil( mb_strlen( $text ) / 500 ) );

	return esc_html( sprintf( '約%d分で読めます', $minutes ) );
}

この例は、本文の文字数から読了時間の目安（1分あたり500字で計算）を返します。uses_context で指定したコンテキストが、$block_instance->context から読めるようになります。

エディターでの表示を整える

PHPだけでソースを登録した場合、フロントエンドでは値が表示されますが、エディター上ではバインドされていることを示す表示になり、実際の値は出ないことがあります。編集者に実際の値やプレースホルダーを見せたい場合は、JavaScript側でも同じ名前のソースを登録します。クライアント側の登録APIは WordPress 6.7 で追加されました。

// エディター用スクリプト（依存: wp-blocks）
const { registerBlockBindingsSource } = wp.blocks;

registerBlockBindingsSource( {
	name: 'mysite/site-info',
	getValues( { bindings } ) {
		const values = {};
		for ( const [ attributeName, binding ] of Object.entries( bindings ) ) {
			values[ attributeName ] = '［サイト情報: ' + binding.args.key + '］';
		}
		return values;
	},
	canUserEditValue() {
		return false;
	},
} );

このスクリプトは enqueue_block_editor_assets フックで wp_enqueue_script() を使って読み込み、依存関係に wp-blocks を指定します。canUserEditValue で false を返すと、エディター上でバインドされた値を直接編集できなくなります。JavaScript側のAPIは比較的新しく、引数や対応機能が変わる可能性があるため、利用するWordPressのバージョンのドキュメントで確認してください。

安全に作るための注意点

カスタムソースで最も注意したいのは、**ブロックの args は投稿を編集できる人なら誰でも書き換えられる**という点です。たとえば get_option( $source_args['key'] ) のように、args の値をそのままオプション名として使うと、投稿者が任意のオプションの値をページに表示できてしまいます。管理者のメールアドレスや、プラグインが保存しているAPIキーが公開される危険があります。

上のコード例で switch による許可リストを使っているのはこのためです。args は「どの値を出すかの選択肢」としてだけ扱い、返す値は自分で決めたものに限定してください。

その他の注意点です。

返す値は用途に合わせてエスケープする（テキストなら esc_html()、URL属性なら esc_url()）
コールバックはブロックが表示されるたびに実行されるので、重い処理や外部APIの呼び出しは避けるか、トランジェントでキャッシュする
ソースを登録しているコードを削除すると、バインドは解除されずに元の内容が表示されるだけになる。テーマ変更で消えないよう、サイト全体で使う値はプラグインで登録するほうが扱いやすい

まとめ

Block Bindings API は、コアブロックの属性を外部の値に結び付ける仕組みで、WordPress 6.5で導入された
独自の値を使うには init で register_block_bindings_source() を呼び、get_value_callback で値を返す
ブロック側では metadata.bindings に属性名・ソース名・args を書く
投稿ごとの値が必要なら uses_context で postId などを受け取る
エディターで値を見せたい場合は、JavaScript側でも registerBlockBindingsSource() で登録する
args は編集者が書き換えられるため、許可リストで返す値を限定し、出力はエスケープする