解析 WordPress `register_block_pattern()` 函数源码：如何注册自定义区块模式以实现模板化。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷们，大家好！今天咱们来聊聊WordPress里一个相当实用的函数，register_block_pattern()。这玩意儿能让你像搭积木一样，快速构建自定义的区块模式，实现模板化，省时省力，逼格满满。

开场白：什么是区块模式？

想象一下，你经常需要在文章里插入一个固定的“作者简介”区块，包含头像、姓名、职称、简介等等。每次都手动添加、调整样式，是不是很烦？这时候，区块模式就派上用场了！你可以把这个“作者简介”区块保存为一个模式，以后直接调用，一键插入，岂不美哉？

register_block_pattern()：注册区块模式的核心函数

register_block_pattern()函数就是用来注册这些自定义区块模式的。它接受两个参数：

$pattern_name (string)：模式的唯一名称，必须是字符串，而且要符合WordPress的命名规范（小写字母、数字、短横线）。
$pattern_properties (array)：一个包含模式属性的数组，比如标题、内容等等。

$pattern_properties 数组的结构

这个数组是关键，决定了你的区块模式长什么样，包含哪些信息。下面我们来详细剖析一下：

键 (Key)	类型 (Type)	描述 (Description)	必填 (Required)	示例 (Example)
`title`	string	模式的标题，会在区块编辑器中显示，方便用户选择。	是	`'我的自定义标题'`
`content`	string	模式的内容，也就是实际的区块代码。这部分内容需要用标准的WordPress区块语法（HTML注释包裹的JSON）来编写。	是	`'<!-- wp:paragraph --><p>这是一个段落。</p><!-- /wp:paragraph -->'`
`description`	string	模式的描述，可以提供更详细的信息，帮助用户理解这个模式的用途。	否	`'这是一个用于显示作者简介的区块模式。'`
`categories`	array	一个字符串数组，用于将模式归类到不同的类别下。这样用户可以在区块编辑器中按照类别筛选模式。	否	`array( 'text', 'buttons' )`
`keywords`	array	一个字符串数组，用于添加关键词，方便用户通过搜索找到这个模式。	否	`array( '作者', '简介', 'bio' )`
`viewportWidth`	int	模式的预览宽度，单位是像素。这可以帮助用户在选择模式时更好地了解其布局。	否	`800`
`blockTypes`	array	一个字符串数组，指定这个模式只能在哪些区块类型下使用。例如，你可以限制某个模式只能在`core/post-content`区块中使用。	否	`array( 'core/post-content' )`
`inserter`	bool	一个布尔值，指定是否在区块编辑器中显示这个模式。默认为`true`。如果你不想让用户直接插入这个模式，可以设置为`false`。	否	`false`
`templateLock`	string/bool	控制模版锁定的行为。可以设置为 ‘all’，’insert’，或者 false。 ‘all’ 锁住所有区块的移动，删除。’insert’ 锁定插入区块。false 不锁定。	否	`'all'` 或者 `false`
`__experimental_use_block_active_when_inserter_open`	bool	一个布尔值，指定当插入器打开时，是否应使用块的活动状态。默认为 `false`。	否	`true`

代码示例：注册一个简单的段落模式

<?php
/**
 * 注册自定义区块模式.
 */
function my_theme_register_block_patterns() {
    register_block_pattern(
        'my-theme/simple-paragraph',
        array(
            'title'       => __( '简单段落', 'my-theme' ),
            'content'     => '<!-- wp:paragraph --><p>这是一个简单的段落，用于快速插入文本。</p><!-- /wp:paragraph -->',
            'description' => __( '一个简单的段落区块模式。', 'my-theme' ),
            'categories'  => array( 'text' ),
            'keywords'    => array( '段落', '文本', '简单' ),
        )
    );
}
add_action( 'init', 'my_theme_register_block_patterns' );

这段代码做了什么？

定义了一个名为 my_theme_register_block_patterns 的函数。
使用 register_block_pattern() 函数注册了一个名为 my-theme/simple-paragraph 的区块模式。
设置了模式的标题、内容、描述、类别和关键词。
使用 add_action( 'init', 'my_theme_register_block_patterns' ) 将这个函数挂载到 init 钩子上，确保在WordPress初始化时执行。

重点：content 的编写

content 属性是区块模式的核心，它定义了模式的实际内容。这部分内容必须使用标准的WordPress区块语法来编写，也就是用HTML注释包裹的JSON数据。

例如，一个简单的段落区块的JSON表示如下：

<!-- wp:paragraph -->
<p>这是一个段落。</p>
<!-- /wp:paragraph -->

如果你想包含多个区块，可以把它们的JSON表示拼接在一起：

<!-- wp:paragraph -->
<p>这是第一个段落。</p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":3} -->
<h3>这是一个三级标题</h3>
<!-- /wp:heading -->

更复杂的例子：注册一个包含图片和文本的模式

<?php
/**
 * 注册自定义区块模式.
 */
