剖析 WordPress block.json 文件在区块注册中的作用

WordPress 区块注册中的 block.json：核心作用与深度剖析

大家好！今天我们要深入探讨 WordPress 区块注册过程中的核心角色 —— block.json 文件。理解 block.json 的作用对于开发高质量、可维护的 WordPress 区块至关重要。我们会从基础概念出发，逐步剖析文件的结构、关键属性以及它在区块注册流程中的作用，并结合实际代码示例，帮助大家掌握这项关键技术。

1. 区块注册的必要性与传统方式的局限

在 WordPress Gutenberg 编辑器中，区块（Blocks）是构建内容的基本单元。每个区块都代表一种特定的内容类型，例如段落、标题、图像、视频等。为了让 WordPress 知道如何处理和渲染一个区块，我们需要将其注册到系统中。

在 block.json 出现之前，区块的注册通常通过 PHP 代码完成，特别是使用 register_block_type() 函数。这种方式虽然可行，但存在一些局限性：

• 代码分散: 区块的元数据（例如标题、描述、属性等）与区块的渲染逻辑代码混合在一起，增加了代码的复杂性。
• 维护困难: 修改区块的元数据需要修改 PHP 代码，这使得维护和更新变得困难。
• 可读性差: PHP 代码难以清晰地表达区块的结构和属性。
• 跨平台兼容性: 如果需要在不同的环境中（例如 Node.js）使用区块的元数据，就需要编写额外的代码来解析 PHP 代码。

2. block.json 文件的诞生：解决痛点

为了解决上述问题，WordPress 引入了 block.json 文件。它是一个 JSON 格式的文件，用于描述区块的元数据，包括标题、描述、属性、样式、脚本等。 block.json 文件的出现带来了以下优势：

• 结构化数据: 使用 JSON 格式存储区块元数据，使其结构清晰、易于阅读和解析。
• 代码解耦: 将区块元数据与 PHP 代码分离，提高了代码的可维护性和可重用性。
• 跨平台兼容性: JSON 格式可以被各种编程语言和平台轻松解析，方便区块元数据在不同环境中使用。
• 自动注册: WordPress 可以自动检测并注册 block.json 文件，简化了区块的注册流程。

3. block.json 文件结构详解

一个典型的 block.json 文件包含多个属性，用于描述区块的各个方面。下面我们将详细介绍一些常用的属性：

属性名	类型	描述	示例
name	string	区块的唯一名称，必须包含命名空间，例如 my-plugin/my-block。	"my-plugin/my-block"
title	string	区块的显示名称，用于在 Gutenberg 编辑器中显示。	"My Block"
description	string	区块的描述，用于在 Gutenberg 编辑器中显示。	"A simple block for displaying a message."
category	string	区块的类别，用于在 Gutenberg 编辑器中组织区块。常用的类别包括 common、formatting、layout、widgets 和 embed。	"common"
icon	string/object	区块的图标，用于在 Gutenberg 编辑器中显示。可以是 Dashicons 图标的名称，也可以是 SVG 代码或自定义组件。	"smiley" (Dashicon) { "src": "data:image/svg+xml;..." } (SVG) { "src": "block-icon" } (自定义组件)
keywords	array	区块的关键词，用于在 Gutenberg 编辑器中搜索区块。	["message", "simple"]
attributes	object	区块的属性，用于存储区块的数据。每个属性都有一个名称、类型和默认值。	json { "message": { "type": "string", "default": "Hello, world!" }, "alignment": { "type": "string", "default": "left" } }
supports	object	区块支持的功能，例如对齐方式、字体大小、背景颜色等。	json { "align": true, "html": false, "className": false }
example	object	区块的示例，用于在 Gutenberg 编辑器中预览区块。	json { "attributes": { "message": "This is an example message." } }
textdomain	string	区块的文本域，用于国际化。	"my-plugin"
editorScript	string	编辑器脚本的句柄，用于加载区块的 JavaScript 代码。	"my-plugin-my-block-editor-script"
editorStyle	string	编辑器样式的句柄，用于加载区块的 CSS 代码。	"my-plugin-my-block-editor-style"
style	string	前端样式的句柄，用于加载区块的 CSS 代码。	"my-plugin-my-block-style"
viewScript	string	前端 JavaScript 脚本的句柄，用于在前端执行额外的 JavaScript 代码。	"my-plugin-my-block-view-script"
render	string	指定渲染区块的 PHP 文件路径，从 WordPress 6.4 开始已经不推荐使用，推荐使用 render_callback 。	"./render.php"
render_callback	string	指定渲染区块的回调函数，用于动态渲染区块。如果设置了该属性，WordPress 将调用该函数来生成区块的 HTML 代码。	"my_plugin_my_block_render"
attributes.type	string	属性的类型，用于指定属性的数据类型。常用的类型包括 string、number、boolean、array 和 object。	"string"
attributes.default	any	属性的默认值，用于在区块初始化时设置属性的值。	"Hello, world!"

