2551654928/gutenbergdocs

Fork 0

unknown 28ad1b3935 docs

2025-10-22 01:40:18 +08:00

11 KiB

Raw Permalink Blame History

补充资源

block.json

block.json 文件通过使用相同的 JSON 格式区块定义，在服务端和客户端（区块编辑器）上注册区块，从而简化了定义和注册区块的过程。

下图详细说明了 block.json 文件的基本结构。

要查看完整的区块示例及其相关的 block.json 文件，请访问区块开发示例 GitHub 仓库。

除了简化区块注册外，使用 block.json 还有诸多优势，包括性能提升。

block.json 中的元数据文档提供了关于可在区块的 block.json 文件中使用的所有属性的完整指南。本文将介绍最常用的选项，这些选项允许你指定：

区块的基本元数据
控制区块功能、外观和输出的文件
数据在区块内的存储方式
用户界面中区块的设置面板

区块的基本元数据

使用 block.json 属性，你可以定义区块的唯一标识方式以及在区块编辑器中显示的信息。这些属性包括：

apiVersion： 指定区块使用的 API 版本。除非有特定要求，否则请使用最新版本。
name： 区块的唯一名称，包括命名空间（例如 my-plugin/my-custom-block）。
title： 区块的显示标题，在插入器中显示。
category： 区块在插入器中出现的分类。常见分类包括 text、media、design、widgets 和 theme。
icon： 在插入器中代表区块的图标。可以是 Dashicon 标识或自定义 SVG 图标。
description： 区块的简短描述，提供比标题更多的上下文信息。
keywords： 关键词数组，帮助用户在搜索时找到区块。
textdomain： 区块的文本域，用于国际化。

控制区块行为、输出或样式的文件

block.json 文件还允许你指定区块功能所需的关键文件：

editorScript： 仅用于区块编辑器的 JavaScript 文件。
editorStyle： 用于区块编辑器内样式设置的 CSS 文件。
script： 在区块编辑器和前端均可加载的 JavaScript 文件。
style： 在区块编辑器和前端均可应用的 CSS 文件。
viewScript： 仅用于前端的 JavaScript 文件。

对于所有这些属性，你可以提供文件路径（以 file: 开头）、使用 wp_register_script 或 wp_register_style 注册的句柄，或结合这两种选项的数组。

此外，render 属性（在 WordPress 6.1 中引入）指定了一个 PHP 模板文件的路径，该文件负责生成动态渲染区块的前端标记。如果未向 register_block_type() 函数提供 $render_callback 函数，则使用此方法。

使用区块 `attributes` 存储数据

区块属性是分配给区块的设置或数据。它们可以决定区块的各个方面，例如其内容、布局、样式以及需要随区块结构存储的任何其他特定信息。如果用户更改了区块（例如修改字体大小），您需要一种方法来保留这些更改。属性正是解决方案。

在注册新的区块类型时，block.json 的 attributes 属性描述了区块所需的自定义数据以及这些数据在数据库中的存储方式。这使得区块编辑器能够正确解析这些值，并将 attributes 传递给区块的 Edit 组件和 save 函数。

以下是在 block.json 中定义的三个属性的示例：

"attributes": {
	"fallbackCurrentYear": {
		"type": "string"
	},
	"showStartingYear": {
		"type": "boolean"
	},
	"startingYear": {
		"type": "string"
	}
},

区块使用包含类似 JSON 特定属性的 HTML 样式注释标签进行“界定”。这些界定符使得在渲染文章内容或在区块编辑器中编辑文章时能够识别区块边界并解析区块属性。

以下代码示例展示了区块界定符中定义的属性。

<!-- wp:block-development-examples/copyright-date-block-09aac3 {"fallbackCurrentYear":"2023","showStartingYear":true,"startingYear":"2020"} -->
<p class="wp-block-block-development-examples-copyright-date-block-09aac3">© 2020–2023</p>
<!-- /wp:block-development-examples/copyright-date-block-09aac3 -->

默认情况下，所有属性都会被序列化并存储在区块的界定符中，但这可以根据您的需求进行配置。查看理解区块属性文章以了解更多信息。

读取和更新属性

这些属性会传递给区块的 Edit React 组件以在区块编辑器中显示，传递给 save 函数以生成存储在数据库中的标记，并传递给区块的任何服务器端渲染定义。

Edit 组件独特地具有通过 setAttributes 函数修改这些属性的能力。

下图详细说明了在典型区块中属性是如何存储、读取和更新的。

在此完整区块示例中查看属性如何传递给 Edit 组件、save 函数和 render.php。

有关属性以及如何在自定义区块中使用它们的更多信息，请访问属性 API 参考页面。

使用区块支持启用设置和样式

许多区块（包括核心区块）提供类似的定制选项，例如背景颜色、文本颜色和内边距调整。

block.json 中的 supports 属性允许区块声明支持一组这些常见的定制选项。启用后，区块用户可以直接从设置侧边栏调整颜色或内边距等内容。

利用这些预定义的区块支持有助于确保您的区块与核心区块行为一致，无需从头重新创建类似功能。

以下是在 block.json 中定义颜色支持的示例：

"supports": {
	"color": {
		"text": true,
		"link": true,
		"background": true
	}
}

使用区块支持会生成一组需要手动添加到区块包装元素的属性。这确保它们作为区块数据的一部分被正确存储，并在生成将交付给前端的区块标记时被考虑在内。

以下代码演示了通过启用区块支持生成的属性和 CSS 类如何存储在区块的标记表示中。

<!-- wp:block-development-examples/block-supports-6aa4dd {"backgroundColor":"contrast","textColor":"accent-4"} -->
<p class="wp-block-block-development-examples-block-supports-6aa4dd has-accent-4-color has-contrast-background-color has-text-color has-background">Hello World</p>
<!-- /wp:block-development-examples/block-supports-6aa4dd -->

查看上述代码的完整区块示例。

有关支持以及如何在自定义区块中使用它们的更多信息，请访问支持 API 参考页面。

11 KiB Raw Permalink Blame History Unescape Escape