深入理解 WordPress `get_block_wrapper_attributes()` 函数的源码：如何为区块容器添加动态 HTML 属性。

各位观众老爷，今天咱们聊点硬核的——WordPress 区块编辑器里，get_block_wrapper_attributes() 这个小可爱，以及如何用它给你的区块容器穿上定制的“华服”。

开场白：为什么需要给区块容器定制属性？

想象一下，你是一个建筑师，你的任务是设计一个漂亮的房子（WordPress 网站）。区块编辑器就是你的乐高积木，而 get_block_wrapper_attributes() 就像是那些能让你把积木块连接起来，并且赋予它们特殊功能的连接器。

默认情况下，WordPress 会给每个区块包裹一个 <div> 标签。但是，如果你想让这个 <div> 标签更强大，比如添加自定义 CSS 类、data 属性，或者 ARIA 属性，让它能响应用户的交互，或者更好地被屏幕阅读器识别，那你就需要 get_block_wrapper_attributes() 了。

get_block_wrapper_attributes() 是什么？

简单来说，get_block_wrapper_attributes() 是一个 PHP 函数，它允许你生成 HTML 属性字符串，然后把这些属性添加到你的区块容器元素上。通常，这个容器元素就是一个 <div>。

源码剖析：探秘 get_block_wrapper_attributes() 的真面目

虽然我们直接讲它的实现有点枯燥，但是了解它的原理能帮助我们更好地使用它。实际上， get_block_wrapper_attributes() 最终调用的核心逻辑隐藏在更底层的函数中，它主要负责将一个属性数组转换成 HTML 属性字符串。我们不会深入到WordPress内核的迷宫里，而是专注于如何在PHP代码里利用它。

实战演练：给区块容器添加酷炫的属性

现在，咱们撸起袖子，开始实战。假设我们要创建一个自定义的“提示框”区块。我们希望这个提示框的容器能有以下特性：

• 一个 class 属性，用于应用样式。
• 一个 data-type 属性，用于标识提示框的类型（例如：info, warning, error）。
• 一个 aria-label 属性，用于提升可访问性。

步骤 1：注册区块

首先，我们需要注册我们的自定义区块。这通常在你的主题的 functions.php 文件或者一个自定义插件中完成。

<?php
function my_custom_block_init() {
    register_block_type( __DIR__ . '/blocks/tip-box/block.json' );
}
add_action( 'init', 'my_custom_block_init' );

这里 block.json 文件定义了区块的元数据，包括区块名称、标题、属性等等。这个文件一般长这样（简化版）：

{
    "name": "my-theme/tip-box",
    "title": "提示框",
    "category": "common",
    "icon": "info",
    "attributes": {
        "type": {
            "type": "string",
            "default": "info"
        },
        "content": {
            "type": "string",
            "source": "html",
            "selector": "p"
        }
    },
    "supports": {
        "align": true
    },
    "textdomain": "my-theme",
    "editorScript": "file:./index.js",
    "style": "file:./index.css"
}

注意 attributes 部分，这里定义了区块的属性。 type 属性用于选择提示框的类型， content 属性用于存储提示框的内容。

步骤 2：编写 PHP 渲染回调函数

接下来，我们需要编写 PHP 渲染回调函数，这个函数负责生成区块的 HTML 代码。关键就在这里，我们要使用 get_block_wrapper_attributes() 来添加自定义属性。

<?php
/**
 * Render callback function.
 *
 * @param array    $attributes The block attributes.
 * @param string   $content    The block content.
 * @param WP_Block $block      The block instance.
 *
 * @return string The rendered HTML.
 */
function my_tip_box_render_callback( $attributes, $content, $block ) {
    $type = isset( $attributes['type'] ) ? $attributes['type'] : 'info';

    $wrapper_attributes = get_block_wrapper_attributes(
        [
            'class' => 'tip-box tip-box-' . $type,
            'data-type' => $type,
            'aria-label' => '提示框：' . $type,
        ]
    );

    $block_content = sprintf(
        '<div %1$s>%2$s</div>',
        $wrapper_attributes,
        $content
    );

    return $block_content;
}

register_block_type(
    'my-theme/tip-box',
    [
        'render_callback' => 'my_tip_box_render_callback',
    ]
);

让我们逐行解读：

• $type = isset( $attributes['type'] ) ? $attributes['type'] : 'info';：从区块属性中获取 type 的值，如果没有设置，默认为 ‘info’。
• $wrapper_attributes = get_block_wrapper_attributes([...]);： 这是关键！我们调用 get_block_wrapper_attributes() 函数，并传入一个关联数组。这个数组的键就是 HTML 属性的名称，值就是属性的值。
• 'class' => 'tip-box tip-box-' . $type,： 这里我们给容器添加了两个 CSS 类：tip-box 和 tip-box-{type}。 {type} 会被替换成实际的提示框类型（例如：info, warning, error）。
• 'data-type' => $type,： 这里我们添加了一个 data-type 属性，用于标识提示框的类型。
• 'aria-label' => '提示框：' . $type,： 这里我们添加了一个 aria-label 属性，用于提升可访问性。屏幕阅读器会读取这个属性，告诉用户这是一个什么类型的提示框。
• sprintf('<div %1$s>%2$s</div>', $wrapper_attributes, $content);： 这里我们用 sprintf() 函数将属性字符串和区块内容组合成最终的 HTML 代码。%1$s 会被 $wrapper_attributes 替换，%2$s 会被 $content 替换。

步骤 3：编写 JavaScript 编辑器组件 (index.js)

