## 语义化区块模式

在区块主题中，您还可以将区块模式标记为"页眉"或"页脚"模式（模板部件区域）。我们称之为"语义化区块模式"。当用户插入或替换页眉/页脚模板部件时，这些模式将会显示给用户。

示例：

```php
<?php
register_block_pattern(
	'my-plugin/my-header',
	array(
		'title'      => __( '我的页眉', 'my-plugin' ),
		'categories' => array( 'header' ),
		// 将该模式指定至"header"区域
		'blockTypes' => array( 'core/template-part/header' ),
		'content'    => '我的区块模式内容',
	)
);
```

# 区块模式

区块模式是从区块插入器的模式选项卡中可用的预定义区块布局。一旦插入到内容中，这些区块即可用于添加或修改内容及配置。

## 区块模式

### register_block_pattern

编辑器自带若干核心区块模式。主题和插件作者可以使用 `register_block_pattern` 辅助函数来注册额外的自定义区块模式。

`register_block_pattern` 辅助函数接收两个参数：
-   `title`：一个遵循 `命名空间/标题` 命名约定的机器可读标题。
-   `properties`：描述模式属性的数组。

区块模式可用的属性包括：

-   `title`（必需）：模式的人类可读标题。
-   `content`（必需）：模式的区块 HTML 标记。
-   `description`（可选）：在插入器中用于描述模式的视觉隐藏文本。描述是可选的，但当标题未能完全说明模式功能时，强烈建议提供。描述将帮助用户在搜索时发现该模式。
-   `categories`（可选）：用于对区块模式进行分组的已注册模式类别数组。区块模式可显示在多个类别中。类别必须单独注册才能在此处使用。
-   `keywords`（可选）：帮助用户在搜索时发现模式的别名或关键词数组。
-   `viewportWidth`（可选）：指定模式预期宽度的整数，以便在插入器中显示模式的缩放预览。
-   `blockTypes`（可选）：模式预期与之配合使用的区块类型数组。每个值需为已声明区块的 `name`。
-   `postTypes`（可选）：模式限制与之配合使用的文章类型数组。该模式仅在编辑数组中传递的某一文章类型时可用。对于所有其他文章类型，该模式完全不可用。
-   `templateTypes`（可选）：模式适用的模板类型数组，例如，如果模式用于 404 页面，则为 `404`；如果模式用于显示单篇文章，则为 `single-post`。
-   `inserter`（可选）：默认情况下，所有模式都会出现在插入器中。若要隐藏模式，使其只能通过编程方式插入，请将 `inserter` 设置为 `false`。
-   `source`（可选）：表示模式来源的字符串。对于注册模式的插件，传递字符串 `plugin`；对于主题，传递字符串 `theme`。

以下代码示例注册了一个名为 `my-plugin/my-awesome-pattern` 的区块模式：

```php
register_block_pattern(
	'my-plugin/my-awesome-pattern',
	array(
		'title'       => __( '两个按钮', 'my-plugin' ),
		'description' => _x( '两个水平按钮，左侧按钮为实心填充，右侧按钮为轮廓样式。', '区块模式描述', 'my-plugin' ),
		'content'     => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">" . esc_html__( '按钮一', 'my-plugin' ) . "</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">" . esc_html__( '按钮二', 'my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
	)
);
```

请注意，`register_block_pattern()` 应从附加到 `init` 钩子的处理程序中调用。

```php
function my_plugin_register_my_patterns() {
  register_block_pattern( ... );
}

add_action( 'init', 'my_plugin_register_my_patterns' );
```

## 取消注册区块模式

### unregister_block_pattern

`unregister_block_pattern` 辅助函数允许从主题或插件中取消注册先前已注册的区块模式，它接收一个参数。

-   `title`：要取消注册的区块模式的名称。

以下代码示例取消了名为 `my-plugin/my-awesome-pattern` 的区块模式的注册：

```php
unregister_block_pattern( 'my-plugin/my-awesome-pattern' );
```

_注意：_

`unregister_block_pattern()` 应在附加到 init 钩子的处理程序中调用。

```php
function my_plugin_unregister_my_patterns() {
  unregister_block_pattern( ... );
}

add_action( 'init', 'my_plugin_unregister_my_patterns' );
```

