云策 WordPress 开发者社区

函数文档

register_block_pattern()

查看官方原文 ↗
💡 云策文档标注

概述

register_block_pattern() 函数用于在 WordPress 中注册一个新的块模式，通过 WP_Block_Patterns_Registry 类实现。它接受模式名称和属性数组作为参数，返回布尔值表示注册是否成功。

关键要点

  • 函数参数：$pattern_name（必需，包含命名空间的块模式名称）和 $pattern_properties（必需，属性数组，参考 WP_Block_Patterns_Registry::register()）。
  • 返回值：布尔值，成功注册返回 true，否则返回 false。
  • 内部实现：调用 WP_Block_Patterns_Registry::get_instance()->register() 方法。
  • 最佳实践：建议在 init 钩子中调用 register_block_pattern()，以避免编辑器错误。
  • 属性数组包括 title（必需）、content（必需）、description、categories、keywords 和 viewportWidth 等字段。
  • 块模式可以分配到多个类别，使用数组指定 categories。
  • 从 WordPress 6.0 开始，块主题可以通过 /patterns 子文件夹中的 PHP 文件注册模式。
  • 移除核心块模式时，确保至少注册一个块模式类别，防止编辑器崩溃。

代码示例

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

注意事项

  • 注册块模式时，应使用 init 钩子，避免直接从 functions.php 调用导致编辑器错误。
  • 确保属性数组中的 title 和 content 为必需字段，description 虽可选但推荐提供。
  • 使用 remove_theme_support('core-block-patterns') 移除核心模式时，需注册至少一个类别。
📄 原文内容

Registers a new block pattern.

Parameters

$pattern_namestringrequired
Block pattern name including namespace.
$pattern_propertiesarrayrequired
List of properties for the block pattern.
See WP_Block_Patterns_Registry::register() for accepted arguments.

Return

bool True if the pattern was registered with success and false otherwise.

Source

function register_block_pattern( $pattern_name, $pattern_properties ) {
	return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
}

View all references View on Trac View on GitHub

Uses Description
WP_Block_Patterns_Registry::get_instance()wp-includes/class-wp-block-patterns-registry.php

Utility method to retrieve the main instance of the class.
Used by Description
_register_remote_theme_patterns()wp-includes/block-patterns.php

Registers patterns from Pattern Directory provided by a theme’s theme.json file.
_register_theme_block_patterns()wp-includes/block-patterns.php

Register any patterns that the active theme may provide under its ./patterns/ directory.
_load_remote_featured_patterns()wp-includes/block-patterns.php

Register Featured (category) patterns from wordpress.org/patterns.
_load_remote_block_patterns()wp-includes/block-patterns.php

Register Core’s official patterns from wordpress.org/patterns.
_register_core_block_patterns_and_categories()wp-includes/block-patterns.php

Registers the core block patterns and categories.

Changelog

Version Description
5.5.0 Introduced.

User Contributed Notes

  1. Skip to note 6 content


    Christina Blust


    You must log in to vote on the helpfulness of this noteVote results for this note: 11You must log in to vote on the helpfulness of this note

    Per the Block Patterns documentation in the Block Editor Handbook, the $pattern_properties array includes:

    • title (required): A human-readable title for the pattern.
    • content (required): Raw HTML content for the pattern.
    • description: A visually hidden text used to describe the pattern in the inserter. A description is optional but it is strongly encouraged when the title does not fully describe what the pattern does.
    • categories: A list of pattern categories used to group block patterns. Block patterns can be shown on multiple categories.
    • keywords: Aliases or keywords that help users discover it while searching.
    • viewportWidth: Specify the width of the pattern in the inserter.

    and the example function given is:

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

  3. Skip to note 8 content


    mikehealy


    You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note

    The docs & handbook don’t seem to mention it, but I gather register_block_pattern() should be called from a handler attached to the init hook.

    function wpdocs_register_my_patterns() {
  register_block_pattern( ... );
}

add_action( 'init', 'wpdocs_register_my_patterns' );

  5. Skip to note 10 content


    thejaydip


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    A basic example of how to register a new pattern block.

    function wpdocs_register_block_patterns() {
        register_block_pattern(
            'wpdocs/my-example',
            array(
                'title'         => __( 'My First Block Pattern', 'textdomain' ),
                'description'   => _x( 'This is my first block pattern', 'Block pattern description', 'textdomain' ),
                'content'       => '<!-- wp:paragraph --><p>A single paragraph block style</p><!-- /wp:paragraph -->',
                'categories'    => array( 'text' ),
                'keywords'      => array( 'cta', 'demo', 'example' ),
                'viewportWidth' => 800,
            )
        );
}
add_action( 'init', 'wpdocs_register_block_patterns' );