block.json 中的元数据

从 WordPress 5.8 版本开始，我们建议使用 block.json 元数据文件作为在 PHP（服务端）和 JavaScript（客户端）中注册块类型的标准方式。以下是一个定义创建通知块的插件的元数据的示例 block.json 文件。

示例：

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "my-plugin/notice",
    "title": "Notice",
    "category": "text",
    "parent": [ "core/group" ],
    "icon": "star",
    "description": "Shows warning, error or success notices...",
    "keywords": [ "alert", "message" ],
    "version": "1.0.3",
    "textdomain": "my-plugin",
    "attributes": {
        "message": {
            "type": "string",
            "source": "html",
            "selector": ".message"
        }
    },
    "providesContext": {
        "my-plugin/message": "message"
    },
    "usesContext": [ "groupId" ],
    "selectors": {
        "root": ".wp-block-my-plugin-notice"
    },
    "supports": {
        "align": true
    },
    "styles": [
        { "name": "default", "label": "Default", "isDefault": true },
        { "name": "other", "label": "Other" }
    ],
    "example": {
        "attributes": {
            "message": "This is a notice!"
        }
    },
    "variations": [
        {
            "name": "example",
            "title": "Example",
            "attributes": {
                "message": "This is an example!"
            }
        }
    ],
    "editorScript": "file:./index.js",
    "script": "file:./script.js",
    "viewScript": [ "file:./view.js", "example-shared-view-script" ],
    "editorStyle": "file:./index.css",
    "style": [ "file:./style.css", "example-shared-style" ],
    "viewStyle": [ "file:./view.css", "example-view-style" ],
    "render": "file:./render.php"
}

使用元数据文件的优点

块定义允许在 JavaScript、PHP 和其他语言之间共享代码，用于处理存储为 JSON 的块类型。使用 block.json 元数据文件注册块除了上述功能外还提供多种好处。

从性能角度来看，当主题支持懒加载资源时，使用 block.json 注册的块将自动优化其资源队列。在 style 或 script 属性中列出的前端 CSS 和 JavaScript 资源仅在页面中存在该块时才会被队列化，从而减少页面大小。

此外，由于 块类型 REST API 端点 只能列出在服务端注册的块，因此建议在服务端注册块；使用 block.json 文件可以简化此注册过程。

WordPress 插件目录 可以检测 block.json 文件，突出显示插件中包含的块，并提取其元数据。如果您希望将您的块提交到块目录，则您插件中的所有块都必须具有 block.json 文件，以便块目录能够识别它们。

通过使用定义的架构定义文件可以改进开发工作。支持的编辑器可以提供帮助，例如工具提示、自动完成和架构验证。要使用架构，请将以下内容添加到 block.json 的顶部。

"$schema": "https://schemas.wp.org/trunk/block.json"

块 API

本节描述了可以添加到 block.json 文件的所有属性，用于定义块类型的行为和元数据。

API 版本

• 类型：number
• 可选
• 本地化：否
• 属性：apiVersion
• 默认值：1

{ "apiVersion": 3 }

块使用的块 API 版本。最新版本是 3，它是在 WordPress 6.3 中引入的。

查看 API 版本文档 以获取更多信息。

名称

• 类型：string
• 必需
• 本地化：否
• 属性：name

{ "name": "core/heading" }

块的名称是一个唯一字符串，用于标识块。名称必须结构化为 namespace/block-name，其中 namespace 是您的插件或主题的名称。

注意：块名称只能包含小写字母数字字符、破折号，以及最多一个正斜杠来指定插件唯一的命名空间前缀。它必须以字母开头。

注意：此名称在注释分隔符中用作 <!-- wp:my-plugin/book -->。core 命名空间中的块类型在序列化时不包括命名空间。

标题

• 类型：string
• 必需
• 本地化：是
• 属性：title

{ "title": "Heading" }

这是您块的显示标题，可以使用我们的翻译函数进行翻译。标题将显示在插入器和其他编辑器区域中。

注意：为了保持您的块标题在 UI 中可读和可访问，请避免使用非常长的标题。

类别

