阐述 WordPress `register_block_type()` 函数源码：区块注册与 `block.json` 文件的关系。

嘿，各位代码界的探险家们，欢迎来到今天的 WordPress 区块魔法讲座！ 今天我们要深入挖掘 register_block_type() 这个神奇的函数，揭秘它与 block.json 文件的爱恨情仇，让大家彻底掌握区块注册的奥秘。

开场白：区块，WordPress 的新宠

想象一下，WordPress 就像一座乐高城堡，而区块就是那些色彩缤纷的积木。以前我们只能用主题和插件来搭建这座城堡，但现在有了区块，我们可以更自由、更灵活地创造各种独特的结构。而 register_block_type() 就是赋予这些积木“生命”的关键咒语。

register_block_type()：区块注册的魔杖

register_block_type() 函数是 WordPress 中注册区块的核心武器。它告诉 WordPress，“嘿，这里有一个新的区块，长这样，叫那个名字，你以后见到它就按我说的办！”。

让我们先看看它的基本用法：

<?php
/**
 * 注册自定义区块.
 */
function my_custom_block() {
    register_block_type( 'my-plugin/my-block', array(
        'attributes'      => array(
            'content' => array(
                'type' => 'string',
                'default' => 'Hello, Block!',
            ),
        ),
        'render_callback' => 'my_custom_block_render',
    ) );
}
add_action( 'init', 'my_custom_block' );

/**
 * 区块渲染回调函数.
 *
 * @param array $attributes 区块属性.
 * @return string 渲染后的 HTML.
 */
function my_custom_block_render( $attributes ) {
    $content = isset( $attributes['content'] ) ? $attributes['content'] : 'Hello, Block!';
    return '<p>' . esc_html( $content ) . '</p>';
}

这段代码做了什么？

1. register_block_type( 'my-plugin/my-block', array(...) ): 这是最关键的一步。

   • 'my-plugin/my-block'： 这是区块的 唯一 名称。 类似于你的乐高积木的型号，必须独一无二。 通常遵循 plugin-name/block-name 的格式，以避免命名冲突。
   • array(...)： 这是一个关联数组，包含了区块的各种属性和配置。

2. 'attributes' => array(...): 定义区块有哪些可配置的属性。

   • 'content' => array(...)： 定义了一个名为 content 的属性。
   • 'type' => 'string'： content 属性的类型是字符串。
   • 'default' => 'Hello, Block!'： content 属性的默认值是 "Hello, Block!"。

3. 'render_callback' => 'my_custom_block_render': 指定一个回调函数，负责将区块渲染成 HTML。 这个函数接收区块的属性作为参数。

4. add_action( 'init', 'my_custom_block' ): 将 my_custom_block 函数挂载到 init 钩子上，确保在 WordPress 初始化时注册区块。

简而言之，这段代码就像在告诉 WordPress：“嘿，我这里有个新的区块，它的名字是 my-plugin/my-block，它有一个可编辑的文本字段 content，当你遇到这个区块时，就用 my_custom_block_render 函数来渲染它。”

block.json：区块定义的标准化容器

虽然我们可以用 register_block_type() 函数的第二个参数来定义区块的所有属性，但更好的做法是将这些属性放在一个名为 block.json 的文件中。 为什么要这样做呢？

• 代码组织： 将区块的定义放在一个单独的文件中，可以使代码更清晰、更易于维护。
• 标准化： block.json 是一种标准化的格式，可以被 WordPress 和其他工具解析。
• 自动化： WordPress 可以自动读取 block.json 文件，并注册区块，无需显式调用 register_block_type() 函数。

block.json 的基本结构

一个典型的 block.json 文件可能看起来像这样：

{
    "name": "my-plugin/my-block",
    "title": "My Custom Block",
    "description": "A simple custom block.",
    "category": "common",
    "icon": "smiley",
    "keywords": [ "custom", "block" ],
    "attributes": {
        "content": {
            "type": "string",
            "default": "Hello, Block!"
        }
    },
    "supports": {
        "align": true
    },
    "textdomain": "my-plugin",
    "editorScript": "file:./index.js",
    "style": "file:./style.css"
}

让我们逐行解读一下：

• name: 区块的唯一名称，必须与 register_block_type() 函数中使用的名称一致。
• title: 区块在编辑器中显示的标题。
• description: 区块的描述，方便用户了解区块的功能。
• category: 区块所属的类别，例如 "common"、"formatting"、"layout" 等。
• icon: 区块在编辑器中显示的图标。 可以是 Dashicon 的名称，也可以是 SVG 代码。
• keywords: 用于搜索区块的关键词。
• attributes: 区块的属性定义，与 register_block_type() 函数中的 'attributes' 参数相同。
• supports: 区块支持的功能，例如对齐方式、颜色、字体大小等。
• textdomain: 区块的文本域，用于国际化。
• editorScript: 编辑器脚本的路径，用于添加编辑器的交互功能。
• style: 区块的样式表的路径，用于定义区块的样式。

