云策 WordPress 开发者社区

社区新闻

介绍区块绑定，第一部分：连接自定义字段

查看官方原文 ↗ 发布于

浏览 WordPress 6.5 中即将到来的开发者专属功能清单，我就像圣诞节早晨的孩子，撕开包装纸，露出圣诞老人前一晚送来的所有好东西。但其中有一份特别的礼物。那份大的。那份我一直期盼的礼物。

它就是区块绑定 API。

对于扩展者来说，这是自 WordPress 5.0 和区块编辑器发布以来，我们一直要求的众多功能的基础。这个初始版本提供了对自定义字段集成、模式覆盖和自定义绑定的支持。

这篇文章是一个深入系列的开始，该系列将涵盖区块绑定是什么、为什么应该使用它们以及如何在项目中使用它们。在这第一篇文章中，您将学习如何将自定义字段绑定到区块属性。

我鼓励您留言说明您希望使用区块绑定 API 构建什么。您在 WordPress 6.5 中看到的只是一个极其强大功能的第一个迭代版本，它将在未来的版本中变得更好。

如果您在 WordPress 6.5 发布之前阅读本文，请确保您正在使用最新版本的 WordPress trunk 和最新版本的 Gutenberg 插件进行测试。请报告您发现的任何问题。

本教程向您展示如何使用自定义字段面板处理元数据，这对于许多用例来说效果很好。但在实际项目中，您很可能会为插件/主题用户构建自定义 UI 控件。或者您可以使用众多现有的自定义字段插件之一。这完全取决于您。

什么是区块绑定？

在我们深入探讨连接自定义字段等真正有趣的内容之前，让我们先打好基础。理解区块绑定 API 是什么以及为什么它对 WordPress 的未来至关重要非常重要。

区块和绑定的基本结构

看一下基本图像区块的标记：

<!-- wp:image -->
<figure class="wp-block-image"><img src="" alt=""/></figure>
<!-- /wp:image -->

区块绑定 API 的作用是让您将动态数据“绑定”到区块的属性，然后这些数据会反映在最终输出到前端浏览器的 HTML 标记中。

这意味着您可以做诸如将自定义 URL 绑定到图像区块的 url 属性，并将文本绑定到 alt 属性，数据可以来自自定义字段（文章元数据）、站点数据等。

还需要了解您想要绑定数据的区块有哪些可用属性。对于图像区块，您可以通过其 block.json 文件查看其属性。有很多潜在的属性。但在这个练习中，我们只关注 url 和 alt：

{
	"attributes": {
		"url": {
			"type": "string",
			"source": "attribute",
			"selector": "img",
			"attribute": "src",
			"__experimentalRole": "content"
		},
		"alt": {
			"type": "string",
			"source": "attribute",
			"selector": "img",
			"attribute": "alt",
			"default": "",
			"__experimentalRole": "content"
		}
	}
}

如果您仔细观察区块标记并将其与 block.json 中的 attributes 属性进行比较，您会发现：

  • url 区块属性映射到 <img src=""/>。
  • 同样，alt 区块属性映射到 <img alt=""/>。

在真实场景中，图像区块标记看起来更像这样（为清晰起见进行了格式化）：

<!-- wp:image {
	"lightbox":{"enabled":true},
	"id":1,
	"sizeSlug":"large",
	"linkDestination":"none"
} -->
<figure class="wp-block-image size-large">
	<img src="/path/to/image.jpg" alt="This is the image alt text" class="wp-image-1"/>
</figure>
<!-- /wp:image -->

此标记表明：

  • url 区块属性是 /path/to/image.jpg。
  • alt 区块属性是 This is the image alt text。

理解区块属性及其在标记中的表示方式之间的关系非常重要，因为区块绑定 API 完全与属性系统协同工作。

为什么区块绑定 API 有用

绑定功能如此强大的原因在于，您可以将动态数据绑定到区块属性。在 WordPress 6.5 之前，在区块系统中添加动态数据意味着构建自定义动态区块。

让我们看一个真实世界的例子。如果您打开 WP Movies Demo 中的你的名字电影页面，您会看到很多动态生成的数据：

WP Movies 演示中“你的名字”电影页面的截图。显示了关于电影的文本和图像。两个文本部分被高亮显示，以表明可能是元数据的区域。

您在那里看到的大部分内容（目前）是使用几个与元数据绑定的自定义区块构建的。您可以从项目的GitHub 仓库中看到这一点。如果团队不需要将所有那些都构建为自定义区块，而是可以使用他们现有的文章元字段呢？现在一些容易实现的目标是使用绑定来替换电影数据，例如：

  • 评分
  • 上映日期
  • 片长
  • 语言
  • 预算
  • 票房