• 类型：string
• 可选
• 本地化：否
• 属性：category

{ "category": "text" }

块被分组到类别中，以帮助用户浏览和发现它们。

核心提供的类别有：

• text
• media
• design
• widgets
• theme
• embed

插件和主题还可以注册 自定义块类别。

实现应预期并容忍未知类别，并提供一些合理的回退行为（例如“text”类别）。

父级

• 类型：string[]
• 可选
• 本地化：否
• 属性：parent

{ "parent": [ "my-block/product" ] }

设置 parent 可以让块要求它仅在嵌套在指定的块内时可用。例如，您可能希望允许“添加到购物车”块仅在“产品”块内可用。

祖先

• 类型：string[]
• 可选
• 本地化：否
• 属性：ancestor
• 自：WordPress 6.0.0

{ "ancestor": [ "my-block/product" ] }

ancestor 属性使块在祖先块子树的任何位置内指定的块类型中可用。这允许例如将“评论内容”块放置在“列”块内，只要“列”位于“评论模板”块的某个位置内。与 parent 属性相比，指定其 ancestor 的块可以放置在子树中的任何位置，而具有指定 parent 的块必须是直接子项。

允许块

• 类型：string[]
• 可选
• 本地化：否
• 属性：allowedBlocks
• 自：WordPress 6.5.0

{ "allowedBlocks": [ "my-block/product" ] }

allowedBlocks 指定哪些块类型可以是块的直接子项。例如，“列表”块可以只允许“列表项”块作为子项。

图标

• 类型：string
• 可选
• 本地化：否
• 属性：icon

{ "icon": "smile" }

应指定图标属性以便于识别块。这些可以是 WordPress 的 Dashicons 中的任何一个（slug 在非 JS 上下文中也作为回退使用）。

注意：也可以在客户端使用 SVG 元素的源覆盖此属性。此外，此属性可以用 JavaScript 定义为包含背景和前景颜色的对象。当适用时（例如在插入器中），这些颜色将出现在图标旁边。自定义 SVG 图标会自动包装在 wp.primitives.SVG 组件中以添加可访问性属性（aria-hidden、role 和 focusable）。

描述

• 类型：string
• 可选
• 本地化：是
• 属性：description

{
    "description": "Introduce new sections and organize content to help visitors"
}

这是您块的简短描述，可以使用我们的翻译函数进行翻译。这将在块检查器中显示。

关键词

• 类型：string[]
• 可选
• 本地化：是
• 属性：keywords
• 默认值：[]

{ "keywords": [ "keyword1", "keyword2" ] }

有时块可以拥有别名，以便用户在搜索时发现它。例如，图像块也希望被“photo”发现。您可以通过提供无限数量的术语（这些术语会被翻译）来实现。

版本

• 类型：string
• 可选
• 本地化：否
• 属性：version
• 自：WordPress 5.8.0

{ "version": "1.0.3" }

块的当前版本号，例如 1.0 或 1.0.3。它与插件的版本管理类似。此字段可与块资源一起使用以控制缓存无效化，当块作者省略该字段时，则使用已安装的 WordPress 版本。

文本域

• 类型：string
• 可选
• 本地化：否
• 属性：textdomain
• 自：WordPress 5.7.0

{ "textdomain": "my-plugin" }

插件/块的 gettext 文本域。更多信息可在 文本域 部分找到，位于 如何国际化您的插件 页面。

属性

• 类型：object
• 可选
• 本地化：否
• 属性：attributes
• 默认值：{}

{
    "attributes": {
        "cover": {
            "type": "string",
            "source": "attribute",
            "selector": "img",
            "attribute": "src"
        },
        "author": {
            "type": "string",
            "source": "html",
            "selector": ".book-author"
        }
    }
}

属性提供块的结构化数据需求。当它们被序列化时，它们可以以不同的形式存在，但它们在一个公共接口下共同声明。

有关更多详细信息，请参见 属性文档。

提供上下文

• 类型：object
• 可选
• 本地化：否
• 属性：providesContext
• 默认值：{}

为当前类型的块的子代提供可访问的上下文，形式为一个对象，将上下文名称映射到块自身的属性之一。

