Block Bindings API(ブロックバインディングAPI)は、あらゆるデータソースをブロックの属性に接続することができるブロックエディターの強力な機能です。
このAPIは、WordPress 6.5で初めて導入され、初期の実装では投稿や固定ページ内にカスタムフィールドの値を表示できるようにするものでした。
現在では同期パターンの上書きや、WordPress 6.9で導入された投稿日時ブロックのバリエーションなど、WordPressの他の堅牢な機能の基盤にもなっています。
今回は、Block Bindings APIとは何か、何に使えるのかといった簡単な概要と、Gutenbergブロックと外部データソースを実際に接続する例をご紹介します。
Block Bindings APIの基本概念
冒頭で触れた通り、Block Bindings APIは、データソースとブロックの属性を接続するものです。
ブロックの属性を確認するには、GutenbergプロジェクトのGitHub上のブロックライブラリのsrcディレクトリに移動し、段落ブロックを探して、block.json ファイルを開いてみてください。attributesプロパティに、段落ブロックの属性一覧があります。
"attributes": {
"content": {
"type": "rich-text",
"source": "rich-text",
"selector": "p",
"role": "content"
},
"dropCap": {
"type": "boolean",
"default": false
},
"placeholder": {
"type": "string"
},
"direction": {
"type": "string",
"enum": [ "ltr", "rtl" ]
}
},
以下のブロックは、WordPress 6.9 からBlock Bindings APIに対応しているため、カスタムフィールドに接続可能です。
| 対応ブロック | 属性 |
|---|---|
| 段落 | コンテンツ |
| タイトル | コンテンツ |
| 画像 | id、url、alt、タイトル、キャプション |
| ボタン | テキスト、url、linkTarget、rel |
カスタムフィールドをブロックに接続するには、ブロックを登録する必要があります。以下は、WordPressプラグインまたはテーマのfunctions.phpファイルを介してカスタムフィールドを登録する例です。
add_action( 'init', function() {
register_post_meta( 'your-post-type', 'myplugin_meta_key', [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'description' => __( 'City name', 'textdomain' ),
'auth_callback' => 'is_user_logged_in',
] );
} );
register_post_meta は、カスタムフィールドの特性を定義する属性の配列を受け取ります。属性一覧は、公式ドキュメントをご覧ください。カスタムフィールドをBlock Bindings APIから利用できるようにするには、show_in_restをtrueに設定する必要があります。WordPress 6.9 時点では、サポートされている型はstringのみです。
カスタムフィールドと組み合わせたBlock Bindings APIの動作を確認するため、WordPressプラグインを作成し、先ほど示したコードを使ってメタフィールドを登録します。
<?php
/**
* Plugin Name: Block Bindings example
* Description: Block Bindings API を使用するためのサンプルプラグイン
* Version: 1.0.0
* Author: あなたの名前
* License: GPL2 or later
* Text Domain: block-bindings-example
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
add_action( 'init', function() {
register_post_meta( '', 'block_bindings_image_url', [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'description' => __( 'City name', 'block-bindings-example' ),
'auth_callback' => 'is_user_logged_in',
] );
} );
WordPress管理画面でプラグインを有効化したら、「投稿」>「投稿を追加」で新規投稿を作成します。いずれかの対応ブロックを選択すると、ブロック設定サイドバーの「属性」パネルに、登録したカスタムフィールドに接続可能な属性が一覧表示されます。

右上の「設定オプション」(3つの点)をクリックして、「設定」を開きます。「一般」>「高度な設定」にある「カスタムフィールド」を有効にします。下に出現する「ページを表示して、リロード」をクリックして変更を保存します。

次のステップは、画像ブロックを挿入することです。ブロックを選択した状態で、「属性」パネルの+アイコンをクリックし、「url」を選びます。すると、「属性」パネルに利用可能なメタフィールドの一覧が表示されます。もう一度urlを選択すると、現在の投稿タイプに対応したメタフィールドを指定できます。

メタフィールドを選択して、投稿を保存します。これでエディターとフロントエンドの両方に画像が表示されます。

WordPressのバージョン6.7から、Label属性を使って、以下のようにエディターにテキストを表示できるようになっています。以下は使用例です。
add_action( 'init', function() {
register_post_meta( '', 'block_bindings_image_url', [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'description' => __( 'City image', 'block-bindings-example' ),
'label' => __('Image URL'),
'auth_callback' => 'is_user_logged_in',
] );
} );

コードエディターを開くと、画像ブロックの区切り文字の中にJSONオブジェクトが表示されます。metadata.bindings.urlプロパティは、画像ブロックのurlがメタデータフィールドにリンクされていることを示しています。
<!-- wp:image {
"metadata":{
"bindings":{
"url":{
"source":"core/post-meta",
"args":{
"key":"block_bindings_image_url"
}
}
}
}
} -->
<figure class="wp-block-image"><img alt="/></figure>
<!-- /wp:image -->
sourceプロパティは、ブロックバインディングのデータソースを指定args.keyプロパティは、メタフィールドへの参照を確立
Block Bindings APIは、カスタムデータソースを登録できるため、開発の新たな可能性が広げてくれます。続いては、サードパーティサービスのデータをBlock Bindings APIで利用する方法を見ていきます。
カスタムバインディングソースの登録方法を実践例
Block Bindings APIの基本的な概念を押さえたら、もう少し専門的な側面を掘り下げていきましょう。
前述したように、Block Bindings APIでは独自のデータソースを登録することができます。これにより、データをリモートソースから取得したり、生データを操作して有用な情報を生成したり、コンテンツに自動挿入したりすることが可能になります。
カスタムアプリケーション開発の基礎として利用できる実例を交えながら、Block Bindings APIの可能性を最大限に引き出す方法をご紹介します。
外部ソースからデータを取得し、投稿、固定ページ、またはカスタム投稿タイプに表示したいとします。例えば、ある都市の緯度と経度を指定してリクエストを送信することで、天気予報サービスのAPIに問い合わせ、リアルタイムの天気データを取得し、それをサイトに表示することができます。
Block Bindings API を利用すれば、こうした天気データをブロックに動的に反映できるほか、天候に応じて画像のurl属性を自動で変更することも可能です。
この機能をWordPressサイトに追加するには、まずプラグインを作成する必要があります。
ステップ1. 基本プラグインの作成
まずは、プラグインファイルを作成します。WordPressのwp-content/pluginsディレクトリに移動し、block-bindings-exampleという新規フォルダを作成します。このフォルダの中に以下のファイルを追加します。
/wp-content/plugins/
└── /block-bindings-example/
├── block-bindings-example.php
└── /includes/
├── binding-sources.php
├── meta-fields.php
└── weather-api.php
任意のコードエディターでblock-bindings-example.phpファイルを開き、以下のコードを追加します。
<?php
/**
* Plugin Name: Block Bindings Example
* Description: WordPress Block Bindings API(6.5以降)を使用して、Open-Meteo API の天気データをカスタム投稿メタおよび独自のバインディングソース経由で、Gutenberg ブロックに動的にバインド。
* Version: 1.0.0
* Author: あなたの名前
* License: GPL2 or later
* Text Domain: block-bindings-example
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // 直接アクセスされた場合は終了
}
/**
* 天気データのキャッシュ期間:30分
* API呼び出し回数を減らし、パフォーマンスを改善
*/
define( 'BB_WEATHER_CACHE_TIME', HOUR_IN_SECONDS / 2 );
require_once plugin_dir_path( __FILE__ ) . 'includes/meta-fields.php';
require_once plugin_dir_path( __FILE__ ) . 'includes/binding-sources.php';
require_once plugin_dir_path( __FILE__ ) . 'includes/weather-api.php';
/**
* 初期化処理
*/
function bb_init_setup() {
bb_register_post_meta();
bb_register_binding_sources();
}
add_action( 'init', 'bb_init_setup' );
このコードの実行内容は以下のとおりです。
BB_WEATHER_CACHE_TIME定数:天気データのキャッシュ期間を定義。API 呼び出し回数の削減、ページパフォーマンスの向上、サービスコストの低減に寄与。require_once式:メタフィールドの登録、バインディングソースの登録、APIからのデータ取得に必要なスクリプトが含まれる。- setup関数:投稿メタフィールドとカスタムバインディングソースを登録する2つの関数を呼び出す。
ステップ2. 投稿メタフィールドの登録
次に達成したい目標に必要なメタフィールドを登録します。includesフォルダ内のmeta-fields.phpファイルを開き、以下のコードを追加します。
<?php
/**
* REST API および Block Bindings のエディターパネルに表示される
*/
function bb_register_post_meta() {
if ( ! function_exists( 'register_post_meta' ) ) {
return;
}
register_post_meta( 'post', 'block_bindings_city_name', [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'description' => __( '都市名を入力', 'block-bindings-example' ),
'label' => __( '都市名', 'block-bindings-example' ),
'auth_callback' => 'is_user_logged_in',
] );
register_post_meta( 'post', 'block_bindings_image_url', [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'description' => __( '都市の画像URLを入力', 'block-bindings-example' ),
'label' => __( '都市画像のURL', 'block-bindings-example' ),
'auth_callback' => 'is_user_logged_in',
] );
register_post_meta( 'post', 'block_bindings_city_lat', [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'description' => __( '都市の緯度を入力', 'block-bindings-example' ),
'label' => __( '緯度', 'block-bindings-example' ),
'auth_callback' => 'is_user_logged_in',
] );
register_post_meta( 'post', 'block_bindings_city_lng', [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'description' => __( '都市の経度を入力', 'block-bindings-example' ),
'label' => __( '経度', 'block-bindings-example' ),
'auth_callback' => 'is_user_logged_in',
] );
}
register_post_meta関数は、投稿で使用するメタキーを登録します。なお、この手順で登録したメタフィールドをBlock Bindings APIで使用するには、show_in_restをtrueに、typeをstringに設定する必要があります。詳細は公式ドキュメントをご覧ください。
ステップ3. ブロックバインディングソースの登録
次に、ブロックバインディングソースを登録します。binding-sources.phpファイルを開き、以下のコードを追加します。
<?php
/**
* カスタム Block Bindings ソース「bb/weather-condition」を登録
*/
function bb_register_binding_sources() {
if ( ! function_exists( 'register_block_bindings_source' ) ) {
return;
}
register_block_bindings_source(
'bb/weather-condition',
[
'label' => __( '天気の状態', 'block-bindings-example' ),
'get_value_callback' => 'bb_get_weather_condition_value',
'uses_context' => [ 'postId' ], // 投稿メタを取得するために postId が必要
]
);
}
register_block_bindings_source()には、ソース名、そしてソースからデータを取得して操作された値を返すコールバック関数が必要です。
次に、同じbinding-sources.phpファイルでコールバック関数を定義します。
function bb_get_weather_condition_value( array $source_args, WP_Block $block_instance ) {
$key = $source_args['key'] ?? null;
if ( ! $key ) {
return null;
}
// ブロックのコンテキストから現在の投稿IDを取得(投稿本文内では常に利用可能)
$post_id = $block_instance->context['postId'] ?? null;
// コンテキストが取得できない場合は、グローバルループを使用
if ( ! $post_id && in_the_loop() ) {
$post_id = get_the_ID();
}
if ( ! $post_id || $post_id <= 0 ) {
error_log( 'BB DEBUG: 天気バインディング用の投稿IDを特定できませんでした' );
return null;
}
$weather_data = bb_fetch_and_cache_weather_data( $post_id );
if ( ! is_array( $weather_data ) || ! isset( $weather_data[ $key ] ) ) {
return null;
}
$value = $weather_data[ $key ];
// 気温の場合は「°C」を付加
if ( $key === 'temperature' ) {
return $value . '°C';
}
return $value;
}
-
$source_args['key']は、ブロックの属性にバインドするデータを識別するためのキー。 -
次の行で、ブロックのコンテキストから現在の投稿IDを取得。プレビュー表示などでコンテキストが取得できない場合は、
get_the_ID()を使って現在の投稿IDを取得。 -
その後、APIから天気データを取得する
bb_fetch_and_cache_weather_data関数を呼び出し(この関数の定義については、次のステップで)。 -
$weather_data[$key]には、APIから取得した気温や天候状態などのデータが格納されている。 -
キーが
temperatureの場合は、取得した値の末尾に°Cを付加。 -
最後に、加工された値をブロックに返す。
ステップ4. 外部ソースからのデータ取得
続いて、Open-Meteo サービス(非商用利用は無料)からデータを取得します。
現在の気温と天気を取得するには、指定した場所の緯度と経度、およびクエリー変数current=weather_code,temperature_2mを含むリクエストをAPIに送信します。以下はリクエスト例です。
https://api.open-meteo.com/v1/forecast?latitude=-33.8717&longitude=151.2299¤t=weather_code,temperature_2m
APIが以下のようなレスポンスを返します。
{
"latitude": -33.8717,
"longitude": 151.2299,
"generationtime_ms": 0.030875205993652344,
"utc_offset_seconds": 0,
"timezone": "GMT",
"timezone_abbreviation": "GMT",
"elevation": 13.0,
"current_units": {
"time": "iso8601",
"interval": "seconds",
"weather_code": "wmo code",
"temperature_2m":"°C"
},
"current": {
"time": "2025-12-01T16:00",
"interval": 900,
"weather_code": 3,
"temperature_2m":7.3
}
}

