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

区块模式

register_block_pattern

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

register_block_pattern 辅助函数接收两个参数。
– title：具有 namespace/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 的区块模式：

register_block_pattern(
    'my-plugin/my-awesome-pattern',
    array(
        'title'       => __( 'Two buttons', 'my-plugin' ),
        'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', '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__( 'Button One', '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__( 'Button Two', 'my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
    )
);

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

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 的区块模式：

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

注意：

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

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 的类别：

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

注意：

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

除非已分配模式给该类别，否则该类别不会显示在“模式”下。

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 的类别：

unregister_block_pattern_category( 'hero' );

注意：

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

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

add_action( 'init', 'my_plugin_unregister_my_pattern_categories' );

与区块类型和模式转换相关的区块模式

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

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

例如：

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 的区块模式，并在段落区块的“转换菜单”中显示该模式。转换结果将保留段落的现有内容并应用其他属性——在本例中为背景和文本颜色。

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

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">大家好</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 -->',
    )
);

在上述示例中，如果我们选择两种块类型之一，即段落块或标题块，此模式将通过转换所选块的内容来建议，并且还会添加来自该模式的其余块。另一方面，如果我们多选一个段落块和一个标题块，这两个块都将被转换。

块还可以在其他地方使用这些上下文块模式。例如，当插入一个新的查询循环块时，用户将获得与该块关联的所有模式的列表。

语义块模式

在块主题中，您还可以将块模式标记为“页眉”或“页脚”模式（模板部分区域）。我们称之为“语义块模式”。这些模式在向用户显示插入或替换页眉或页脚模板部分时会出现。

示例：

<?php
register_block_pattern(
    'my-plugin/my-header',
    array(
        'title'      => __( '我的页眉', 'my-plugin' ),
        'categories' => array( 'header' ),
        // 将模式分配给“页眉”区域。
        'blockTypes' => array( 'core/template-part/header' ),
        'content'    => '我的块模式的内容',
    )
);