一个完整的 block.json 示例：

{
    "name": "my-plugin/my-block",
    "title": "My Block",
    "description": "A simple block for displaying a message.",
    "category": "common",
    "icon": "smiley",
    "keywords": [ "message", "simple" ],
    "attributes": {
        "message": {
            "type": "string",
            "default": "Hello, world!"
        },
        "alignment": {
            "type": "string",
            "default": "left"
        }
    },
    "supports": {
        "align": true,
        "html": false,
        "className": false
    },
    "example": {
        "attributes": {
            "message": "This is an example message."
        }
    },
    "textdomain": "my-plugin",
    "editorScript": "my-plugin-my-block-editor-script",
    "editorStyle": "my-plugin-my-block-editor-style",
    "style": "my-plugin-my-block-style",
    "render_callback": "my_plugin_my_block_render"
}

4. block.json 在区块注册流程中的作用

block.json 文件在区块注册流程中扮演着至关重要的角色。WordPress 会自动检测并解析 block.json 文件，然后根据文件中的元数据注册区块。

自动注册流程：

1. 文件位置: WordPress 会在主题或插件的 blocks 目录下查找 block.json 文件。也可以通过 register_block_type() 函数指定 block.json 文件的路径。
2. 文件解析: WordPress 使用 json_decode() 函数解析 block.json 文件，将 JSON 数据转换为 PHP 数组。
3. 数据验证: WordPress 会对 block.json 文件中的数据进行验证，确保数据的有效性。例如，会检查 name 属性是否符合命名规范，category 属性是否是有效的类别。
4. 区块注册: WordPress 使用 register_block_type() 函数注册区块，并将 block.json 文件中的元数据传递给该函数。

使用 PHP 代码注册区块（可选）：

虽然 WordPress 可以自动注册区块，但我们也可以使用 PHP 代码显式地注册区块。这在需要进行更高级的配置或自定义时非常有用。

<?php
/**
 * Registers the block using the metadata loaded from the `block.json` file.
 * Behind the scenes, it registers also all assets so they can be enqueued
 * through the block editor in the corresponding context.
 *
 * @see https://developer.wordpress.org/reference/functions/register_block_type/
 */
function create_block_my_block_block_init() {
    register_block_type( __DIR__ . '/build' ); //__DIR__ 指向当前文件所在的目录，'/build' 指向包含 block.json 文件的子目录
}
add_action( 'init', 'create_block_my_block_block_init' );

在这个例子中，register_block_type() 函数的参数是 block.json 文件所在的目录。WordPress 会自动查找该目录下的 block.json 文件，并从中读取元数据。

前端渲染：render_callback 的作用

render_callback 属性允许我们指定一个 PHP 函数，用于动态渲染区块的内容。这个函数会在前端生成区块的 HTML 代码。

<?php
/**
 * Render callback function.
 *
 * @param array    $attributes The block attributes.
 * @param string   $content    The block content.
 * @param WP_Block $block      The block object.
 *
 * @return string The rendered HTML.
 */
function my_plugin_my_block_render( $attributes, $content, $block ) {
    $message = isset( $attributes['message'] ) ? $attributes['message'] : 'Hello, world!';
    $alignment = isset( $attributes['alignment'] ) ? $attributes['alignment'] : 'left';

    $html = '<div style="text-align: ' . esc_attr( $alignment ) . ';">';
    $html .= '<p>' . esc_html( $message ) . '</p>';
    $html .= '</div>';

    return $html;
}

