探究 WordPress `register_block_pattern_category()` 函数的源码：如何创建自定义区块模式分类。

各位观众老爷们，晚上好！ 今天咱们不聊风花雪月，就聊聊WordPress里那些“花花肠子” —— 区块模式分类。

想象一下，你辛辛苦苦设计了一堆漂亮的区块组合，想要给别人用，但又不想让他们像无头苍蝇一样到处找。这时候，区块模式分类就派上用场了。它就像一个货架，把你的区块模式整整齐齐地摆放好，方便用户挑选。

今天，我们就来扒一扒 register_block_pattern_category() 这个函数的底裤，看看它到底是怎么工作的，以及我们如何用它来创建自定义的区块模式分类。

1. register_block_pattern_category() 是什么？

简单来说，register_block_pattern_category() 是 WordPress 官方提供的一个函数，用于注册区块模式分类。它接收两个参数：

• $category_name: 分类的唯一名称（字符串，必须是小写字母和下划线组成）。这玩意儿就像你的分类的身份证号，必须独一无二。
• $category_properties: 一个数组，包含分类的属性，例如标签（label）。

2. 函数的源码剖析 (WordPress 6.4.2)：

让我们稍微深入源码（wp-includes/block-patterns.php）。虽然不打算逐行解释，但关键部分还是得拎出来溜溜：

/**
 * Registers a block pattern category.
 *
 * @since 5.5.0
 *
 * @param string $category_name       Block pattern category name including namespace.
 * @param array  $category_properties Array containing the category properties.
 *                                    Must include a 'label' property.
 * @return bool True if the pattern category was registered, false otherwise.
 */
function register_block_pattern_category( $category_name, $category_properties ) {
    global $wp_block_pattern_categories;

    if ( ! is_array( $wp_block_pattern_categories ) ) {
        $wp_block_pattern_categories = array();
    }

    if ( ! isset( $category_properties['label'] ) ) {
        _doing_it_wrong(
            __FUNCTION__,
            __( 'Block pattern category must contain a "label" property.' ),
            '5.5.0'
        );
        return false;
    }

    if ( isset( $wp_block_pattern_categories[ $category_name ] ) ) {
        return false;
    }

    $wp_block_pattern_categories[ $category_name ] = $category_properties;

    return true;
}

这段代码的核心逻辑其实很简单：

• 检查全局变量： 它首先检查一个名为 $wp_block_pattern_categories 的全局变量是否存在。如果不存在，就创建一个空数组。这个全局变量就是用来存储所有已注册的区块模式分类的。
• 验证 ‘label’： 它检查 $category_properties 数组中是否存在 ‘label’ 属性。如果不存在，就会触发一个 _doing_it_wrong() 函数，告诉你参数用错了，并且返回 false。 _doing_it_wrong() 是 WordPress 用来提示开发者代码错误的函数，虽然不会中断程序运行，但会在开发者模式下显示警告。
• 检查是否已存在： 它检查 $category_name 是否已经存在于 $wp_block_pattern_categories 数组中。如果已经存在，说明这个分类已经注册过了，函数直接返回 false。
• 注册分类： 如果一切顺利，它会将 $category_name 作为键，$category_properties 作为值，添加到 $wp_block_pattern_categories 数组中。
• 返回结果： 最后，函数返回 true，表示分类注册成功。

3. 如何使用 register_block_pattern_category() ？

现在，我们来看看如何实际使用这个函数。通常，我们会把注册分类的代码放在主题的 functions.php 文件中，或者插件的主文件中。 并且用 init 钩子来确保 WordPress 已经准备好注册区块模式。

add_action( 'init', 'my_custom_block_pattern_categories' );

function my_custom_block_pattern_categories() {
    register_block_pattern_category(
        'my-custom-category', // 分类名称（小写，下划线）
        array( 'label' => __( '我的自定义分类', 'my-theme' ) ) // 分类属性
    );

    register_block_pattern_category(
        'another-category',
        array( 'label' => '另一个分类' ) // 可以不使用文本域函数，但建议使用
    );
}

这段代码做了什么？