必要なデータを取得する方法がわかったところで、weather-api.phpファイルを開き、以下のコードを追加します。
function bb_fetch_and_cache_weather_data( $post_id ) {
$lat = get_post_meta( $post_id, 'block_bindings_city_lat', true );
$lng = get_post_meta( $post_id, 'block_bindings_city_lng', true );
$lat = str_replace( ',', '.', trim( $lat ) );
$lng = str_replace( ',', '.', trim( $lng ) );
if ( ! is_numeric( $lat ) || ! is_numeric( $lng ) ) {
error_log( 'BB DEBUG: 緯度・経度の値が不正です(正規化後も数値として解釈できません)' );
return false;
}
$transient_key = 'bb_weather_data_' . $post_id;
$cached_data = get_transient( $transient_key );
if ( $cached_data !== false ) {
error_log( "BB DEBUG: キャッシュを使用します(post_id: {$post_id})" );
return $cached_data;
}
// Open-Meteo API のURLを組み立て
$api_url = sprintf(
'https://api.open-meteo.com/v1/forecast?latitude=%s&longitude=%s¤t=weather_code,temperature_2m',
rawurlencode( $lat ),
rawurlencode( $lng )
);
error_log( "BB DEBUG: 天気データを取得します: {$api_url}" );
$response = wp_remote_get( $api_url, [ 'timeout' => 10 ] );
if ( is_wp_error( $response ) ) {
error_log( 'BB DEBUG: APIリクエストに失敗しました – ' . $response->get_error_message() );
return false;
}
if ( wp_remote_retrieve_response_code( $response ) !== 200 ) {
error_log( 'BB DEBUG: APIが200以外のステータスコードを返しました' );
return false;
}
$body = wp_remote_retrieve_body( $response );
$data = json_decode( $body, true );
if ( ! $data || ! isset( $data['current'] ) ) {
error_log( 'BB DEBUG: APIレスポンスが空、または形式が想定と異なります' );
return false;
}
$temperature = $data['current']['temperature_2m'] ?? null;
$weather_code = $data['current']['weather_code'] ?? 0;
$mapped_data = [
'temperature' => round( (float) $temperature ),
'weather_state' => bb_map_wmo_code_to_state( (int) $weather_code ),
];
// Cache for 30 minutes
set_transient( $transient_key, $mapped_data, BB_WEATHER_CACHE_TIME );
error_log( 'BB DEBUG: 天気データを取得し、キャッシュしました' );
return $mapped_data;
}
この関数は、Open-Meteo APIから現在の天気データを取得し、transientsを使ってキャッシュに保存します。
-
get_post_metaを2回呼び出し、場所の緯度と経度を取得。 -
続く2行では、ユーザーが小数点の代わりにカンマを入力した場合に備えて、小数点記号を正規化。
-
条件分岐で
is_numeric()を使い、緯度・経度が数値として有効かどうかをチェック。 -
次に取得したデータがキャッシュに存在するかを確認。キャッシュがあれば、そのデータを返して処理を終了し、APIへのリクエストは行わない。
-
キャッシュが存在しない場合は、APIリクエストを組み立てて送信し、レスポンスを取得。
-
その後、レスポンスから気温(
temperature)と天候コード(weather_code)を取り出す。 -
weather_codeは、後述するbb_map_wmo_code_to_state関数を使って天候状態(weather_state)に変換される。 -
取得したデータは
set_transientを使ってキャッシュに保存される。 -
最後に、変換済みの天気データを返す。
最後に、weather_codeを人間が読める文字列に変換する関数を定義します。
function bb_map_wmo_code_to_state( $code ) {
if ( $code >= 0 && $code <= 3 ) {
return 'clear';
} elseif ( $code >= 51 && $code <= 67 ) {
return 'rainy';
} elseif ( $code >= 71 && $code <= 77 ) {
return 'snowy';
} elseif ( $code >= 95 ) {
return 'thunderstorm';
}
return 'cloudy';
}
これでコードが完成です。プラグインをテストする準備が整いました。
Block Bindings APIの使い方
ここからは、Block Bindings APIに追加された新機能の使い方をご紹介します。
WordPress管理画面で「プラグイン」に移動し、先ほど作成したBlock Bindings Exampleプラグインを有効化します。

