WP_Block_Pattern_Categories_Registry
云策文档标注
概述
WP_Block_Pattern_Categories_Registry 是 WordPress 中用于管理块模式类别的核心类，提供注册、注销和查询功能。它采用单例模式，确保全局唯一实例，并支持区分在 `init` 动作内外注册的类别。
关键要点
- 类用于与块模式类别交互，包括注册、注销、查询等操作。
- 提供单例方法 WP_Block_Pattern_Categories_Registry::get_instance() 获取主实例。
- 主要方法包括 register()、unregister()、get_registered()、get_all_registered() 和 is_registered()。
- 支持参数验证和错误处理，如使用 _doing_it_wrong() 提示无效输入。
- 内部维护两个数组：registered_categories 和 registered_categories_outside_init，用于跟踪不同时机注册的类别。
代码示例
// 注册一个块模式类别
$registry = WP_Block_Pattern_Categories_Registry::get_instance();
$registry->register( 'my-category', array( 'label' => 'My Category Label' ) );
// 检查类别是否注册
if ( $registry->is_registered( 'my-category' ) ) {
// 获取类别属性
$category = $registry->get_registered( 'my-category' );
}
// 注销类别
$registry->unregister( 'my-category' );
// 获取所有注册的类别
$all_categories = $registry->get_all_registered();注意事项
- 类别名称必须是字符串，否则 register() 方法会返回 false 并触发 _doing_it_wrong() 警告。
- 注销未注册的类别时，unregister() 方法会返回 false 并提示错误。
- get_all_registered() 方法可选参数 $outside_init_only，用于仅返回在 `init` 动作外注册的类别。
- 类为 final，不可被继承，确保实例一致性。
原文内容
Class used for interacting with block pattern categories.
Methods
| Name | Description |
|---|---|
| WP_Block_Pattern_Categories_Registry::get_all_registered | Retrieves all registered pattern categories. |
| WP_Block_Pattern_Categories_Registry::get_instance | Utility method to retrieve the main instance of the class. |
| WP_Block_Pattern_Categories_Registry::get_registered | Retrieves an array containing the properties of a registered pattern category. |
| WP_Block_Pattern_Categories_Registry::is_registered | Checks if a pattern category is registered. |
| WP_Block_Pattern_Categories_Registry::register | Registers a pattern category. |
| WP_Block_Pattern_Categories_Registry::unregister | Unregisters a pattern category. |
Source
final class WP_Block_Pattern_Categories_Registry {
/**
* Registered block pattern categories array.
*
* @since 5.5.0
* @var array[]
*/
private $registered_categories = array();
/**
* Pattern categories registered outside the `init` action.
*
* @since 6.0.0
* @var array[]
*/
private $registered_categories_outside_init = array();
/**
* Container for the main instance of the class.
*
* @since 5.5.0
* @var WP_Block_Pattern_Categories_Registry|null
*/
private static $instance = null;
/**
* Registers a pattern category.
*
* @since 5.5.0
*
* @param string $category_name Pattern category name including namespace.
* @param array $category_properties {
* List of properties for the block pattern category.
*
* @type string $label Required. A human-readable label for the pattern category.
* }
* @return bool True if the pattern was registered with success and false otherwise.
*/
public function register( $category_name, $category_properties ) {
if ( ! isset( $category_name ) || ! is_string( $category_name ) ) {
_doing_it_wrong(
__METHOD__,
__( 'Block pattern category name must be a string.' ),
'5.5.0'
);
return false;
}
$category = array_merge(
array( 'name' => $category_name ),
$category_properties
);
$this->registered_categories[ $category_name ] = $category;
// If the category is registered inside an action other than `init`, store it
// also to a dedicated array. Used to detect deprecated registrations inside
// `admin_init` or `current_screen`.
if ( current_action() && 'init' !== current_action() ) {
$this->registered_categories_outside_init[ $category_name ] = $category;
}
return true;
}
/**
* Unregisters a pattern category.
*
* @since 5.5.0
*
* @param string $category_name Pattern category name including namespace.
* @return bool True if the pattern was unregistered with success and false otherwise.
*/
public function unregister( $category_name ) {
if ( ! $this->is_registered( $category_name ) ) {
_doing_it_wrong(
__METHOD__,
/* translators: %s: Block pattern name. */
sprintf( __( 'Block pattern category "%s" not found.' ), $category_name ),
'5.5.0'
);
return false;
}
unset( $this->registered_categories[ $category_name ] );
unset( $this->registered_categories_outside_init[ $category_name ] );
return true;
}
/**
* Retrieves an array containing the properties of a registered pattern category.
*
* @since 5.5.0
*
* @param string $category_name Pattern category name including namespace.
* @return array|null Registered pattern properties, or `null` if the pattern category is not registered.
*/
public function get_registered( $category_name ) {
if ( ! $this->is_registered( $category_name ) ) {
return null;
}
return $this->registered_categories[ $category_name ];
}
/**
* Retrieves all registered pattern categories.
*
* @since 5.5.0
*
* @param bool $outside_init_only Return only categories registered outside the `init` action.
* @return array[] Array of arrays containing the registered pattern categories properties.
*/
public function get_all_registered( $outside_init_only = false ) {
return array_values(
$outside_init_only
? $this->registered_categories_outside_init
: $this->registered_categories
);
}
/**
* Checks if a pattern category is registered.
*
* @since 5.5.0
*
* @param string|null $category_name Pattern category name including namespace.
* @return bool True if the pattern category is registered, false otherwise.
*/
public function is_registered( $category_name ) {
return isset( $category_name, $this->registered_categories[ $category_name ] );
}
/**
* Utility method to retrieve the main instance of the class.
*
* The instance will be created if it does not exist yet.
*
* @since 5.5.0
*
* @return WP_Block_Pattern_Categories_Registry The main instance.
*/
public static function get_instance() {
if ( null === self::$instance ) {
self::$instance = new self();
}
return self::$instance;
}
}