WP_Block_Type_Registry
云策文档标注
概述
WP_Block_Type_Registry 是 WordPress 核心类，用于管理块类型的注册、检索和注销。它提供单例模式访问，确保全局一致性。
关键要点
- 核心方法包括 register()、unregister()、get_registered()、get_all_registered() 和 is_registered()，用于块类型生命周期管理。
- 块类型名称必须为小写字符串，遵循命名空间格式（如 my-plugin/my-block），否则会触发 _doing_it_wrong() 警告。
- 使用 get_instance() 获取类的主实例，支持单例模式，避免重复创建。
- 内部维护 $registered_block_types 数组存储已注册块类型，键为名称，值为 WP_Block_Type 实例。
代码示例
// 注册一个块类型
$registry = WP_Block_Type_Registry::get_instance();
$block_type = $registry->register( 'my-plugin/my-block', array(
'title' => 'My Block',
'category' => 'widgets',
'icon' => 'smiley',
'render_callback' => 'my_block_render_callback'
) );
// 检索已注册块类型
$block = $registry->get_registered( 'my-plugin/my-block' );
if ( $block ) {
echo $block->title; // 输出: My Block
}
// 检查块类型是否注册
if ( $registry->is_registered( 'my-plugin/my-block' ) ) {
echo 'Block is registered.';
}
// 注销块类型
$unregistered = $registry->unregister( 'my-plugin/my-block' );注意事项
- register() 方法接受字符串名称或 WP_Block_Type 实例，参数 $args 对应 WP_Block_Type 的公共属性。
- 重复注册或注销未注册的块类型会触发 _doing_it_wrong() 警告并返回 false。
- __wakeup() 方法用于反序列化时验证 $registered_block_types 数组的完整性，确保所有值为 WP_Block_Type 实例。
- 自 WordPress 5.0.0 引入，是块编辑器（Gutenberg）的基础组件之一。
原文内容
Core class used for interacting with block types.
Methods
| Name | Description |
|---|---|
| WP_Block_Type_Registry::__wakeup | – |
| WP_Block_Type_Registry::get_all_registered | Retrieves all registered block types. |
| WP_Block_Type_Registry::get_instance | Utility method to retrieve the main instance of the class. |
| WP_Block_Type_Registry::get_registered | Retrieves a registered block type. |
| WP_Block_Type_Registry::is_registered | Checks if a block type is registered. |
| WP_Block_Type_Registry::register | Registers a block type. |
| WP_Block_Type_Registry::unregister | Unregisters a block type. |
Source
final class WP_Block_Type_Registry {
/**
* Registered block types, as `$name => $instance` pairs.
*
* @since 5.0.0
* @var WP_Block_Type[]
*/
private $registered_block_types = array();
/**
* Container for the main instance of the class.
*
* @since 5.0.0
* @var WP_Block_Type_Registry|null
*/
private static $instance = null;
/**
* Registers a block type.
*
* @since 5.0.0
*
* @see WP_Block_Type::__construct()
*
* @param string|WP_Block_Type $name Block type name including namespace, or alternatively
* a complete WP_Block_Type instance. In case a WP_Block_Type
* is provided, the $args parameter will be ignored.
* @param array $args Optional. Array of block type arguments. Accepts any public property
* of `WP_Block_Type`. See WP_Block_Type::__construct() for information
* on accepted arguments. Default empty array.
* @return WP_Block_Type|false The registered block type on success, or false on failure.
*/
public function register( $name, $args = array() ) {
$block_type = null;
if ( $name instanceof WP_Block_Type ) {
$block_type = $name;
$name = $block_type->name;
}
if ( ! is_string( $name ) ) {
_doing_it_wrong(
__METHOD__,
__( 'Block type names must be strings.' ),
'5.0.0'
);
return false;
}
if ( preg_match( '/[A-Z]+/', $name ) ) {
_doing_it_wrong(
__METHOD__,
__( 'Block type names must not contain uppercase characters.' ),
'5.0.0'
);
return false;
}
$name_matcher = '/^[a-z0-9-]+/[a-z0-9-]+$/';
if ( ! preg_match( $name_matcher, $name ) ) {
_doing_it_wrong(
__METHOD__,
__( 'Block type names must contain a namespace prefix. Example: my-plugin/my-custom-block-type' ),
'5.0.0'
);
return false;
}
if ( $this->is_registered( $name ) ) {
_doing_it_wrong(
__METHOD__,
/* translators: %s: Block name. */
sprintf( __( 'Block type "%s" is already registered.' ), $name ),
'5.0.0'
);
return false;
}
if ( ! $block_type ) {
$block_type = new WP_Block_Type( $name, $args );
}
$this->registered_block_types[ $name ] = $block_type;
return $block_type;
}
/**
* Unregisters a block type.
*
* @since 5.0.0
*
* @param string|WP_Block_Type $name Block type name including namespace, or alternatively
* a complete WP_Block_Type instance.
* @return WP_Block_Type|false The unregistered block type on success, or false on failure.
*/
public function unregister( $name ) {
if ( $name instanceof WP_Block_Type ) {
$name = $name->name;
}
if ( ! $this->is_registered( $name ) ) {
_doing_it_wrong(
__METHOD__,
/* translators: %s: Block name. */
sprintf( __( 'Block type "%s" is not registered.' ), $name ),
'5.0.0'
);
return false;
}
$unregistered_block_type = $this->registered_block_types[ $name ];
unset( $this->registered_block_types[ $name ] );
return $unregistered_block_type;
}
/**
* Retrieves a registered block type.
*
* @since 5.0.0
*
* @param string|null $name Block type name including namespace.
* @return WP_Block_Type|null The registered block type, or null if it is not registered.
*/
public function get_registered( $name ) {
if ( ! $this->is_registered( $name ) ) {
return null;
}
return $this->registered_block_types[ $name ];
}
/**
* Retrieves all registered block types.
*
* @since 5.0.0
*
* @return WP_Block_Type[] Associative array of `$block_type_name => $block_type` pairs.
*/
public function get_all_registered() {
return $this->registered_block_types;
}
/**
* Checks if a block type is registered.
*
* @since 5.0.0
*
* @param string|null $name Block type name including namespace.
* @return bool True if the block type is registered, false otherwise.
*/
public function is_registered( $name ) {
return isset( $name, $this->registered_block_types[ $name ] );
}
public function __wakeup() {
if ( ! $this->registered_block_types ) {
return;
}
if ( ! is_array( $this->registered_block_types ) ) {
throw new UnexpectedValueException();
}
foreach ( $this->registered_block_types as $value ) {
if ( ! $value instanceof WP_Block_Type ) {
throw new UnexpectedValueException();
}
}
}
/**
* Utility method to retrieve the main instance of the class.
*
* The instance will be created if it does not exist yet.
*
* @since 5.0.0
*
* @return WP_Block_Type_Registry The main instance.
*/
public static function get_instance() {
if ( null === self::$instance ) {
self::$instance = new self();
}
return self::$instance;
}
}
Changelog
| Version | Description |
|---|---|
| 5.0.0 | Introduced. |