有关更多详细信息，请参见 块上下文文档。

{
    "providesContext": {
        "my-plugin/recordId": "recordId"
    }
}

上下文

• 类型：string[]
• 可选
• 本地化：否
• 属性：usesContext
• 默认值：[]

从祖先提供者继承的上下文值名称数组。

有关更多详细信息，请参见 块上下文文档。

{
    "usesContext": [ "message" ]
}

选择器

• 类型：object
• 可选
• 本地化：否
• 属性：selectors
• 默认值：{}
• 自：WordPress 6.3.0

任何自定义 CSS 选择器，以 root、feature 或 sub-feature 为键，用于生成 theme.json（全局样式）样式表中的块样式。
提供自定义选择器允许更精细地控制哪些样式适用于哪些块元素，例如仅将排版样式应用于内部标题，而颜色仍然应用于外部块包装器等。

有关更多详细信息，请参见 选择器文档。

{
    "selectors": {
        "root": ".my-custom-block-selector",
        "color": {
            "text": ".my-custom-block-selector p"
        },
        "typography": {
            "root": ".my-custom-block-selector > h2",
            "text-decoration": ".my-custom-block-selector > h2 span"
        }
    }
}

支持

• 类型：object
• 可选
• 本地化：否
• 属性：supports
• 默认值：{}

它包含一组选项，用于控制编辑器中使用的功能。有关更多详细信息，请参见 支持文档。

块样式

• 类型：array
• 可选
• 本地化：是（仅 label）
• 属性：styles
• 默认值：[]

{
    "styles": [
        { "name": "default", "label": "Default", "isDefault": true },
        { "name": "other", "label": "Other" }
    ]
}

块样式可用于为块提供替代样式。它的工作原理是为块的包装器添加类名。使用 CSS，主题开发人员可以针对所选的块样式类名。

插件和主题还可以为现有块注册 自定义块样式。

示例

• 类型：object
• 可选
• 本地化：否
• 属性：example

{
    "example": {
        "attributes": {
            "message": "This is a notice!"
        }
    }
}

它为块提供结构化示例数据。此数据用于构建块的预览，以便在用户将鼠标悬停在块上时显示在 Inspector 帮助面板中。

有关更多详细信息，请参见 示例文档。

变体

• 类型：object[]|WPDefinedPath（了解更多）
• 可选
• 本地化：是（仅每个变体的 title、description 和 keywords）
• 属性：variations
• 自：WordPress 5.9.0

{
    "variations": [
        {
            "name": "example",
            "title": "Example",
            "attributes": {
                "level": 2,
                "message": "This is an example!"
            },
            "scope": [ "block" ],
            "isActive": [ "level" ]
        }
    ]
}

块变体是允许块拥有相似版本但共享某些共同功能的 API。每个块变体通过设置一些初始属性或内部块与其他变体区分开来。然后在插入块时应用这些属性和/或内部块。

注意：在 JavaScript 中，您可以为 isActive 属性提供函数，并为 icon 提供 React 元素。在 block.json 文件中两者仅支持字符串

从版本 6.7 开始，可以在 block.json 中指定一个 PHP 文件，在服务器端生成块变体列表：

{ "variations": "file:./variations.php" }

该 PHP 文件预期要 return 包含块变体的数组。从 PHP 文件返回的变体中找到的字符串不会自动本地化；相反，像往常一样使用 __() 函数。

例如：

<?php
// Generate variations for a Social Icon kind of block.

return array(
    array(
        'isDefault'  => true,
        'name'       => 'wordpress',
        'title'      => 'WordPress',
        'icon'       => 'wordpress',
        'attributes' => array(
            'service' => 'wordpress',
        ),
        'isActive'   => array( 'service' )
    ),
    array(
        'name'       => 'mail',
        'title'      => __( 'Mail' ),
        'keywords'   => array(
            __( 'email' ),
            __( 'e-mail' )
        ),
        'icon'       => 'mail',
        'attributes' => array(
            'service' => 'mail',
        ),
        'isActive'   => array( 'mail' )
    ),
);