## 区块模式分类

区块模式可以使用分类进行分组。区块编辑器自带了一些捆绑的分类，您可以在自定义区块模式中使用。您也可以注册自己的区块模式分类。

### register_block_pattern_category

`register_block_pattern_category` 辅助函数接收两个参数。

-   `title`：区块模式分类的机器可读标题。
-   `properties`：描述模式分类属性的数组。

模式分类的属性包括：

-   `label`（必需）：模式分类的人类可读标签。

以下代码示例注册了名为 `hero` 的分类：

```php
register_block_pattern_category(
	'hero',
	array( 'label' => __( 'Hero', 'my-plugin' ) )
);
```

_注意：_

`register_block_pattern_category()` 应在附加到 init 钩子的处理程序中调用。

除非有模式被分配到此分类，否则该分类不会显示在“模式”下。

```php
function my_plugin_register_my_pattern_categories() {
  register_block_pattern_category( ... );
}

add_action( 'init', 'my_plugin_register_my_pattern_categories' );
```

### unregister_block_pattern_category

`unregister_block_pattern_category` 辅助函数允许从主题或插件中取消注册先前已注册的区块模式分类，它接收一个参数。

-   `title`：要取消注册的区块模式分类的名称。

以下代码示例取消了名为 `hero` 的分类的注册：

```php
unregister_block_pattern_category( 'hero' );
```

_注意：_

`unregister_block_pattern_category()` 应在附加到 init 钩子的处理程序中调用。

```php
function my_plugin_unregister_my_pattern_categories() {
  unregister_block_pattern_category( ... );
}

add_action( 'init', 'my_plugin_unregister_my_pattern_categories' );
```

## 特定于区块类型的区块模式和模式转换

可以将一个区块模式附加到一个或多个区块类型。这会将该区块模式添加为该区块类型的可用转换。

目前，这些转换仅适用于简单区块（没有内部块的区块）。为了建议某个模式，**所选中的每个块都必须存在于该区块模式中**。

例如：

```php
register_block_pattern(
	'my-plugin/powered-by-wordpress',
	array(
		'title'      => __( 'Powered by WordPress', 'my-plugin' ),
		'blockTypes' => array( 'core/paragraph' ),
		'content'    => '<!-- wp:paragraph {"backgroundColor":"black","textColor":"white"} -->
		<p class="has-white-color has-black-background-color has-text-color has-background">Powered by WordPress</p>
		<!-- /wp:paragraph -->',
	)
);
```

上面的代码注册了一个名为 `my-plugin/powered-by-wordpress` 的区块模式，并在段落块的“转换菜单”中显示该模式。转换结果将保留段落的现有内容并应用其他属性——在本例中为背景色和文本颜色。

如上所述，如果我们选择了多个块，并且存在与这些块匹配的上下文模式，那么简单区块的模式转换也可以工作。让我们看一个附加了两个区块类型的模式示例。

```php
register_block_pattern(
	'my-plugin/powered-by-wordpress',
	array(
		'title'      => __( 'Powered by WordPress', 'my-plugin' ),
		'blockTypes' => array( 'core/paragraph', 'core/heading' ),
		'content'    => '<!-- wp:group -->
						<div class="wp-block-group">
						<!-- wp:heading {"fontSize":"large"} -->
						<h2 class="has-large-font-size"><span style="color:#ba0c49" class="has-inline-color">Hi everyone</span></h2>
						<!-- /wp:heading -->
						<!-- wp:paragraph {"backgroundColor":"black","textColor":"white"} -->
						<p class="has-white-color has-black-background-color has-text-color has-background">Powered by WordPress</p>
						<!-- /wp:paragraph -->
						</div><!-- /wp:group -->',
	)
);
```

在上面的示例中，如果我们选择**两个区块类型中的任意一个**，无论是段落块还是标题块，此模式都将通过转换所选块的内容来建议，并且还会添加模式中剩余的块。另一方面，如果我们多选一个段落块和一个标题块，则这两个块都将被转换。

区块也可以在其他地方使用这些上下文区块模式。例如，当插入新的查询循环块时，会向用户提供附加到该块的所有模式的列表。