206 lines
8.9 KiB
Markdown
206 lines
8.9 KiB
Markdown
## 语义化区块模式
|
||
|
||
在区块主题中，您还可以将区块模式标记为"页眉"或"页脚"模式（模板部件区域）。我们称之为"语义化区块模式"。当用户插入或替换页眉/页脚模板部件时，这些模式将会显示给用户。
|
||
|
||
示例：
|
||
|
||
```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 -->',
|
||
)
|
||
);
|
||
```
|
||
|
||
在上面的示例中，如果我们选择**两个区块类型中的任意一个**，无论是段落块还是标题块，此模式都将通过转换所选块的内容来建议，并且还会添加模式中剩余的块。另一方面，如果我们多选一个段落块和一个标题块，则这两个块都将被转换。
|
||
|
||
区块也可以在其他地方使用这些上下文区块模式。例如，当插入新的查询循环块时，会向用户提供附加到该块的所有模式的列表。 |