有关更多详细信息，请参见 变体文档。

块钩子

• 类型：object
• 可选
• 属性：blockHooks
• 自：WordPress 6.4.0

{
    "blockHooks": {
        "my-plugin/banner": "after"
    }
}

Block Hooks 是一个 API，允许一个块自动插入到给定块类型的所有实例旁边，其相对位置也由“挂钩”的块指定。也就是说，一个块可以选择在给定块类型之前或之后插入，或者作为其第一个或最后一个子块（即分别追加或附加到其子块列表）。挂钩的块将同时出现在前端和编辑器中（以便用户进行自定义）。

键是挂钩到的块的名称 (string)，值是挂钩到的位置 (string)。有关可用配置的更多信息，请查看 Block Hooks 文档。

编辑器脚本

• 类型：WPDefinedAsset|WPDefinedAsset[] (了解更多)
• 可选
• 本地化：否
• 属性：editorScript

{ "editorScript": "file:./index.js" }

块类型编辑器脚本定义。它们仅在编辑器的上下文中加载。

可以传递使用 wp_register_script 函数注册的脚本句柄、相对于 block.json 文件的 JavaScript 文件路径，或两者的混合列表 (了解更多)。

注意：自 WordPress 6.1.0 起，存在传递编辑器脚本数组的选项。

脚本

• 类型：WPDefinedAsset|WPDefinedAsset[] (了解更多)
• 可选
• 本地化：否
• 属性：script

{ "script": "file:./script.js" }

块类型前端和编辑器脚本定义。它们将在编辑器和查看站点内容时同时加载。

可以传递使用 wp_register_script 函数注册的脚本句柄、相对于 block.json 文件的 JavaScript 文件路径，或两者的混合列表 (了解更多)。

注意：自 WordPress 6.1.0 起，存在传递脚本数组的选项。

查看脚本

• 类型：WPDefinedAsset|WPDefinedAsset[] (了解更多)
• 可选
• 本地化：否
• 属性：viewScript
• 版本：WordPress 5.9.0

{ "viewScript": [ "file:./view.js", "example-shared-view-script" ] }

块类型前端脚本定义。它们仅在查看站点内容时加载。

可以传递使用 wp_register_script 函数注册的脚本句柄、相对于 block.json 文件的 JavaScript 文件路径，或两者的混合列表 (了解更多)。

注意：自 WordPress 6.1.0 起，存在传递查看脚本数组的选项。

查看脚本模块

• 类型：WPDefinedAsset|WPDefinedAsset[] (了解更多)
• 可选
• 本地化：否
• 属性：viewScriptModule
• 版本：WordPress 6.5.0

{ "viewScriptModule": [ "file:./view.js", "example-shared-script-module-id" ] }

块类型前端脚本模块定义。它们仅在查看站点内容时加载。

可以传递使用 wp_register_script_module 函数注册的脚本模块 ID、相对于 block.json 文件的 JavaScript 模块路径，或两者的混合列表 (了解更多)。

WordPress 脚本和 WordPress 脚本模块目前不兼容。如果前端查看资源依赖于 WordPress 脚本，应使用 viewScript。如果它们依赖于 WordPress 脚本模块（即当前的交互性 API），则应使用 viewScriptModule。更多功能将逐步为脚本模块提供。

注意：自 WordPress 6.5.0 起可用。

编辑器样式

• 类型：WPDefinedAsset|WPDefinedAsset[] (了解更多)
• 可选
• 本地化：否
• 属性：editorStyle

{ "editorStyle": "file:./index.css" }

块类型编辑器样式定义。它们仅在编辑器的上下文中加载。

可以传递使用 wp_register_style 函数注册的样式句柄、相对于 block.json 文件的 CSS 文件路径，或两者的混合列表 (了解更多)。

注意：自 WordPress 5.9.0 起，存在传递编辑器样式数组的选项。

样式

• 类型：WPDefinedAsset|WPDefinedAsset[] (了解更多)
• 可选
• 本地化：否
• 属性：style

{ "style": [ "file:./style.css", "example-shared-style" ] }

