register_block_bindings_source() │ WP 6.5.0

Регистрирует новый источник данных для блоков, позволяя динамически подставлять значения в атрибуты блоков при их рендеринге.

Кастомный источник данных связывается с атрибутами блоков через API привязки блоков (Block Bindings API). Это позволяет подставлять значения из произвольных полей, внешних API или других источников без необходимости создавать новые блоки.

Регистрация источника состоит из определения "имени" для источника и "коллбэк функции" определяющей как получать получить значение из источника и передать его в атрибут блока.

После регистрации источника любой блок, поддерживающий API привязок, может использовать его значение, указав его в атрибуте metadata.bindings.

Хуков нет.

Возвращает

WP_Block_Bindings_Source|false.

• WP_Block_Bindings_Source — при успешной регистрации.
• false — в случае ошибки.

Использование

register_block_bindings_source( $source_name, $source_properties );

$source_name(строка) (обязательный)

Уникальное имя источника в формате namespace/slug. Должно содержать только строчные буквы, цифры, дефисы и слэш.
Например my-plugin/my-custom-source.

$source_properties(массив) (обязательный)

Массив параметров для регистрации источника:

• label(строка)
  Название источника.

• get_value_callback(callable)
  Коллбэк функция, вызываемая при получении значения из источника (при рендеринге блока).

  Сигнатура коллбэк функции:

  function( array $args, WP_Block $block, string $attr_name ): mixed

  • $args(array)
    Массив аргументов, указанных в блоке (при привязке). Это те данные, которые указываются в JSON-данных блока в параметре args при привязке (см. пример ниже). Например:

    // в json данных блока:
    "metadata": {
    	"bindings": {
    		"content": {
    			"source": "my-plugin/my-custom-source",
    			"args": {
    				"key": "custom_field_key"
    			}
    		}
    	}
    }
    // в параметр функции попадёт массив:
    [ 'key' => 'custom_field' ]

  • $block(WP_Block)
    Объект текущего блока. Через него можно получить контекст (например postId), атрибуты и другую информацию о блоке.

  • $attr_name(string)
    Имя атрибута блока, к которому идет привязка. Например, content для параграфа, или url для изображения. Это позволяет одной функции обрабатывать несколько атрибутов, если нужно.

  Коллбэк может вернуть разные значения:

  • строку для переопределения оригинального значения блока
  • null
  • false для удаления атрибута
    и т.д.

• uses_context(массив строк) (необязательно)
  Массив контекстов блока, необходимых для источника, например: ['postId'].

  Указывает, какие контексты блока нужны источнику данных, чтобы корректно работать.

  Это информация, которую блок получает из окружения. Например, текущий ID записи (postId), ID шаблона (templateId), тип записи (postType) и т.д.

  Если источник зависит от таких данных (например, чтобы получить метаполе текущей записи), нужно явно указать, какие именно контексты ему требуются. Тогда WordPress автоматически передаст их в $block->context.

  Пример:

  'uses_context' => [ 'postId' ]

  Это означает, что источник требует ID текущей записи, и этот ID можно получить так:

  $post_id = $block->context['postId'];

  Без uses_context нужный контекст в блок не передастся, и получить, например, postId не получится.

Примеры

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

function my_plugin_get_custom_source_value( array $args, WP_Block $block, string $attr_name ) {
	$post_id = $block->context['postId'];
	$meta_key = $args['meta_key'] ?? '';

	return get_post_meta( $post_id, $meta_key, true );
}

<!-- wp:paragraph {
	"metadata": {
		"bindings": {
			"content": {
				"source": "my-plugin/my-custom-source",
				"args": {
					"meta_key": "custom_field_key"
				}
			}
		}
	}
} -->
<p>Значение по умолчанию (будет заменено)</p>
<!-- /wp:paragraph -->

add_action( 'init', 'register_external_data_source' );
function register_external_data_source() {
	register_block_bindings_source( 'my-plugin/external-data', [
		'label'              => 'External Data',
		'get_value_callback' => 'get_external_data',
	] );
}

function get_external_data( array $args, WP_Block $block, string $attr_name ) {
	$response = wp_remote_get( 'https://api.example.com/data' );
	if ( is_wp_error( $response ) ) {
		return 'Ошибка при получении данных';
	}

	$data = json_decode( wp_remote_retrieve_body( $response ), true );

	return $data['value'] ?? 'Данные недоступны';
}

<!-- wp:image {
	"id": 123,
	"sizeSlug": "large",
	"linkDestination": "none",
	"metadata": {
		"bindings": {
			"alt": {
				"source": "my-plugin/external-data"
			}
		}
	}
} /-->

add_filter( 'block_bindings_source_value', 'format_custom_value', 10, 5 );

/**
 * @param mixed    $value          The computed value for the source.
 * @param string   $name           The name of the source.
 * @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.
 *
 * @return mixed
 */
function format_custom_value( $value, $name, $source_args, $block_instance, $attribute_name ) {
	if ( $name === 'my-plugin/custom-source' && is_string( $value ) ) {
		return strtoupper( $value );
	}

	return $value;
}

Добавить свой пример