在这个例子中，my_plugin_my_block_render() 函数接收三个参数：

• $attributes: 区块的属性。
• $content: 区块的内容（通常为空）。
• $block: 区块对象。

该函数根据区块的属性生成 HTML 代码，并将其返回。

重要提示： 避免直接在 render_callback 中执行复杂的数据库查询或业务逻辑。 尽量保持渲染函数简洁高效，并将复杂逻辑放在其他地方处理。

5. attributes 属性的深度解析：数据管理的核心

attributes 属性是 block.json 文件中最关键的部分之一。它定义了区块的数据结构，允许我们存储和管理区块的数据。

属性类型：

attributes 属性中的每个属性都必须指定一个类型。常用的类型包括：

• string: 字符串
• number: 数字
• boolean: 布尔值
• array: 数组
• object: 对象

默认值：

每个属性都可以指定一个默认值。默认值会在区块初始化时设置属性的值。

属性示例：

{
    "attributes": {
        "message": {
            "type": "string",
            "default": "Hello, world!"
        },
        "fontSize": {
            "type": "number",
            "default": 16
        },
        "isBold": {
            "type": "boolean",
            "default": false
        },
        "items": {
            "type": "array",
            "default": []
        },
        "settings": {
            "type": "object",
            "default": {
                "color": "red",
                "background": "white"
            }
        }
    }
}

在 JavaScript 代码中使用属性：

在区块的 JavaScript 代码中，我们可以通过 useBlockProps hook 获取区块的属性。

import { useBlockProps } from '@wordpress/block-editor';

function MyBlockEdit( { attributes, setAttributes } ) {
    const { message, fontSize, isBold } = attributes;

    return (
        <div { ...useBlockProps() }>
            <p style={ { fontSize: fontSize + 'px', fontWeight: isBold ? 'bold' : 'normal' } }>
                { message }
            </p>
            <input
                type="text"
                value={ message }
                onChange={ ( event ) => setAttributes( { message: event.target.value } ) }
            />
        </div>
    );
}

export default MyBlockEdit;

在这个例子中，我们使用 useBlockProps() hook 获取区块的属性，并将 message、fontSize 和 isBold 属性用于渲染区块的内容。我们还使用 setAttributes() 函数更新 message 属性的值。

6. supports 属性详解：控制区块行为

supports 属性允许我们控制区块的行为，例如是否支持对齐方式、字体大小、背景颜色等。

常用的 supports 属性：

• align: 是否支持对齐方式。可以设置为 true、false 或一个包含对齐方式的数组，例如 [ 'left', 'center', 'right', 'wide', 'full' ]。
• anchor: 是否支持锚点。
• className: 是否允许用户添加自定义 CSS 类名。
• color: 是否支持颜色设置。
• spacing: 是否支持间距设置（例如 padding 和 margin）。
• typography: 是否支持排版设置（例如字体大小和字体系列）。
• html: 是否允许用户编辑区块的 HTML 代码（不推荐）。
• inserter: 控制区块是否出现在区块插入器中（默认为 true）。
• multiple: 控制是否允许在同一页面中多次插入同一个区块（默认为 true）。

示例：

{
    "supports": {
        "align": [ "left", "center", "right" ],
        "anchor": true,
        "className": false,
        "color": {
            "background": true,
            "text": true
        },
        "spacing": {
            "padding": true
        },
        "typography": {
            "fontSize": true,
            "lineHeight": true
        }
    }
}

在这个例子中，我们启用了对齐方式（仅允许左对齐、居中和右对齐）、锚点、背景颜色、文本颜色、padding、字体大小和行高。我们禁用了自定义 CSS 类名。

7. editorScript、editorStyle 和 style：加载资源

editorScript、editorStyle 和 style 属性用于指定区块的 JavaScript 和 CSS 文件。

• editorScript: 指定编辑器脚本的句柄。该脚本会在 Gutenberg 编辑器中加载。
• editorStyle: 指定编辑器样式的句柄。该样式会在 Gutenberg 编辑器中加载。
• style: 指定前端样式的句柄。该样式会在前端加载。

注册资源：

在 PHP 代码中，我们需要使用 wp_register_script() 和 wp_register_style() 函数注册这些资源。

