register_block_bindings_source()

💡 云策文档标注

概述

register_block_bindings_source() 函数用于在 WordPress 中注册一个新的 Block Bindings 源，允许开发者定义自定义数据源，以便在支持 Block Bindings API 的块中动态绑定数据。

关键要点

注册源需要提供源名称和回调函数，回调函数负责从源获取值并传递给块属性。
源名称必须包含命名空间前缀，如 my-plugin/my-custom-source，且仅允许小写字母数字、斜杠和短横线。
注册应在 init hook 的处理程序中进行，以确保正确初始化。
块通过 metadata.bindings 属性引用源，并传递参数给回调函数。
回调函数接收 $source_args、$block_instance 和 $attribute_name 参数，返回混合类型值以覆盖块属性。

代码示例

function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) {
  $value = $source_args['key'];
  return "The value passed to the block is: $value";
}

function my_plugin_register_block_bindings_sources() {
  register_block_bindings_source( 'my-plugin/my-custom-source', array(
    'label'              => __( 'My Custom Source', 'my-plugin' ),
    'get_value_callback' => 'my_plugin_get_custom_source_value',
  ) );
}
add_action( 'init', 'my_plugin_register_block_bindings_sources' );

注意事项

源注册失败时返回 false，成功时返回 WP_Block_Bindings_Source 实例。
源属性数组可包含 label、get_value_callback 和可选的 uses_context 等键。
回调函数应处理 $source_args 以获取值，例如从自定义表或外部 API 查询。

📄 原文内容

Registers a new block bindings source.

Description

Registering a source consists of defining a name for that source and a callback function specifying how to get a value from that source and pass it to a block attribute.

Once a source is registered, any block that supports the Block Bindings API can use a value from that source by setting its metadata.bindings attribute to a value that refers to the source.

Note that register_block_bindings_source() should be called from a handler attached to the init hook.

Example

Registering a source

First, you need to define a function that will be used to get the value from the source.

function my_plugin_get_custom_source_value( array $source_args, $block_instance, string $attribute_name ) {
  // Your custom logic to get the value from the source.
  // For example, you can use the `$source_args` to look up a value in a custom table or get it from an external API.
  $value = $source_args['key'];

  return "The value passed to the block is: $value"
}

The $source_args will contain the arguments passed to the source in the block’s metadata.bindings attribute. See the example in the “Usage in a block” section below.

function my_plugin_register_block_bindings_sources() {
  register_block_bindings_source( 'my-plugin/my-custom-source', array(
    'label'              => __( 'My Custom Source', 'my-plugin' ),
    'get_value_callback' => 'my_plugin_get_custom_source_value',
  ) );
}
add_action( 'init', 'my_plugin_register_block_bindings_sources' );

Usage in a block

In a block’s metadata.bindings attribute, you can specify the source and its arguments. Such a block will use the source to override the block attribute’s value. For example:

<!-- wp:paragraph {
  "metadata": {
    "bindings": {
      "content": {
        "source": "my-plugin/my-custom-source",
        "args": {
          "key": "you can pass any custom arguments here"
        }
      }
    }
  }
} -->
<p>Fallback text that gets replaced.</p>
<!-- /wp:paragraph -->

Parameters

$source_namestringrequired

The name of the source. It must be a string containing a namespace prefix, i.e.
my-plugin/my-custom-source. It must only contain lowercase alphanumeric characters, the forward slash / and dashes.

$source_propertiesarrayrequired

The array of arguments that are used to register a source.

label string
The label of the source.
get_value_callback callable
A callback executed when the source is processed during block rendering.
The callback should have the following signature: function( $source_args, $block_instance, $attribute_name ): mixed
- @param array $source_args Array containing source arguments used to look up the override value, i.e. {“key”: “foo”}.
- @param WP_Block $block_instance The block instance.
- @param string $attribute_name The name of an attribute.
The callback has a mixed return type; it may return a string to override the block’s original value, null, false to remove an attribute, etc.
uses_context string[]
Optional. Array of values to add to block uses_context needed by the source.

Return

WP_Block_Bindings_Source|false Source when the registration was successful, or false on failure.

Source

function register_block_bindings_source( string $source_name, array $source_properties ) {
	return WP_Block_Bindings_Registry::get_instance()->register( $source_name, $source_properties );
}

View all references View on Trac View on GitHub

Uses	Description
WP_Block_Bindings_Registry::get_instance()`wp-includes/class-wp-block-bindings-registry.php`	Utility method to retrieve the main instance of the class.

Used by	Description
_register_block_bindings_post_data_source()`wp-includes/block-bindings/post-data.php`	Registers Post Data source in the block bindings registry.
_register_block_bindings_term_data_source()`wp-includes/block-bindings/term-data.php`	Registers Term Data source in the block bindings registry.
_register_block_bindings_post_meta_source()`wp-includes/block-bindings/post-meta.php`	Registers Post Meta source in the block bindings registry.
_register_block_bindings_pattern_overrides_source()`wp-includes/block-bindings/pattern-overrides.php`	Registers Pattern Overrides source in the Block Bindings registry.

Changelog

Version	Description
6.5.0	Introduced.

云策 WordPress 开发者社区

函数文档