6.9 KiB
区块注册
WordPress中的区块通常以插件形式打包，并通过block.json元数据在服务端和客户端进行注册。
虽然可以仅在客户端注册区块，但最佳实践强烈建议在服务端和客户端同时注册。这种双重注册对于启用服务端功能至关重要，例如动态渲染、区块支持、区块钩子和样式变体。若缺少服务端注册，这些功能将无法正常运行。
例如，若希望区块通过theme.json设置样式，则必须在服务端进行注册。否则，该区块将无法识别或应用在theme.json中为其分配的任何样式。
以下流程图详细说明了区块的注册过程。
使用PHP注册区块（服务端）
区块在服务端的注册通常发生在主插件PHP文件中，通过init钩子调用register_block_type()函数。该函数通过读取block.json文件中存储的元数据来简化区块类型注册。
此函数专为注册区块类型而设计，在此上下文中主要使用两个参数（虽然可支持更多变体）：
-
$block_type（字符串）： 可以是包含block.json文件的目录路径，或元数据文件的完整路径（如果文件名不同）。此参数告知WordPress在哪里查找区块配置。 -
$args（数组）： 这是一个可选参数，可用于指定区块类型的其他参数。默认情况下为空数组，但可以包含各种选项，其中之一是$render_callback。此回调用于在前端渲染区块，是block.json中render属性的替代方案。
在开发过程中，block.json文件通常作为代码编译的一部分从src（源）目录移动到build目录。因此，在注册区块时，请确保$block_type路径指向build目录中的block.json文件。
register_block_type()函数在成功时返回注册的区块类型（WP_Block_Type），失败时返回false。以下是一个使用render_callback的简单示例。
register_block_type(
__DIR__ . '/build',
array(
'render_callback' => 'render_block_core_notice',
)
);
以下是一个更完整的示例，包括init钩子。
function minimal_block_ca6eda___register_block() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'minimal_block_ca6eda___register_block' );
仅限PHP的自动注册区块
对于仅需服务端渲染的区块，您可以使用auto_register标志和render_callback在PHP中单独注册。这些区块会自动出现在编辑器中，无需任何JavaScript注册或客户端代码，并使用动态渲染。
register_block_type( 'my-plugin/server-block', array(
'render_callback' => function( $attributes ) {
$wrapper_attributes = get_block_wrapper_attributes();
return sprintf(
'<div %1$s>服务器内容</div>',
$wrapper_attributes
);
},
'supports' => array(
'auto_register' => true,
'color' => array(
'background' => true,
),
),
) );
使用JavaScript注册区块（客户端）
当区块已在服务端注册且未使用仅限PHP的自动注册区块时，您只需使用@wordpress/blocks包中的registerBlockType方法在JavaScript中注册客户端设置。只需确保使用与区块block.json文件中定义的相同区块名称。以下是一个示例：
import { registerBlockType } from '@wordpress/blocks';
registerBlockType( 'my-plugin/notice', {
edit: Edit,
// ...其他客户端设置
} );
虽然通常建议使用PHP在服务端注册区块，以获得"使用元数据文件的好处"部分所述的优势，但您也可以选择仅在客户端注册区块。registerBlockType方法允许您使用元数据注册区块类型。
该函数接受两个参数：
blockNameOrMetadata（字符串|对象）： 可以是区块类型的名称（字符串），也可以是包含区块元数据的对象（通常从block.json文件加载）。settings（对象）： 这是一个包含区块客户端设置的对象。
作为第二个参数传递的settings对象包含许多属性，但以下两个是最重要的：
edit： 在编辑器中用于我们区块的React组件。save： 返回保存到数据库的静态HTML标记的函数。
registerBlockType()函数在成功时返回注册的区块类型（WPBlock），失败时返回undefined。以下是一个示例：
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';
import metadata from './block.json';
const Edit = () => <p { ...useBlockProps() }>Hello World - 区块编辑器</p>;
const save = () => <p { ...useBlockProps.save() }>Hello World - 前端</p>;
registerBlockType( metadata.name, {
edit: Edit,
save,
} );