什么是WordPress区块绑定API以及如何使用它来构建动态网站

区块绑定 API 是区块编辑器中一个强大的工具，它允许您将任何数据源连接到区块的属性。

此 API 最初在 WordPress 6.5 中引入，其最初的实现方式是让 WordPress 用户能够在文章和页面中显示自定义字段值。

区块绑定 API 是其他强大 WordPress 功能的基础。例如，同步样板覆盖和 WordPress 6.9 中引入的“文章日期”区块变体。

那么，区块绑定 API 究竟是什么？它有什么用途？我们将提供一个简单的介绍和一个实际示例，展示如何在 Gutenberg 区块和外部数据源之间创建绑定。

区块绑定API：基本概念

如上所述，区块绑定 API 允许您在数据源和区块属性之间创建绑定。

如果您不熟悉区块属性，请导航至 GitHub 上 Gutenberg 项目区块库的 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 起支持区块绑定 API，因此可以链接到您的自定义字段：

要将自定义字段连接到 Gutenberg 区块，您必须先注册它们。以下代码通过 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',
] );
} );

属性定义了自定义字段的特征，文档中提供了完整的属性列表。要使自定义字段可供 Block Bindings API 使用，必须将 show_in_rest 设置为 `true`。从 WordPress 6.9 开始，string 是唯一受支持的类型。

要查看 Block Bindings API 如何与自定义字段配合使用，请创建一个新的 WordPress 插件，并使用上述代码注册一个元字段。

<?php
/**
* Plugin Name: Block Bindings example
* Description: Example plugin that uses the Block Bindings API.
* Version: 1.0.0
* Author: Your Name
* 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 控制面板中激活该插件。然后，导航至“文章”页面并创建一个新文章。当您选择一个受支持的区块时，“区块设置”侧边栏中的“属性”面板将显示可绑定到已注册自定义字段的属性列表。

支持区块绑定的图像区块属性

打开右上角的“选项”菜单，选择“首选项”。在“常规”选项卡中，找到“高级”部分并启用自定义字段。保存更改，等待页面重新加载，然后返回编辑器。

在编辑器的“首选项”中启用自定义字段。

注：我们假设您希望手动添加自定义字段。本文不涉及如何创建简化自定义字段插入的界面。

下一步是插入一个图像区块。选中该图像区块后，点击“属性”面板中的“+”图标，然后选择“url”属性。“属性”面板将显示可用元字段列表。再次选择“url”。现在，您将看到当前文章类型可用的元字段列表。

在“区块绑定”界面中，将自定义字段绑定到图像区块的 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 属性建立对元字段的引用。

区块绑定 API 最吸引人的地方在于它能够注册自定义数据源，这为开发者开启了许多令人兴奋的新可能性。接下来，我们将探讨如何将第三方服务的数据与区块绑定 API 结合使用。

如何注册自定义区块绑定数据源：一个实际示例

熟悉 Block Bindings API 的基本概念后，我们可以继续探讨其更高级、更有趣的开发者功能。

如前所述，Block Bindings API 允许您注册自定义数据源。这使您可以从远程源检索数据，和/或处理原始数据以生成可自动插入到内容中的有用信息。

在本节中，您将通过一个实际示例学习如何最大限度地发挥 Block Bindings 的潜力，该示例可作为开发您自己的自定义应用程序的基础。

温馨提示：请注意，以下示例中提供的代码仅用于演示目的，不应在生产环境中使用。

假设您想要从外部源检索数据并将其显示在您的文章、页面或自定义文章类型中。例如，您可以通过发送包含城市经纬度的请求来查询天气服务 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: Use WordPress Block Bindings API (6.5+) to dynamically bind weather data from Open-Meteo API to Gutenberg blocks using custom post meta and a custom binding source.
* Version: 1.0.0
* Author: Your Name
* License: GPL2 or later
* Text Domain: block-bindings-example
*/
if ( ! defined( 'ABSPATH' ) ) {
exit; // Exit if accessed directly
}
/**
* Cache duration for weather data: 30 minutes
* This reduces API calls and improves performance
*/
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';
/**
* Setup function
*/
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：注册文章元字段