register_block_type() 与 block.json 的协作

有了 block.json 文件，我们就可以简化 register_block_type() 函数的使用。 WordPress 会自动查找 block.json 文件，并根据其中的信息注册区块。

假设你的 block.json 文件位于 my-plugin/blocks/my-block/block.json，那么你可以这样注册区块：

<?php
/**
 * 注册自定义区块.
 */
function my_custom_block() {
    register_block_type( __DIR__ . '/blocks/my-block' );
}
add_action( 'init', 'my_custom_block' );

这里，我们只需要将 block.json 文件的目录传递给 register_block_type() 函数即可。 WordPress 会自动读取 block.json 文件，并注册区块。

register_block_type_from_metadata()：更简洁的选择

WordPress 提供了一个更简洁的函数 register_block_type_from_metadata()，专门用于从 block.json 文件注册区块。 它的用法与 register_block_type() 类似，但它会自动读取 block.json 文件，并根据其中的信息注册区块。

<?php
/**
 * 注册自定义区块.
 */
function my_custom_block() {
    register_block_type_from_metadata( __DIR__ . '/blocks/my-block' );
}
add_action( 'init', 'my_custom_block' );

使用 register_block_type_from_metadata() 函数，可以使代码更简洁、更易于阅读。

深度剖析：register_block_type() 源码

现在，让我们深入 register_block_type() 函数的源码，看看它到底做了些什么。

虽然直接公开 WordPress 核心源码有点复杂，但我们可以通过伪代码来模拟它的行为：

<?php

/**
 * 模拟 register_block_type() 函数.
 *
 * @param string $block_name 区块名称或 block.json 文件路径.
 * @param array|null $args 区块属性 (可选).
 */
function simulate_register_block_type( $block_name, $args = null ) {
    // 1. 确定区块名称和属性.
    if ( is_string( $block_name ) && file_exists( $block_name . '/block.json' ) ) {
        // 如果 $block_name 是一个目录，并且包含 block.json 文件，则尝试读取 block.json 文件。
        $block_json_path = $block_name . '/block.json';
        $block_json = file_get_contents( $block_json_path );

        if ( $block_json ) {
            $block_data = json_decode( $block_json, true );

            if ( ! isset( $block_data['name'] ) ) {
                error_log( '区块注册失败：block.json 文件缺少 "name" 属性。' );
                return;
            }

            $block_name = $block_data['name'];

            // 如果提供了 $args，则合并 block.json 中的属性和 $args。
            if ( is_array( $args ) ) {
                $block_data = array_merge( $block_data, $args );
            }

            $args = $block_data;

        } else {
            error_log( '区块注册失败：无法读取 block.json 文件。' );
            return;
        }
    } elseif ( is_string( $block_name ) && ! is_null( $args ) && is_array( $args ) ) {
        // 如果 $block_name 是一个字符串，并且提供了 $args 数组，则直接使用这些信息。
        // 确保区块名称存在。
        if ( empty( $block_name ) ) {
            error_log( '区块注册失败：区块名称不能为空。' );
            return;
        }

    } else {
        error_log( '区块注册失败：无效的参数。' );
        return;
    }

    // 2. 验证区块名称.
    if ( ! preg_match( '/^[a-z0-9-]+/[a-z0-9-]+$/', $block_name ) ) {
        error_log( '区块注册失败：无效的区块名称。区块名称必须包含斜杠，并且只能包含小写字母、数字和短横线。' );
        return;
    }

    // 3. 注册区块.
    global $wp_block_types;

    if ( isset( $wp_block_types[ $block_name ] ) ) {
        error_log( '区块注册失败：区块名称已存在。' );
        return;
    }

    $wp_block_types[ $block_name ] = (object) $args;

    // 4. 触发 action.
    do_action( 'register_block_type', $block_name, $args );

    echo "区块 {$block_name} 注册成功！<br>";
}

// 示例用法：
// 1. 从 block.json 文件注册区块.
// simulate_register_block_type( __DIR__ . '/my-block' );

// 2. 直接使用数组注册区块.
// simulate_register_block_type(
//     'my-plugin/another-block',
//     array(
//         'attributes' => array(
//             'content' => array(
//                 'type' => 'string',
//                 'default' => 'Another Block!',
//             ),
//         ),
//     )
// );
?>