现在，让我们编写 JavaScript 代码，让用户可以在区块编辑器中选择提示框的类型并输入内容。

import { registerBlockType } from '@wordpress/blocks';
import { TextControl, SelectControl } from '@wordpress/components';
import { useBlockProps, RichText } from '@wordpress/block-editor';

registerBlockType( 'my-theme/tip-box', {
    edit: ( props ) => {
        const { attributes, setAttributes } = props;
        const { type, content } = attributes;

        const blockProps = useBlockProps();

        return (
            <div { ...blockProps }>
                <SelectControl
                    label="提示框类型"
                    value={ type }
                    options={ [
                        { label: '信息', value: 'info' },
                        { label: '警告', value: 'warning' },
                        { label: '错误', value: 'error' },
                    ] }
                    onChange={ ( newType ) => setAttributes( { type: newType } ) }
                />
                <RichText
                    tagName="p"
                    placeholder="请输入提示内容…"
                    value={ content }
                    onChange={ ( newContent ) => setAttributes( { content: newContent } ) }
                />
            </div>
        );
    },
    save: ( props ) => {
        const { attributes } = props;
        const { content } = attributes;

        const blockProps = useBlockProps.save();

        return (
            <div { ...blockProps }>
                <RichText.Content tagName="p" value={ content } />
            </div>
        );
    },
} );

这里，我们使用了 @wordpress/components 提供的 SelectControl 组件，让用户可以选择提示框的类型。 RichText 组件用于输入提示框的内容。 useBlockProps 会自动处理区块的默认属性（例如：id, class）。 ...blockProps 是一个 ES6 的展开运算符，它会将 blockProps 对象的所有属性添加到 <div> 元素上。在save方法中，我们使用useBlockProps.save()来获取用于保存的属性，确保前端渲染时能够正确显示。

步骤 4：编写 CSS 样式 (index.css)

最后，我们需要编写 CSS 样式，让提示框看起来更漂亮。

.tip-box {
    padding: 10px;
    border: 1px solid #ccc;
    margin-bottom: 10px;
}

.tip-box-info {
    background-color: #e5f5ff;
    border-color: #99d9ea;
}

.tip-box-warning {
    background-color: #fff8e1;
    border-color: #ffe57f;
}

.tip-box-error {
    background-color: #ffebee;
    border-color: #ef9a9a;
}

这里，我们定义了 tip-box 类的一些基本样式，然后根据提示框的类型，应用不同的背景颜色和边框颜色。

完整代码结构

为了更清晰地展示代码结构，我们用一个表格来总结一下：

文件名	内容
functions.php	注册区块：register_block_type()，并设置渲染回调函数。
blocks/tip-box/block.json	区块元数据：区块名称、标题、图标、属性等。
blocks/tip-box/index.php	PHP 渲染回调函数：my_tip_box_render_callback()，使用 get_block_wrapper_attributes() 添加自定义属性。
blocks/tip-box/index.js	JavaScript 编辑器组件：定义区块在编辑器中的行为，包括显示属性编辑控件（例如：SelectControl, TextControl）和保存区块数据。
blocks/tip-box/index.css	CSS 样式：定义区块的样式，包括容器的样式和不同类型提示框的样式。

高级用法：动态属性

get_block_wrapper_attributes() 的强大之处在于它可以根据区块的属性动态地生成 HTML 属性。例如，我们可以根据用户的选择，动态地添加不同的 CSS 类或者 data 属性。

<?php
function my_dynamic_block_render_callback( $attributes, $content, $block ) {
    $style = isset( $attributes['style'] ) ? $attributes['style'] : 'default';

    $wrapper_attributes = get_block_wrapper_attributes(
        [
            'class' => 'my-block my-block-' . $style,
            'data-style' => $style,
        ]
    );

    return sprintf(
        '<div %1$s>%2$s</div>',
        $wrapper_attributes,
        $content
    );
}

在这个例子中，我们根据 $attributes['style'] 的值，动态地添加 CSS 类 my-block-{style} 和 data 属性 data-style="{style}"。

注意事项：安全第一

在使用 get_block_wrapper_attributes() 时，一定要注意安全问题。特别是当你的属性值来自用户输入时，一定要进行适当的过滤和转义，防止 XSS 攻击。可以使用 esc_attr() 函数来转义属性值。

<?php
$unsafe_value = $_POST['my_input']; // 假设这个值来自用户输入
$safe_value = esc_attr( $unsafe_value );

$wrapper_attributes = get_block_wrapper_attributes(
    [
        'data-unsafe' => $safe_value,
    ]
);

总结：get_block_wrapper_attributes() 的妙用

get_block_wrapper_attributes() 是一个非常实用的函数，它可以让你轻松地给区块容器添加自定义的 HTML 属性。通过合理地使用这个函数，你可以：

• 增强区块的样式和功能。
• 提升网站的可访问性。
• 更好地控制区块的 HTML 输出。
• 构建更灵活、更强大的自定义区块。

记住，get_block_wrapper_attributes() 只是一个工具，真正重要的是你的创造力和想象力。希望今天的讲座能给你带来一些启发，让你在 WordPress 区块编辑器的世界里玩得更嗨！

最后的温馨提示

在实际开发中，建议你仔细阅读 WordPress 官方文档，了解 get_block_wrapper_attributes() 的更多细节和用法。同时，多参考一些优秀的开源区块项目，学习他们的代码实现，可以帮助你更快地掌握这个函数。

好了，今天的讲座就到这里。感谢各位的观看，我们下期再见！