• add_action( 'init', 'my_custom_block_pattern_categories' )： 这行代码告诉 WordPress，在 init 动作被触发时，执行 my_custom_block_pattern_categories() 函数。init 动作会在 WordPress 初始化完成后被触发，是注册区块模式和分类的常用时机。
• register_block_pattern_category()： 这个函数就是我们今天的主角。我们调用它两次，分别注册了两个分类：my-custom-category 和 another-category。
• 'label' => __( '我的自定义分类', 'my-theme' )： label 属性定义了分类在区块编辑器中显示的名称。__( '我的自定义分类', 'my-theme' ) 是 WordPress 的国际化函数，用于翻译文本。 'my-theme' 是文本域，应该替换成你主题或者插件的名称。

4. 注册区块模式

光注册分类还不够，我们还需要注册实际的区块模式，并将它们分配到我们自定义的分类中。 使用 register_block_pattern() 函数来注册区块模式。

add_action( 'init', 'my_custom_block_patterns' );

function my_custom_block_patterns() {
    register_block_pattern(
        'my-theme/my-awesome-pattern', // 模式名称（必须包含命名空间）
        array(
            'title'      => __( '我的超棒模式', 'my-theme' ), // 模式标题
            'categories' => array( 'my-custom-category', 'another-category' ), // 模式所属的分类
            'content'    => '<!-- wp:paragraph --><p>这是一个段落。</p><!-- /wp:paragraph -->' // 模式的内容 (HTML)
        )
    );

    register_block_pattern(
        'my-theme/my-simple-pattern',
        array(
            'title'      => '简单模式',
            'categories' => array( 'another-category' ),
            'content'    => '<!-- wp:heading {"level":3} --><h3>这是一个标题</h3><!-- /wp:heading -->'
        )
    );
}

这段代码注册了两个区块模式：

• 'my-theme/my-awesome-pattern'： 这个模式被分配到了 my-custom-category 和 another-category 两个分类中。
• 'my-theme/my-simple-pattern'： 这个模式只被分配到了 another-category 分类中。
• 'content'： 这个属性定义了模式的内容，使用 HTML 格式的区块代码。 你可以通过在区块编辑器中创建你想要的组合，然后切换到“代码编辑器”模式，复制生成的 HTML 代码。

5. 实践案例：创建一个包含标题和图像的区块模式分类

现在，让我们来一个更具体的例子。假设我们想要创建一个包含标题和图像的区块模式分类，方便用户快速添加带图片的标题。

首先，注册分类：

add_action( 'init', 'my_image_heading_category' );

function my_image_heading_category() {
    register_block_pattern_category(
        'image-heading',
        array( 'label' => __( '标题与图像', 'my-theme' ) )
    );
}

接下来，注册区块模式：

add_action( 'init', 'my_image_heading_patterns' );

function my_image_heading_patterns() {
    register_block_pattern(
        'my-theme/image-heading-left',
        array(
            'title'      => __( '图像在左，标题在右', 'my-theme' ),
            'categories' => array( 'image-heading' ),
            'content'    => '<!-- wp:columns {"verticalAlignment":"center"} -->
            <div class="wp-block-columns are-vertically-aligned-center"><!-- wp:column {"width":"33.33%"} -->
            <div class="wp-block-column" style="flex-basis:33.33%"><!-- wp:image {"sizeSlug":"large"} -->
            <figure class="wp-block-image size-large"><img src="https://via.placeholder.com/300x200" alt="占位图"/></figure>
            <!-- /wp:image --></div>
            <!-- /wp:column -->

            <!-- wp:column {"width":"66.66%"} -->
            <div class="wp-block-column" style="flex-basis:66.66%"><!-- wp:heading -->
            <h2>这是一个标题</h2>
            <!-- /wp:heading -->

            <!-- wp:paragraph -->
            <p>这是一段描述。</p>
            <!-- /wp:paragraph --></div>
            <!-- /wp:column --></div>
            <!-- /wp:columns -->'
        )
    );

    register_block_pattern(
        'my-theme/image-heading-right',
        array(
            'title'      => __( '图像在右，标题在左', 'my-theme' ),
            'categories' => array( 'image-heading' ),
            'content'    => '<!-- wp:columns {"verticalAlignment":"center"} -->
            <div class="wp-block-columns are-vertically-aligned-center"><!-- wp:column {"width":"66.66%"} -->
            <div class="wp-block-column" style="flex-basis:66.66%"><!-- wp:heading -->
            <h2>这是一个标题</h2>
            <!-- /wp:heading -->

            <!-- wp:paragraph -->
            <p>这是一段描述。</p>
            <!-- /wp:paragraph --></div>
            <!-- /wp:column -->

            <!-- wp:column {"width":"33.33%"} -->
            <div class="wp-block-column" style="flex-basis:33.33%"><!-- wp:image {"sizeSlug":"large"} -->
            <figure class="wp-block-image size-large"><img src="https://via.placeholder.com/300x200" alt="占位图"/></figure>
            <!-- /wp:image --></div>
            <!-- /wp:column --></div>
            <!-- /wp:columns -->'
        )
    );
}