这个伪代码展示了 register_block_type() 函数的一些核心逻辑：

1. 参数解析： 首先，它会检查传入的参数，判断是直接传入区块属性数组，还是传入 block.json 文件的路径。 如果传入的是 block.json 文件的路径，它会读取文件内容，并解析成数组。
2. 区块名称验证： 它会验证区块名称是否符合规范，确保名称包含斜杠，并且只包含小写字母、数字和短横线。
3. 区块注册： 它会将区块的属性存储到一个全局变量 $wp_block_types 中，以便 WordPress 能够识别和使用该区块。
4. 触发 Action： 它会触发一个 register_block_type action，允许其他插件或主题修改区块的属性。

block.json 文件的优先级

如果同时使用 block.json 文件和 register_block_type() 函数的第二个参数来定义区块的属性，那么哪个优先级更高呢？

答案是：register_block_type() 函数的第二个参数优先级更高。

这意味着，如果 block.json 文件中定义了一个属性，而在 register_block_type() 函数的第二个参数中也定义了相同的属性，那么 register_block_type() 函数的第二个参数中的值会覆盖 block.json 文件中的值。

实战演练：创建一个带样式的自定义区块

现在，让我们通过一个实战演练来巩固我们所学的知识。 我们将创建一个名为 my-plugin/styled-block 的自定义区块，它包含一个可编辑的文本字段，并且具有自定义样式。

1. 创建 block.json 文件：

   在 my-plugin/blocks/styled-block/block.json 文件中添加以下内容：

   {
       "name": "my-plugin/styled-block",
       "title": "Styled Block",
       "description": "A custom block with styles.",
       "category": "common",
       "icon": "star",
       "attributes": {
           "content": {
               "type": "string",
               "default": "Styled Block Content"
           }
       },
       "editorScript": "file:./index.js",
       "style": "file:./style.css"
   }

2. 创建 index.js 文件：

   在 my-plugin/blocks/styled-block/index.js 文件中添加以下内容：

   import { registerBlockType } from '@wordpress/blocks';
   import { useBlockProps, RichText } from '@wordpress/block-editor';
   
   registerBlockType( 'my-plugin/styled-block', {
       edit: ( props ) => {
           const { attributes, setAttributes } = props;
           const { content } = attributes;
   
           const onChangeContent = ( newContent ) => {
               setAttributes( { content: newContent } );
           };
   
           return (
               <div { ...useBlockProps() }>
                   <RichText
                       tagName="p"
                       className="my-styled-block-content"
                       value={ content }
                       onChange={ onChangeContent }
                       placeholder="Enter content here..."
                   />
               </div>
           );
       },
       save: ( props ) => {
           const { attributes } = props;
           const { content } = attributes;
   
           return (
               <div { ...useBlockProps.save() }>
                   <p className="my-styled-block-content">{ content }</p>
               </div>
           );
       },
   } );

3. 创建 style.css 文件：

   在 my-plugin/blocks/styled-block/style.css 文件中添加以下内容：

   .wp-block-my-plugin-styled-block .my-styled-block-content {
       font-size: 20px;
       color: blue;
       font-style: italic;
   }

4. 注册区块：

   在你的插件主文件中添加以下代码：

   <?php
   /**
    * 注册自定义区块.
    */
   function my_custom_block() {
       register_block_type_from_metadata( __DIR__ . '/blocks/styled-block' );
   }
   add_action( 'init', 'my_custom_block' );

5. 构建区块：

   在插件的根目录下运行 npm install 安装依赖，然后运行 npm run build 构建区块。

现在，你就可以在 WordPress 编辑器中使用 Styled Block 区块了。 它会显示一个可编辑的文本字段，并且具有蓝色的斜体样式。

总结：区块注册的艺术

今天我们深入探讨了 register_block_type() 函数及其与 block.json 文件的关系。 我们学习了如何使用 block.json 文件来定义区块的属性，以及如何使用 register_block_type() 或 register_block_type_from_metadata() 函数来注册区块。

记住，区块注册是 WordPress 区块开发的基础。 掌握了这些知识，你就可以创建各种各样的自定义区块，为 WordPress 网站添加无限的可能性。

课后作业：

1. 尝试创建一个包含多个属性的自定义区块，例如文本、颜色和图片。
2. 研究 WordPress 官方文档，了解更多关于 block.json 文件的属性和 register_block_type() 函数的用法。
3. 探索其他插件和主题的区块实现，学习他们的设计和代码风格。

祝大家在区块开发的道路上越走越远！ 下课！