块模式（已归档）

最后更新：2026-10-05 15:56:51

本文档现已归档，相关内容已被《主题手册》中更新的Patterns章节所替代。如需了解关于模式的最新信息，请参阅该页面。

块模式是主题开发者手中极为强大的功能之一。它自WordPress 5.4版本引入后，不仅让用户能够通过块编辑器轻松插入更复杂的布局，也为设计师们打开了全新的创作可能。

什么是块模式？

本质上，块模式就是一组预先配置好的块，呈现给最终用户使用。可以将它们视为可重复使用的块组。

它们非常适合用作用户在文章和页面内容中插入的起始元素，同时也可用于模板中。

用户可以通过站点编辑器直接将块模式添加到模板中，或通过文章编辑器将其添加到内容中：

WordPress文章编辑器，插入器中已选中Patterns > Featured类别，其中列出了一个块模式。

虽然文件头也与块模式类似，都是用于定义可重复使用的块组，但块模式还允许使用PHP代码，因此可以实现对文本的国际化处理、动态添加用于嵌入图片的URL等等。

另外，管理员还可以通过外观 > 编辑器 > 块模式页面来创建和管理自定义块模式。在自行开发的主题中，也可以使用该页面来管理自定义模式：

WordPress管理员后台的块模式库，显示All Patterns页面，右侧为预览框，其中展示了某个块模式。

使用块模式

在本节中，您将学习如何创建自定义块模式、在主题中注册它们以及取消注册。同时还会介绍一些实用技巧和方法，帮助您更高效地使用块模式。

创建块模式

学习创建块模式的最简单方法，是从在文章编辑器中组合几个块开始。这些块可以是任何类型，但为便于演示，下文提供的示例将使用一个核心的封面块，其中嵌套了其他块，结构如下：

Group
- Heading
- Paragraph
- Buttons
  - Button

建议您先试着自己构建这个结构，尤其是刚开始使用块编辑器的时候。虽然也可以根据需求对结构进行自定义，但初次创建模式时建议保持结构简洁。

完成后，点击工具栏中的⋮（选项）图标，然后选择复制：

这样就能得到可用于开发的代码，其内容大致如下：

<?php
/**
 * Title: Hero
 * Slug: themeslug/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"overlayColor":"contrast","align":"full"} -->
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-contrast-background-color has-background-dim-100 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:group {"style":{"spacing":{"blockGap":"2.5rem"}},"layout":{"type":"constrained","wideSize":"%","contentSize":"75%"}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">欢迎来到我的网站</h2>
<!-- /wp:heading -->

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">这里是我的个人空间，您可以在这里了解我。我会分享自己的兴趣爱好等内容，偶尔还会在博客中写些有趣的内容。</p>
<!-- /wp:paragraph -->

<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
<div class="wp-block-buttons"><!-- wp:button {"className":"is-style-outline"} -->
<div class="wp-block-button is-style-outline"><a class="wp-block-button__link wp-element-button">查看我的热门文章 →</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group --></div></div>
<!-- /wp:cover -->

在后续内容中，您将使用这个模式，学习如何注册、取消注册以及进一步自定义它。

通常建议将大多数模式包裹在Group、Cover或其他支持嵌套块的容器块中，这样主题用户就能更轻松地在编辑器中移动整个模式。此外，还可以为这些外部容器块添加CSS类，以便为整个模式应用自定义样式。

注册块模式

在WordPress中，有两种方式可以注册块模式：

将包含块标记的文件放入主题的/patterns文件夹中，让系统自动注册。
通过PHP手动调用register_block_pattern()函数来注册。

最简单的方法是第一种，后续章节会详细介绍两种方法的操作方式，不过除非有特殊需求，否则建议使用/patterns文件夹这种方式。

通过/patterns目录注册模式

如果使用自动注册方式，即将模式文件放入/patterns文件夹，那么就无法实现条件注册。这种情况下，就需要先取消注册该模式。

假设只有当core/paragraph块已注册时，才显示之前注册的“英雄”模式。实际上这里只是举例，现实中更多情况下是检查第三方块，而core/paragraph块仅作为示例使用。

可在functions.php文件中添加以下代码，取消注册之前注册的模式：

add_action( 'init', 'themeslug.unregister_patterns', 999 );

function themeslug.unregister_patterns() {
	if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) {
		unregister_block_pattern( 'themeslug/hero' );
	}
}

通过register_block_pattern()函数注册模式

如果是通过PHP手动注册模式，只需在调用register_block_pattern()时加入条件判断即可。

仍以之前的示例为例，若只有在core/paragraph块已注册时才注册该模式，可在functions.php中添加如下代码：

add_action( 'init', 'themeslug_register_patterns', 999 );

function themeslug_register_patterns() {
	if ( WP_Block_Type_Registry::get_instance()->is_registered( 'core/paragraph' ) ) {
		register_block_pattern( 'themeslug/hero', array(
			'title'      => __( '英雄', 'themeslug' ),
			'categories' => array( 'featured' ),
			'source'     => 'theme',
			'content'    => '<!-- 块模式内容此处 -->'
		) );
	}
}

模式类别

WordPress默认会注册多种块模式类别：

featured
about
audio（在WordPress 6.4中添加）
banner
buttons
call-to-action
columns
contact
footer
gallery
header
media
portfolio
posts
query（建议使用posts替代）
services
team
testimonials
text
video（在WordPress 6.4中添加）

通常建议在主题中使用这些默认类别，这样能够保持界面一致性，方便用户使用。不过有时也可能需要添加自定义类别，或删除已存在的类别。

在本节的内容中，您将学习如何注册和取消注册自定义块模式类别。

注册模式类别

要注册自定义模式类别，需使用register_block_pattern_category()函数：

register_block_pattern_category( 
	string $category_name, 
	array $category_properties 
): bool

该函数接受两个参数：

$category_name：类别的唯一标识/别名，建议在前面加上主题的别名，以便区分。
$category_properties：用于定义类别属性的数组，包含：
- label：类别的显示标签，可进行翻译。
- description：类别的描述，也可翻译。

可在主题的functions.php文件中添加以下代码，为主题注册一个自定义的themeslug/custom类别：

add_action( 'init', 'themeslug_register_pattern_categories' );

function themeslug_register_pattern_categories() {
	register_block_pattern_category( 'themeslug/custom', array( 
		'label'       => __( '主题名称：自定义', 'themeslug' ),
		'description' => __( '属于该主题的自定义模式。', 'themeslug' )
	) );
}

之后，将themeslug/custom类别添加到任何块模式中，该模式就会出现在插入器以及外观 > 编辑器 > 块模式页面中：

取消注册模式类别

要取消注册某个模式类别，需使用unregister_block_pattern_category()函数：

unregister_block_pattern_category( string $category_name ): bool

该函数仅接受一个参数：

$category_name：要取消注册的类别名称（即别名）。

可在functions.php文件中添加以下代码，删除之前注册的themeslug/custom类别：

add_action( 'init', 'themeslug.unregister_pattern_categories' );

function themeslug.unregister_pattern_categories() {
	unregister_block_pattern_category( 'themeslug/custom' );
}