为这类数据构建自定义区块在许多情况下一直感觉有些过度，特别是当您构建的基本 HTML 标记已经作为核心区块存在时。例如，既然核心段落区块存在，为什么要构建一个使用带有 RichText 内容的简单 <p> 元素的自定义区块？

如果您对高级 React JavaScript 不太熟悉，扩展 WordPress 的入门可能会感觉更像爬山。区块绑定 API 的第一个版本将使这种攀登不那么令人生畏，用更少的代码赋予您更多的能力。

沿用上一节中的图像区块示例，想象一下从各种来源连接自定义 URL，例如：

  • 自定义字段
  • 自定义数据库表
  • 图像附件模板上的媒体源
  • 用户未设置图像时的后备方案

您不需要为那些东西构建自定义区块。您可以通过核心或自定义绑定源（取决于场景）将数据直接绑定到现有的 WordPress 图像区块。

以下是从虚构绑定源获取数据时图像区块标记的示例：

<!-- wp:image {
	"metadata":{
		"bindings":{
			"url":{
				"source":"namespace/slug",
				"args":{
					"key":"some-field"
				}
			},
			"alt":{
				"source":"namespace/slug",
				"args":{
					"key":"some-other-field"
				}
			}
		}
	}
} -->
<figure class="wp-block-image">
<img src="" alt="" />
</figure>
<!-- /wp:image -->

说真的，您只需要插入几个字段就能让它工作。

我们稍后会讲解这些东西各自的作用。我只是想在深入之前让您熟悉一下标记。

关键是绑定允许您将来自任何源的任何动态数据附加到区块属性。（WordPress 6.5 将附带对少数核心区块和属性的有限支持，这些内容在本文末尾的表格中列出。）

想象一个 WordPress，您只需要将几个字段绑定到现有的基础区块（如图像、标题、段落等），就能创建出完全符合您用例需求的东西。

这个想法很令人兴奋，对吧？ 嗯，WordPress 6.5 为多种用例实现了这一点。

将自定义字段连接到区块属性

区块绑定 API 的主要用例之一是将自定义字段（即文章元数据）连接到区块。这可以像将自定义文本字段添加到段落区块一样简单。或者它可以处理更高级的场景，例如拉取自定义图像 URL 和替代文本来附加到图像区块。

我们将通过这两个示例来广泛介绍如何使用自定义字段，但我相信您心中已经有了很多用例。

启用自定义字段

考虑到本教程将涵盖的内容范围很广，我不想花太多时间讲解自定义字段的工作原理或如何为其构建自己的 UI 元素。这些内容超出了本文的范围，因此添加的任何自定义字段都将通过文章编辑器中的默认自定义字段面板完成。

要在编辑器中启用此面板，请打开文章编辑器中的选项（⋮ 图标）下拉菜单，然后单击首选项按钮。在高级部分下，将自定义字段选项切换为开启：

标题为“首选项”的面板，包含多个选项卡。当前打开了“常规”选项卡，并且“自定义字段”选项已勾选开启。

系统会要求您重新加载浏览器，以便自定义字段面板出现在编辑器底部。

基础：将文本字段绑定到段落区块

让我们从一个最简单的可能示例开始：注册一个元键并将其绑定到段落区块。我们来构建一个显示今天心情的东西怎么样？

始终建议使用您的插件或主题 slug 作为自定义元键的前缀。它应该看起来像这样：projectslug_key。

您的 PHP 代码可以从自定义插件文件或主题的 functions.php 运行。打开您选择的文件并注册一个名为 projectslug_mood 的文章元键：

add_action( 'init', 'projectslug_register_meta' );

function projectslug_register_meta() {
	register_meta(
		'post',
		'projectslug_mood',
		array(
			'show_in_rest'      => true,
			'single'            => true,
			'type'              => 'string',
			'sanitize_callback' => 'wp_strip_all_tags'
		)
	);
}

再次强调，本教程不是关于如何注册元数据。请记住，您必须将 show_in_rest 设置为 true，元字段才能通过 REST API 和在区块编辑器中工作。有关注册自定义元数据的更多信息，请参阅 register_meta() 文档。

现在您已经注册了文章元数据，可以测试自定义值并将其绑定到区块了。

从 WordPress 管理后台打开文章编辑器，向下滚动到自定义字段面板。在名称字段下添加 projectslug_mood 键，并在值字段中输入任何您想要的文本。然后点击添加自定义字段按钮：

WordPress 文章编辑器，内容区域为空。自定义字段面板设置了一个键，名称为“projectslug_mood”。

WordPress 6.5 没有内置的 UI 用于将自定义字段绑定到区块，因此下一步您需要切换到代码编辑器视图。您可以通过选项菜单（右上角面板中的⋮按钮）找到它。

现在将此区块标记添加到编辑器中：

