云策 WordPress 开发者社区

函数文档

get_block_wrapper_attributes()

查看官方原文 ↗
💡 云策文档标注

概述

get_block_wrapper_attributes() 函数用于生成当前渲染块支持的HTML属性字符串，通过应用块支持的所有特性。它接受一个可选的额外属性数组，并返回合并后的HTML属性字符串。

关键要点

  • 函数参数：$extra_attributes（可选），默认为空数组，用于添加额外属性。
  • 返回值：字符串形式的HTML属性，如 style="..." class="..."。
  • 核心功能：合并块支持属性（通过 WP_Block_Supports::get_instance()->apply_block_supports() 获取）和额外属性，优先处理固定列表属性（style、class、id、aria-label）。
  • 属性合并逻辑：对于固定列表属性，如果两者都存在，则用空格连接；否则取非空值。其他属性直接添加。
  • 转义处理：使用 esc_attr() 对属性值进行转义，确保HTML安全。

代码示例

$wrapper_attributes = get_block_wrapper_attributes(
    [
        'class' => 'custom-class',
        'style' => 'color: #333',
    ]
);
return sprintf('<div %s>...</div>', $wrapper_attributes);

注意事项

  • 函数硬编码支持固定属性列表（style、class、id、aria-label），其他属性可通过 $extra_attributes 添加。
  • 从 WordPress 6.1.1 起，支持自定义属性如 data-settings，但需注意版本兼容性。
  • 使用时需将生成的属性字符串嵌入块标记的最外层HTML元素中。
📄 原文内容

Generates a string of attributes by applying to the current block being rendered all of the features that the block supports.

Parameters

$extra_attributesstring[]optional
Array of extra attributes to render on the block wrapper.

Default:array()

Return

string String of HTML attributes.

Source

function get_block_wrapper_attributes( $extra_attributes = array() ) {
	$new_attributes = WP_Block_Supports::get_instance()->apply_block_supports();

	if ( empty( $new_attributes ) && empty( $extra_attributes ) ) {
		return '';
	}

	// This is hardcoded on purpose.
	// We only support a fixed list of attributes.
	$attributes_to_merge = array( 'style', 'class', 'id', 'aria-label' );
	$attributes          = array();
	foreach ( $attributes_to_merge as $attribute_name ) {
		if ( empty( $new_attributes[ $attribute_name ] ) && empty( $extra_attributes[ $attribute_name ] ) ) {
			continue;
		}

		if ( empty( $new_attributes[ $attribute_name ] ) ) {
			$attributes[ $attribute_name ] = $extra_attributes[ $attribute_name ];
			continue;
		}

		if ( empty( $extra_attributes[ $attribute_name ] ) ) {
			$attributes[ $attribute_name ] = $new_attributes[ $attribute_name ];
			continue;
		}

		$attributes[ $attribute_name ] = $extra_attributes[ $attribute_name ] . ' ' . $new_attributes[ $attribute_name ];
	}

	foreach ( $extra_attributes as $attribute_name => $value ) {
		if ( ! in_array( $attribute_name, $attributes_to_merge, true ) ) {
			$attributes[ $attribute_name ] = $value;
		}
	}

	if ( empty( $attributes ) ) {
		return '';
	}

	$normalized_attributes = array();
	foreach ( $attributes as $key => $value ) {
		$normalized_attributes[] = $key . '="' . esc_attr( $value ) . '"';
	}

	return implode( ' ', $normalized_attributes );
}

View all references View on Trac View on GitHub

Uses Description
WP_Block_Supports::get_instance()wp-includes/class-wp-block-supports.php

Utility method to retrieve the main instance of the class.
esc_attr()wp-includes/formatting.php

Escaping for HTML attributes.

Changelog

Version Description
5.6.0 Introduced.

User Contributed Notes

  2. Skip to note 4 content


    Fabian Kaegy


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    At the time of WordPress 6.0 the get_block_wrapper_attributes function accepts two keys via the $extra_attributes. class and style.

    $wrapper_attributes = get_block_wrapper_attributes(
	[
		'class' => 'custom-class',
		'style' => 'color: #333',
	]
);

    In order to output the wrapper attributes, you need to add them inside your outermost HTML element in your block markup.

    $wrapper_attributes = get_block_wrapper_attributes(
	[
		'class' => 'custom-class',
		'style' => 'color: #333',
	]
);

return sprintf( '<section %s>...</section>', $wrapper_attributes );