块类型前端和编辑器样式定义。它们将在编辑器和查看站点内容时同时加载。

可以传递使用 wp_register_style 函数注册的样式句柄、相对于 block.json 文件的 CSS 文件路径，或两者的混合列表 (了解更多)。

注意：自 WordPress 5.9.0 起，存在传递样式数组的选项。

查看样式

• 类型：WPDefinedAsset|WPDefinedAsset[] (了解更多)
• 可选
• 本地化：否
• 属性：viewStyle
• 版本：WordPress 6.5.0

{ "viewStyle": [ "file:./view.css", "example-view-style" ] }

块类型前端样式定义。它们仅在查看站点内容时加载。

可以传递使用 wp_register_style 函数注册的样式句柄、相对于 block.json 文件的 CSS 文件路径，或两者的混合列表 (了解更多)。

仅前端样式对于交互式块特别有用，用于样式化仅在用户执行某些操作后才可见的部分，并且这些样式在编辑器中永远不需要。您可以从使用 style 属性将所有通用样式放在一个样式表中开始。只有当您需要特定于编辑器的样式或特定于前端的样式时，您才可以扩展到 editorStyle 和 viewStyle，但仍将您的样式的通用部分保留在主样式表中。

渲染

• 类型：WPDefinedPath (了解更多)
• 可选
• 本地化：否
• 属性：render
• 版本：WordPress 6.1.0

{ "render": "file:./render.php" }

在服务器上渲染块类型以显示在前端时使用的 PHP 文件。以下变量暴露给该文件：

• $attributes (array)：块的属性。
• $content (string)：块的默认内容。
• $block (WP_Block)：块实例。

使用 render 定义的 render.php 文件的一个示例实现可能如下所示：

<div <?php echo get_block_wrapper_attributes(); ?>>
    <?php echo esc_html( $attributes['label'] ); ?>
</div>

注意：此文件在服务器渲染页面 HTML 时，对于块类型的每个实例都会加载。在文件中声明函数或类时必须考虑到这一点。避免错误风险的最简单方法是从另一个文件消费该共享逻辑。

资源

WPDefinedPath

WPDefinedPath 类型是字符串的子类型，其值表示相对于 block.json 文件所在位置的路径到 JavaScript、CSS 或 PHP 文件。提供的路径必须以 file: 前缀开头。这种方法基于 npm 如何处理包的 本地路径。

示例：

在 block.json 中：

{
    "render": "file:./render.php"
}

WPDefinedAsset

它扩展了 WPDefinedPath 以支持 JavaScript 和 CSS 文件。另一种替代文件路径的方法是引用已注册的资产（使用 WordPress 辅助工具）的脚本句柄、脚本模块 ID 或样式句柄。

示例：

在 block.json 中：

{
    "editorScript": "file:./index.js",
    "script": "file:./script.js",
    "viewScriptModule": [
        "file:./view.js",
        "example-registered-script-module-id"
    ],
    "editorStyle": "file:./index.css",
    "style": [ "file:./style.css", "example-shared-style" ],
    "viewStyle": [ "file:./view.css", "example-view-style" ]
}

在 WordPress 的上下文中，当使用 PHP 注册块时，它会自动注册 block.json 文件中发现的所有脚本、脚本模块和样式，并使用文件路径而不是资产句柄。

这就是为什么 WPDefinedAsset 类型必须提供一种方法来镜像使用 wp_register_script、wp_register_script_module 和 wp_register_style 注册脚本、脚本模块和样式所需的参数，然后将这些参数分配为与块关联的句柄或脚本模块 ID。

可以提供具有以下形状的对象：

• handle (string) – 脚本的名称。如果省略，将自动生成。
• dependencies (string[]|{ id: string, import?: 'dynamic'|'static' }[]) – 此脚本依赖的已注册脚本句柄数组。脚本模块可以使用简单字符串表示静态依赖项，或使用对象形式表示动态依赖项。动态依赖项是可能在运行时使用也可能不使用的依赖项，通常与动态 import('module-id') 语法一起使用。默认值：[]。
• version (string|false|null) – 指定脚本版本号（如果有的话）的字符串，该版本号作为查询字符串添加到 URL 中以进行缓存清除。如果版本设置为 false，则会自动添加等于当前安装的 WordPress 版本的版本号。如果设置为 null，则不添加版本号。默认值：false。