<!-- wp:paragraph {
	"metadata":{
		"bindings":{
			"content":{
				"source":"core/post-meta",
				"args":{
					"key":"projectslug_mood"
				}
			}
		}
	}
} -->
<p></p>
<!-- /wp:paragraph -->

在我们走得太远之前，让我们花点时间研究一下您刚刚输入的区块标记。那里肯定有很多嵌套属性！

以下是每个嵌套属性的概述：

  • metadata： 包含区块元数据的对象。
  • bindings： 可以包含区块的一个或多个绑定的对象。
  • content： 要绑定到自定义字段的区块属性。在本例中，它是段落区块的 content 属性。
  • source： 通过区块绑定 API 注册的绑定源，将在服务器端处理返回值。必须将其设置为 core/post-meta 才能使用内置的自定义字段处理（我们将在本系列的第 2 部分介绍其他源）。
  • args： 可以包含一个或多个要传递给区块绑定源的参数的对象。对于自定义字段，您必须始终将 key 属性设置为要绑定到区块属性的元键名称。

现在切换回可视化编辑器视图。您可能首先会看到 projectslug_mood 键显示为段落内容。重要的是，您不应该能够从可视化编辑器本身编辑它。

保存文章后，您输入到自定义字段面板中的值应该会出现在其位置：

WordPress 文章编辑器，其中包含一个段落，内容为：“Jammin' with my friends.”

如果您在网站的前端查看文章，您应该看到完全相同的输出。

当然，在实际项目中，您将构建自定义 UI 或使用第三方插件来输入数据。而且，通常您实际上会在模式或模板中输出这些字段。这只是测试底层 API 和自定义字段的一种快速而简洁的方法。

更高级：图像区块上的多个绑定

让我们更进一步，尝试向单个区块注册两个不同的绑定。在这个练习中，您将向图像区块添加自定义 URL 和替代文本。过程几乎相同。

首先，为文章注册两个元数据键：

  • projectslug_image_url： 这将存储您将绑定到图像区块 url 属性的 URL。
  • projectslug_image_alt： 您将绑定到 alt 属性的替代文本。

打开您的插件文件或主题的 functions.php（无论您在上一步中决定使用哪个）。然后将此代码添加到您之前添加的 projectslug_register_meta() 函数中：

register_meta(
	'post',
	'projectslug_image_url',
	array(
		'show_in_rest'      => true,
		'single'            => true,
		'type'              => 'string',
		'sanitize_callback' => 'esc_url_raw'
	)
);

register_meta(
	'post',
	'projectslug_image_alt',
	array(
		'show_in_rest'      => true,
		'single'            => true,
		'type'              => 'string',
		'sanitize_callback' => 'wp_strip_all_tags'
	)
);

返回 WordPress 管理后台的文章编辑器。在向自定义字段面板添加任何数据之前，让我们看看带有绑定的空图像区块是什么样子。

打开代码编辑器视图并将此区块标记粘贴到其中：

<!-- wp:image {	"metadata":{
		"bindings":{
			"url":{
				"source":"core/post-meta",
				"args":{
					"key":"projectslug_image_url"
				}
			},
			"alt":{
				"source":"core/post-meta",
				"args":{
					"key":"projectslug_image_alt"
				}
			}
		}
	}
} -->
<figure class="wp-block-image">
<img src="" alt="" />
</figure>
<!-- /wp:image -->

如果您还记得上一节的内容，区块的 bindings 属性可以包含多个属性。请注意与上一节中段落区块相比的结构。

添加代码后，切换回可视化编辑器。您的图像区块应该看起来像这样：

WordPress 文章编辑器，内容区域中有一个图像区块。它显示一条消息：“Image: Connected to a custom field.”

如您所见，图像区块周围的 UI 默认情况下稍微好一些。它提供了一条消息，表明该区块已连接到自定义字段。如果您打开区块的侧边栏面板，您也应该在替代文本字段中看到相同的消息。

最重要的是，图像上传和替代文本字段都应该被锁定，无法编辑。

现在转到文章编辑器中的自定义字段面板，为 projectslug_image_url 元键输入自定义图像 URL，并为 projectslug_image_alt 输入自定义文本。

保存字段和文章后，图像区块应该会以正确的图像和替代文本出现在 UI 中：

WordPress 文章编辑器，显示一张道路和山脉的图像。编辑器底部是与图像 URL 和替代文本关联的两个自定义字段。

添加后备元值

核心的 register_meta() 函数允许您注册一个 default 字段。如果您在注册元键时设置此字段，它将作为默认值出现，直到用户设置了元值。

让我们重新看一下上一节中为图像区块注册元键的代码。现在为 projectslug_image_url 元添加一个新的 default 参数。在下面的示例中，您可以看到我已将其设置为我主题文件夹中的图像 URL：

register_meta(
	'post',
	'projectslug_image_url',
	array(
		'show_in_rest'      => true,
		'single'            =>