下一步是注册您所需的元字段。打开 includes 文件夹中的 meta-fields.php 文件，并添加以下代码：

<?php
/**
* Registers custom post meta fields so they appear in the REST API and Block Bindings editor panel
*/
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'   => __( 'Add city name', 'block-bindings-example' ),
'label'         => __( 'City name', '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'   => __( 'Add city image URL', 'block-bindings-example' ),
'label'         => __( 'City image 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'   => __( 'Add city latitude', 'block-bindings-example' ),
'label'         => __( 'Latitude', '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'   => __( 'Add city longitude', 'block-bindings-example' ),
'label'         => __( 'Longitude', '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
/**
* Registers a custom Block Bindings source: bb/weather-condition
*/
function bb_register_binding_sources() {
if ( ! function_exists( 'register_block_bindings_source' ) ) {
return;
}
register_block_bindings_source(
'bb/weather-condition',
[
'label'              => __( 'Weather Condition', 'block-bindings-example' ),
'get_value_callback' => 'bb_get_weather_condition_value',
'uses_context'       => [ 'postId' ], // We need postId to get meta values
]
);
}

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;
}
// Get current post ID from block context (always available in post content)
$post_id = $block_instance->context['postId'] ?? null;
// Fallback: use global loop if context is missing
if ( ! $post_id && in_the_loop() ) {
$post_id = get_the_ID();
}
if ( ! $post_id || $post_id <= 0 ) {
error_log( 'BB DEBUG: Could not determine post ID for weather binding' );
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 ];
// Append °C symbol for temperature
if ( $key === 'temperature' ) {
return $value . '°C';
}
return $value;
}

让我们来分析一下这个函数：

• $source_args['key'] 用于标识绑定到区块属性的数据。
• 下一行从 context 中检索当前帖子的 ID。如果 context 缺失（例如预览帖子），则使用 get_the_ID() 函数检索当前帖子的 ID。
• 然后，它调用 bb_fetch_and_cache_weather_data 函数，该函数从 API 获取数据。我们将在下一步定义此函数。
• $weather_data[$key] 包含 API 提供的数据，例如温度和天气状态。
• 如果键是 temperature，则在提供的值后附加 °C。
• 然后，该函数返回最终值。

步骤 4：从外部源检索数据

如上所述，我们从 OpenMeteo 服务（免费用于非商业用途）检索数据。

要获取当前温度和天气状况，您需要向 API 发送一个请求，其中包含给定位置的纬度和经度，以及查询参数 var current=weather_code,temperature_2m。以下是一个请求示例：

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
}
}

在 Postman for Visual Studio Code 中获取 OpenMeteo 的响应

现在您已经知道如何获取所需数据，请打开 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: Invalid latitude/longitude values after normalization' );
return false;
}
$transient_key = 'bb_weather_data_' . $post_id;
$cached_data   = get_transient( $transient_key );
if ( $cached_data !== false ) {
error_log( "BB DEBUG: Cache hit for post ID {$post_id}" );
return $cached_data;
}
// Build 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: Fetching weather data from: {$api_url}" );
$response = wp_remote_get( $api_url, [ 'timeout' => 10 ] );
if ( is_wp_error( $response ) ) {
error_log( 'BB DEBUG: API request failed – ' . $response->get_error_message() );
return false;
}
if ( wp_remote_retrieve_response_code( $response ) !== 200 ) {
error_log( 'BB DEBUG: API returned non-200 status code' );
return false;
}
$body = wp_remote_retrieve_body( $response );
$data = json_decode( $body, true );
if ( ! $data || ! isset( $data['current'] ) ) {
error_log( 'BB DEBUG: Invalid or empty API response' );
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: Weather data fetched and cached successfully' );
return $mapped_data;
}

此函数从 OpenMeteo API 获取当前天气数据，并使用瞬态数据将其存储在缓存中。让我们仔细看看。