定义存储在一个以 .asset.php 结尾的单独的 PHP 文件中，该文件位于 block.json 中列出的 JS/CSS 文件旁边。WordPress 将通过模式匹配自动检测此文件。此选项是首选的，因为预计它将使用 @wordpress/scripts 包自动生成这些资产文件的选项。

示例：

build/
├─ block.json
├─ index.js
└─ index.asset.php

在 block.json 中：

{ "editorScript": "file:./index.js" }

在 build/index.asset.php 中：

<?php
return array(
    'dependencies' => array(
        'react',
        'wp-blocks',
        'wp-i18n',
    ),
    'version'      => '3be55b05081a63d8f9d0ecb466c42cfd',
);

前端加载队列

从 WordPress 5.8 版本开始，可以指示 WordPress 仅在块类型在前端渲染时为其加载脚本和样式。这适用于 block.json 文件中的以下资产字段：

• script
• viewScript
• style
• viewStyle（在 WordPress 6.5.0 中添加）

国际化

WordPress 字符串发现系统可以自动翻译此文档中标记为可翻译的字段。首先，您需要在提供块元数据的 block.json 文件中设置 textdomain 属性。

示例：

{
    "title": "My block",
    "description": "My block is fantastic",
    "keywords": [ "fantastic" ],
    "textdomain": "my-plugin"
}

PHP

在 PHP 中，当执行 register_block_type 时，本地化属性将在 WordPress 后端自动包装在 _x 函数调用中。这些翻译作为内联脚本添加到插件的脚本句柄或 WordPress 核心的 wp-block-library 脚本句柄中。

register_block_type 处理可翻译值的方式大致等同于以下代码片段：

<?php
$metadata = array(
    'title'       => _x( 'My block', 'block title', 'my-plugin' ),
    'description' => _x( 'My block is fantastic!', 'block description', 'my-plugin' ),
    'keywords'    => array( _x( 'fantastic', 'block keyword', 'my-plugin' ) ),
);

实现遵循现有的 get_plugin_data 函数，该函数解析插件内容以检索插件的元数据，并动态应用翻译。

JavaScript

在 JavaScript 中，您可以使用 @wordpress/blocks 包中的 registerBlockType 方法，并将从 block.json 加载的元数据对象作为第一个参数传递。所有本地化属性都会自动包装在 _x（来自 @wordpress/i18n 包）函数调用中，工作方式类似于 PHP。

示例：

import { registerBlockType } from '@wordpress/blocks';
import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata, {
    edit: Edit,
    // ...other client-side settings
} );

向后兼容性

现有的注册机制（服务器端和前端）将继续工作，它将作为基于 block.json 的注册的底层实现细节。

一旦所有细节准备就绪，核心块将逐步迁移，第三方块将在控制台看到警告，以鼓励它们重构使用的块注册 API。

出于向后兼容性的原因，以下属性仅在客户端支持。其中一些可能在将来被替代 API 替换：

• edit – 有关更多详细信息，请参阅 编辑和保存 文档。
• save – 有关更多详细信息，请参阅 编辑和保存 文档。
• transforms – 有关更多详细信息，请参阅 转换 文档。
• deprecated – 有关更多详细信息，请参阅 已弃用的块 文档。
• merge – 目前未记录。其作用是处理将多个块合并为一个。
• getEditWrapperProps – 同样未记录。其作用是将额外的属性注入到块的编辑组件包装器中。

示例：

import { registerBlockType } from '@wordpress/blocks';

registerBlockType( 'my-plugin/block-name', {
    edit: function () {
        // Edit definition goes here.
    },
    save: function () {
        // Save definition goes here.
    },
    getEditWrapperProps: function () {
        // Implementation goes here.
    },
} );

对于 WordPress 支持的 动态块，仍然应该可以使用服务器上的 register_block_type 函数注册 render_callback 属性。