这段代码注册了两个模式：

• 'my-theme/image-heading-left'： 图像在左边，标题和描述在右边。
• 'my-theme/image-heading-right'： 图像在右边，标题和描述在左边。

注意：

• https://via.placeholder.com/300x200 只是一个占位图的 URL，你需要替换成你自己的图片 URL。
• 模式内容中的 HTML 代码使用了区块的注释语法。

6. 最佳实践和注意事项

• 命名空间： 区块模式和分类的名称都应该包含命名空间，以避免与其他主题或插件冲突。 通常，你可以使用你的主题或插件的名称作为命名空间（例如，my-theme/my-awesome-pattern）。
• 文本域： 在翻译文本时，务必使用正确的文本域，以便 WordPress 能够正确地翻译你的字符串。
• 代码组织： 如果你的主题或插件有很多区块模式和分类，最好将代码组织成单独的文件，并在主文件中引用它们，以保持代码的整洁性。
• 性能优化： 避免注册过多的区块模式，因为这可能会影响区块编辑器的性能。 只注册那些真正需要的模式。
• 错误处理： 虽然 register_block_pattern_category() 和 register_block_pattern() 函数在注册失败时会返回 false，但你可能需要添加额外的错误处理代码，以确保你的代码在出现问题时能够正常运行。
• 动态内容： 如果你的区块模式需要包含动态内容（例如，来自数据库的数据），你可以使用 render_callback 属性，在模式渲染时动态生成内容。 这需要更高级的技巧，超出本文的范围。
• 更新现有分类： 你不能直接修改或删除已注册的区块模式分类。 如果你需要更改分类的标签，你需要先取消注册该分类，然后再重新注册它。 但是，不建议这样做，因为它可能会影响其他使用该分类的区块模式。

7. 常见问题解答

问题	答案
为什么我的分类没有显示在区块编辑器中？	确保你已经正确地注册了分类，并且至少有一个区块模式被分配到了该分类中。 检查你的代码中是否有任何错误，例如拼写错误或语法错误。 清空你的浏览器缓存，因为有时候旧的缓存会导致区块编辑器显示不正确。 确保你的主题或插件已经激活。
如何修改已注册的分类的标签？	你不能直接修改已注册的分类的标签。 你需要先取消注册该分类，然后再重新注册它。 但是，不建议这样做，因为它可能会影响其他使用该分类的区块模式。
如何取消注册一个区块模式分类？	你可以使用 unregister_block_pattern_category() 函数来取消注册一个区块模式分类。 该函数接收一个参数：要取消注册的分类的名称。 例如：unregister_block_pattern_category( 'my-custom-category' ); 同样，不建议随便取消注册分类，因为这会影响使用该分类的区块模式。
如何在区块模式中使用自定义字段？	你可以使用 render_callback 属性，在模式渲染时动态生成内容。 这允许你在模式中使用自定义字段和其他动态数据。 这需要更高级的技巧，超出本文的范围。
如何为区块模式添加预览图？	WordPress 本身并没有提供直接为区块模式添加预览图的功能。 但是，你可以通过在模式的 content 属性中包含一个代表性的图像，来间接实现预览效果。 另一种方法是使用第三方插件，这些插件通常提供更高级的区块模式管理功能，包括预览图。

8. 总结

register_block_pattern_category() 是一个简单但强大的函数，可以帮助我们更好地组织和管理区块模式。 通过使用自定义的区块模式分类，我们可以为用户提供更便捷、更高效的区块编辑体验。

记住，掌握这些“花花肠子”，才能在 WordPress 的世界里玩得更溜！ 好了，今天的讲座就到这里。 感谢各位的收听，咱们下期再见！