その後、新規投稿または固定ページを作成し、以下のように画像ブロック、タイトル、2つの段落を含む4つの行ブロックを追加して、投稿を保存します。

続いて、カスタムフィールドを追加し、投稿を保存します。

画像ブロックを選択し、ブロック設定サイドバーにある「属性」パネルを開き、ブロックバインディングをサポートする画像ブロック属性の一覧から「url」を選択します。

ブロックの属性を選択すると、「高度な設定」タブに「接続されていません」と表示された新しいURL要素が表示されます。そのURL項目をもう一度クリックすると、利用可能なバインディングソースの一覧が表示されます。「投稿メタ」には、この投稿タイプに登録されている4つのカスタムフィールドと、それぞれの値が表示されます。ここで「都市画像URL」を選択します。

「都市画像URL」メタフィールドを画像ブロックのurl属性に割り当てました。これで選択した都市の写真が表示されます。
他のメタフィールドについても、同様のプロセスになります。「都市名」フィールドを見出しブロックのcontent属性に、「緯度」フィールドと「経度」フィールドを対応する段落ブロックに割り当てます。
最後の2つのブロックをカスタムバインディングソースに接続します。この操作はエディターのUIからは行えません。
現時点では、コードエディターに切り替えて、バインディングソースに接続された2つのブロックのマークアップを記述する必要があります。以下は、Open-Meteoサービスが提供する気温を表示するコード例です。
<!-- wp:paragraph {
"metadata":{
"bindings":{
"content":{
"source":"bb/weather-condition",
"args":{
"key":"temperature"
}
}
}
}
} -->
<p>Placeholder</p>
<!-- /wp:paragraph -->
この方法では、バインディングソース名は「天気の状態」とエディターに表示されますが、実際のデータはフロントエンドでのみ表示されます。