function my_theme_register_block_patterns() {
    register_block_pattern(
        'my-theme/image-text',
        array(
            'title'       => __( '图片加文本', 'my-theme' ),
            'content'     => '<!-- wp:columns --><div class="wp-block-columns"><!-- wp:column --><div class="wp-block-column"><!-- wp:image {"sizeSlug":"large"} --><figure class="wp-block-image size-large"><img src="' . get_template_directory_uri() . '/assets/images/placeholder.jpg" alt="占位符图片"/></figure><!-- /wp:image --></div><!-- /wp:column --><!-- wp:column --><div class="wp-block-column"><!-- wp:heading --><h2>标题</h2><!-- /wp:heading --><!-- wp:paragraph -->这是一个包含图片的段落。你可以修改图片和文本内容。<!-- /wp:paragraph --></div><!-- /wp:column --></div><!-- /wp:columns -->',
            'description' => __( '一个包含图片和文本的区块模式。', 'my-theme' ),
            'categories'  => array( 'media' ),
            'keywords'    => array( '图片', '文本', '图文' ),
        )
    );
}
add_action( 'init', 'my_theme_register_block_patterns' );

这个例子注册了一个包含两列的模式，左边是图片，右边是标题和段落。注意：

使用了 get_template_directory_uri() 函数获取主题目录的URL，方便引用主题内的图片。
sizeSlug 指定了图片的大小。
使用了 、 等区块语法来构建布局。

动态内容：使用 PHP 在 content 中插入数据

有时候，你可能需要在区块模式中插入动态内容，比如当前日期、网站标题等等。这时候，你可以在 content 属性中使用 PHP 代码：

<?php
/**
 * 注册自定义区块模式.
 */
function my_theme_register_block_patterns() {
    $current_date = date( 'Y-m-d' );
    $site_title   = get_bloginfo( 'name' );

    register_block_pattern(
        'my-theme/dynamic-content',
        array(
            'title'       => __( '动态内容', 'my-theme' ),
            'content'     => '<!-- wp:paragraph --><p>当前日期：' . $current_date . '</p><!-- /wp:paragraph --><!-- wp:paragraph --><p>网站标题：' . $site_title . '</p><!-- /wp:paragraph -->',
            'description' => __( '一个包含动态内容的区块模式。', 'my-theme' ),
            'categories'  => array( 'text' ),
            'keywords'    => array( '动态', '日期', '标题' ),
        )
    );
}
add_action( 'init', 'my_theme_register_block_patterns' );

高级技巧：使用 blockTypes 限制模式的使用范围

blockTypes 属性可以让你限制某个模式只能在特定的区块类型下使用。例如，你可以创建一个专门用于文章内容的模式，只允许在 core/post-content 区块中使用：

<?php
/**
 * 注册自定义区块模式.
 */
function my_theme_register_block_patterns() {
    register_block_pattern(
        'my-theme/post-content-pattern',
        array(
            'title'       => __( '文章内容模式', 'my-theme' ),
            'content'     => '<!-- wp:paragraph --><p>这是一段文章内容。</p><!-- /wp:paragraph -->',
            'description' => __( '一个用于文章内容的区块模式。', 'my-theme' ),
            'categories'  => array( 'text' ),
            'keywords'    => array( '文章', '内容' ),
            'blockTypes'  => array( 'core/post-content' ),
        )
    );
}
add_action( 'init', 'my_theme_register_block_patterns' );

实践建议：如何编写高质量的 content

使用区块编辑器生成代码： 最简单的方法是在区块编辑器中手动创建一个你想要的布局，然后切换到“代码编辑器”模式，复制生成的HTML代码，再将其粘贴到 content 属性中。
注意转义特殊字符： 如果你的 content 中包含单引号、双引号等特殊字符，需要进行转义，避免语法错误。可以使用 esc_attr() 函数进行转义。
保持代码整洁： 尽量对代码进行格式化，使其易于阅读和维护。可以使用代码编辑器提供的格式化功能。
使用占位符图片： 在开发阶段，可以使用占位符图片来代替真实的图片，提高开发效率。

调试技巧：如何排查区块模式注册失败的问题

检查代码语法： 确保你的PHP代码没有语法错误。
检查模式名称： 确保模式名称符合命名规范（小写字母、数字、短横线）。
检查 content 内容： 确保 content 属性的内容是有效的WordPress区块语法。
查看错误日志： 查看WordPress的错误日志，可能会有相关的错误信息。
使用调试工具： 使用WordPress的调试工具（例如 Query Monitor）来查看注册的区块模式是否成功。

总结：register_block_pattern() 的强大之处

register_block_pattern() 函数是WordPress主题开发中一个非常强大的工具，它可以让你：

快速构建自定义布局： 通过预定义的区块模式，可以快速构建各种复杂的布局，提高开发效率。
实现模板化： 将常用的布局保存为模式，方便在不同的文章或页面中重复使用，实现模板化。
提高用户体验： 用户可以通过简单的选择，快速插入预定义的布局，提高内容创作的效率。

结尾：希望大家学有所获，下次再见！

今天就讲到这里，希望大家能够掌握 register_block_pattern() 函数的使用方法，并在实际项目中灵活运用。记住，熟能生巧，多加练习才能真正掌握这项技能。下次有机会再给大家分享其他WordPress开发技巧，拜拜！

发表回复 取消回复

发表回复取消回复