<?php
function my_plugin_register_block() {

    wp_register_script(
        'my-plugin-my-block-editor-script',
        plugins_url( 'build/index.js', __FILE__ ), //修改为你的js文件路径
        array( 'wp-blocks', 'wp-element', 'wp-editor' ),
        filemtime( plugin_dir_path( __FILE__ ) . 'build/index.js' ) //修改为你的js文件路径
    );

    wp_register_style(
        'my-plugin-my-block-editor-style',
        plugins_url( 'build/index.css', __FILE__ ), //修改为你的css文件路径
        array( 'wp-edit-blocks' ),
        filemtime( plugin_dir_path( __FILE__ ) . 'build/index.css' ) //修改为你的css文件路径
    );

    wp_register_style(
        'my-plugin-my-block-style',
        plugins_url( 'build/style-index.css', __FILE__ ), //修改为你的css文件路径
        array( 'wp-style' ),
        filemtime( plugin_dir_path( __FILE__ ) . 'build/style-index.css' ) //修改为你的css文件路径
    );

    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'my_plugin_register_block' );

重要提示：

• 确保资源的句柄与 block.json 文件中指定的句柄一致。
• 使用 filemtime() 函数可以确保在文件更新时，浏览器会加载最新的资源版本。
• 合理地组织 JavaScript 和 CSS 代码，避免代码冗余。

8. viewScript 属性：添加前端交互

viewScript 属性允许我们指定一个前端 JavaScript 脚本，用于在前端执行额外的 JavaScript 代码。这对于添加复杂的交互或动画效果非常有用。

示例：

{
    "viewScript": "my-plugin-my-block-view-script"
}

注册 viewScript：

<?php
function my_plugin_register_block() {

    wp_register_script(
        'my-plugin-my-block-view-script',
        plugins_url( 'view.js', __FILE__ ), //修改为你的js文件路径
        array(),
        filemtime( plugin_dir_path( __FILE__ ) . 'view.js' ), //修改为你的js文件路径
        true // 将脚本加载到页面底部
    );

    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'my_plugin_register_block' );

view.js 代码示例：

document.addEventListener( 'DOMContentLoaded', function() {
    const blocks = document.querySelectorAll( '.wp-block-my-plugin-my-block' ); // 修改为你的区块类名

    blocks.forEach( ( block ) => {
        block.addEventListener( 'click', function() {
            alert( 'Block clicked!' );
        } );
    } );
} );

在这个例子中，我们在 view.js 文件中添加了一个点击事件监听器，当用户点击区块时，会弹出一个警告框。

9. 最佳实践与常见问题

• 规范的命名： 使用规范的命名空间，避免与其他插件或主题冲突。例如，使用 my-plugin/my-block 作为区块的名称。
• 清晰的描述： 提供清晰的区块描述，帮助用户理解区块的功能。
• 合理的属性： 定义合理的属性，以便存储和管理区块的数据。
• 有效的验证： 对用户输入的数据进行验证，确保数据的有效性。
• 性能优化： 优化 JavaScript 和 CSS 代码，提高页面加载速度。
• 国际化： 使用文本域进行国际化，使区块可以支持多种语言。
• 版本控制： 使用版本控制系统（例如 Git）管理 block.json 文件，以便跟踪更改和回滚版本。

常见问题：

• block.json 文件未被加载： 检查文件路径是否正确，确保文件位于主题或插件的 blocks 目录下。
• 区块无法正常显示： 检查 block.json 文件中的元数据是否正确，特别是 name、title、category 和 attributes 属性。
• JavaScript 或 CSS 文件未被加载： 检查资源的句柄是否与 block.json 文件中指定的句柄一致，确保资源已正确注册。
• render_callback 函数未被调用： 检查 render_callback 属性是否正确设置，确保函数已正确定义。

10. 结语：block.json 是区块开发的关键

block.json 文件是 WordPress 区块开发的核心。它提供了一种结构化的方式来描述区块的元数据，简化了区块的注册流程，提高了代码的可维护性和可重用性。 掌握 block.json 的使用方法，是成为一名优秀的 WordPress 区块开发者的必备技能。

这次讲座，我详细的描述了block.json文件在WordPress区块注册中的作用，希望对大家有所帮助，感谢大家！