• 两次调用 get_post_meta 函数获取您所在位置的纬度和经度。
• 以下两行代码规范化小数分隔符，以防用户输入逗号而不是句点。
• 条件语句区块使用 is_numeric() 函数检查值是否为数值格式。
• 接下来，它检查数据是否在缓存中。如果在，则返回缓存数据并停止函数，而不向 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 插件。

在 WordPress 控制面板中激活插件。

之后，创建一个新文章或页面。添加一个图片区块、一个标题和四个行区块，每个行区块包含两个段落，如下图所示。然后，保存文章。

将区块添加到编辑器画布。

接下来，添加自定义字段并再次保存文章。

向文章添加自定义字段。

选择图片区块，然后在“区块设置”侧边栏中找到“属性”面板。点击“+”按钮打开下拉菜单，其中显示了支持区块绑定的图片区块属性列表。选择“url”项。

支持区块绑定的图片区块属性

选择区块属性后，“高级”选项卡将显示一个新的“URL”元素，其描述为“Not connected”。再次点击“url”项以查看可用绑定源列表。“文章元数据”提供了为文章类型注册的四个自定义字段及其各自的值。选择“City Image URL”。

连接已注册的元字段。

您已将“City Image URL”元字段分配给“图像”区块的 url 属性。现在您应该可以看到所选城市的图片。

对其他元字段执行相同的操作。将“City Name”字段分配给“标题”区块的 content 属性，并将“Latitude”和“Longitude”字段分配给相应的“段落”区块。

现在，将最后两个区块连接到您的自定义绑定源。遗憾的是，正如您在之前的屏幕截图中看到的，此选项在编辑器 UI 中不可用。

目前，您需要切换到代码编辑器，并手动编写链接到绑定源的两个区块的标记。以下是显示 OpenMeteo 服务提供的温度的代码：

<!-- wp:paragraph {
"metadata":{
"bindings":{
"content":{
"source":"bb/weather-condition",
"args":{
"key":"temperature"
}
}
}
}
} -->
<p>Placeholder</p>
<!-- /wp:paragraph -->

使用此方法，您的绑定数据源名称在编辑器中将显示为“Weather Condition”，但实际数据仅在前端可见。

自定义数据源的区块绑定示例

显然，手动将 JSON 对象添加到区块标记中并非易事。幸运的是，WordPress 6.9 对区块绑定 API 进行了重大改进，使得为自定义数据源创建用户界面成为可能。让我们尝试使用自定义用户界面来改进我们的插件。

如何为自定义区块绑定数据源创建用户界面

注：我们推迟了项目的这一部分，因为所需的功能仅在 WordPress 6.9 及更高版本中可用。如果您运行的是早期版本的 WordPress，以下代码将无法工作。

要为自定义绑定数据源创建用户界面，您需要编写一些 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;
}
// Enqueue the script only in the editor
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: 'Weather Condition',
useContext: [ 'postId', 'postType' ],
getValues: ( { bindings } ) => {
if ( bindings.content?.args?.key === 'temperature' ) {
return {
content: 'Current temperature provided by Open-Meteo.',
};
}
if ( bindings.content?.args?.key === 'weather_state' ) {
return {
content: 'Current conditions.',
};
}
return {
content: bindings.content,
};
},
getFieldsList() {
return [
{ label: 'Temperature (°C)',   type: 'string', args: { key: 'temperature' } },
{ label: 'Weather Conditions',  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 的强大功能。值得一提的是，这项强大的 WordPress 功能的开发远未结束，未来我们有望看到更多新的实现和新增功能。

将 Block Bindings API 与其他强大的 WordPress API（例如 Interactivity API）集成，您可以构建动态的交互式应用程序，其功能远超 WordPress 早期赖以成名的传统博客功能。

WordPress 不再仅仅是一个博客平台或网站构建器。它正朝着成为适用于各种类型 Web 应用程序的多用途开发平台的目标迈进。