明らかに、ブロックのマークアップにJSONオブジェクトを手動で追加する方法は、ユーザーにとって使いやすいとは言えません。WordPress 6.9ではBlock Bindings APIが大幅に改善され、カスタムデータソース用のUIを作成できるようになったため、カスタムUIを追加して、このプラグインをさらに改善してみます。
カスタムバインディングソースのUIを作成する方法
カスタムバインディングソースのUIを作成するには、JavaScriptコードを多少書く必要があります。まず、/includesの下にjsサブフォルダを作成し、その中にblock-bindings-ui.jsファイルを作成します。プラグインの構造は次のようになります。
/wp-content/plugins/
└── /block-bindings-example/
├── block-bindings-example.php
└── /includes/
├── binding-sources.php
├── meta-fields.php
└── weather-api.php
└── /js/
└── block-bindings-ui.js
最初のステップとして、JSスクリプトをプラグインのメインファイルに追加します。
function bb_enqueue_weather_bindings_ui() {
if ( ! function_exists( 'register_block_bindings_source' ) ) {
return;
}
$js_file_path = plugin_dir_path( __FILE__ ) . 'includes/js/block-bindings-ui.js';
if ( ! file_exists( $js_file_path ) ) {
return;
}
// エディターでのみスクリプトを読み込み
wp_enqueue_script(
'bb-weather-bindings-ui',
plugin_dir_url( __FILE__ ) . 'includes/js/block-bindings-ui.js',
[ 'wp-blocks', 'wp-element', 'wp-dom-ready', 'wp-block-bindings' ],
filemtime( $js_file_path ),
true
);
}
add_action( 'enqueue_block_editor_assets', 'bb_enqueue_weather_bindings_ui' );
この関数の概要は以下のとおりです。
-
register_block_bindings_source()が存在するかどうかを確認。 -
次にプラグインの
/includes/jsフォルダ内にblock-bindings-ui.jsファイルが存在するかを確認。 -
wp_enqueue_script()を使って、エディターで利用するためにスクリプトを読み込む(関数の詳細は公式ドキュメントを参照)。 -
スクリプトを編集画面向けに読み込むために、
enqueue_block_editor_assetsフックを使用。
block-bindings-ui.jsファイルを開き、以下のコードを記述します。
wp.blocks.registerBlockBindingsSource({
name: 'bb/weather-condition',
label: '天気の状態',
useContext: [ 'postId', 'postType' ],
getValues: ( { bindings } ) => {
if ( bindings.content?.args?.key === 'temperature' ) {
return {
content: 'Open-Meteoが提供する現在の気温',
};
}
if ( bindings.content?.args?.key === 'weather_state' ) {
return {
content: '現在の状態',
};
}
return {
content: bindings.content,
};
},
getFieldsList() {
return [
{ label: '気温(°C)', type: 'string', args: { key: 'temperature' } },
{ label: '天気の状態', type: 'string', args: { key: 'weather_state' } }
];
}
});
registerBlockBindingsSource():バインディングソースをブロックエディターに登録。name:バインディングソースの一意な識別子。PHPでregister_block_bindings_source()と共に使用される名前と正確に一致する必要がある。label:「属性」パネルの「ソース」ドロップダウンに表示される人間が読める名前。useContext:このソースがブロックから必要とするコンテキスト値を設定。postIdは、ソースがどのポストのメタ/天気データを読み取るかを知るために必要。getValues:ブロックエディター内で境界値のプレビューを提供。ユーザーがバインディングソース(この例では「天気の状態」)を選択した後にドロップダウンに表示されるオプションを返す。この関数はWordPress 6.9 以降で利用可能。getFieldsList:ユーザーがバインディングソース(この例では「天気の状態」)を選択した後にドロップダウンに表示されるオプションを返す。
ファイルを保存し、エディターに戻ると、エディターUIで「投稿メタ」と並んで「天気の状態」ソースが利用できるようになりました。ページを読み込み、バインディングソースに段落または見出しブロックを接続すると、以下のようになります。

以下は、サイトのフロントエンドでの見え方です。

Block Bindings APIでできるその他のこと
今回ご紹介した内容は、Block Bindings APIで実現できることのほんの一部です。今後も新たな実装や機能追加が行われることが期待されます。
Block Bindings APIをInteractivity APIのようなWordPress APIと組み合わせることで、WordPressが初期に人気を博した従来のブログ機能をはるかに超えた、動的でインタラクティブなアプリケーションを構築できるようになります。
WordPressは今日、単なるブログプラットフォームやウェブサイトビルダーではなく、あらゆる種類のウェブアプリケーションを開発できる、汎用的な開発プラットフォームへと進化しつつあります。
アプリケーションが高度になればなるほど、サーバーの性能も重要になります。Kinstaでは、高いパフォーマンス、堅牢なセキュリティ、充実した自動化機能、そして 世界的レビューサイトG2.comユーザーから業界トップクラスと評されるサポートを備えた、高性能なWordPress専用マネージドクラウドサーバーを提供しています。
高度なウェブアプリケーションには、堅牢なサーバー基盤が欠かせません。Kinstaのプランをチェックして、要件に適したものをぜひお試しください。