构建自定义古腾堡积木：最终积木开发教程

许多人抱怨开始构建古腾堡块和应用程序的障碍。学习曲线陡峭，主要是由于安装和配置开发环境的难度。此外，扎实的 JavaScript、Node.js、React 和 Redux 知识是这个相当复杂的配方的必备要素。

尝试免费演示

官方 WordPress 块编辑器手册为开发人员提供了大量信息，但您可能会发现自己迷失在细节的海洋中。

值得一提的是古腾堡项目的首席架构师马蒂亚斯文图拉在接受 WP Tavern 采访时报道的内容：

虽然有些人可以很快学会它，但这对人们来说仍然是一个很大的障碍。我认为这有几个层次；文档在组织和演示方面可能要好一个数量级。我希望我们可以在那里做得更多。

考虑到这一点，我们决定提供一个分步教程，旨在帮助我们的读者开始使用 Gutenberg 块开发。

听起来很有趣？让我们潜入吧！

古腾堡块开发先决条件

对于本教程，唯一需要的技能是 WordPress 插件开发的良好知识以及至少对 HTML、CSS、JavaScript 和 React 的基本了解。

这会是一个雄心勃勃的项目吗？你打赌它会！

要在完整性和简单性之间找到正确的折衷方案，或者决定要包含哪些主题以及要删除哪些主题并不容易。

希望中高级读者能原谅我们没有深入研究某些概念，例如 React 状态、Redux 存储、高阶组件等。这些主题需要额外的空间和注意力，并且对于开始块开发来说可能太高级了（除非您是 React 开发人员）。

出于同样的原因，我们不会涵盖与古腾堡块开发相关的一些更高级的主题，例如动态块和元框。

通过本文结束时您将获得的知识，您将能够立即开始享受乐趣并提高工作效率。

一旦开始构建积木，您就可以进一步提高技能并自行构建更高级的古腾堡积木。

#008cc4}从古腾堡块开发开始，一开始可能会令人生畏…… 😵‍💫 但不要害怕！这份完整的初学者指南让您了解🙏点击推文

什么是古腾堡块？

自 2018 年 12 月首次发布以来，块编辑器在各个方面都得到了极大的改进：更强大的 API、更先进的用户界面、改进的可用性、大量新块、完整站点编辑的首次实现等等.

简而言之，即使 Gutenberg 仍在大力开发中，它已经走了很长一段路——今天，块编辑器是一个成熟的候选者，作为一个可靠的、功能性的页面和站点构建器。

从开发人员的角度来看，Gutenberg 是一个基于 React 的单页应用程序 (SPA)，它允许 WordPress 用户在 WordPress 中创建、编辑和删除内容。但是，这不应让您想到传统内容编辑器的增强版本。

我们想明确这一点：

Gutenberg 不是常规的 WYSIWYG 编辑器。相反，它重新定义了 WordPress 中的整个编辑体验。

在 Gutenberg 中，内容被分成块，这些块是用户可以用来创建帖子和页面或整个网站的“砖块”。

但从技术上讲，什么是块？

我们喜欢 WordPress 的定义：

“块”是一个抽象术语，用于描述组合在一起形成网页内容或布局的标记单元。这个想法结合了我们今天在 WordPress 中通过短代码、自定义 HTML 实现的概念，并将发现嵌入到单个一致的 API 和用户体验中。

标题、段落、列、图像、画廊以及构成编辑器界面的所有元素，从侧边栏面板到块工具栏控件，都是 React 组件。

那么，什么是 React 组件？W3Schools 提供了以下定义：

组件是独立且可重用的代码位。它们与 JavaScript 函数的用途相同，但独立工作并通过 render() 函数返回 HTML。

在 WordPress 5.8 中使用 Gutenberg 块。

虽然与经典的 WordPress 编辑器相比，Gutenberg 提供的编辑体验是全新的，但 WordPress 在数据库中存储您的内容的方式根本没有改变。这是因为 Gutenberg 是一个在 WordPress 中运行的应用程序，但不会改变 CMS 的核心工作方式。

使用 Gutenberg 创建的帖子（包括帖子、页面和自定义帖子类型）仍然存储在 wp_posts 表中，与经典编辑器完全一样。

但是在使用 Gutenberg 创建的帖子中，您会在表格中找到更多信息，这些信息代表了通过 Classic Editor 创建的帖子与 Gutenberg 创建的帖子之间的根本区别。

这些信息看起来像 HTML 注释，它们有一个特定的功能：分隔块：

代码编辑器视图中的博客文章。

块分隔符告诉 WordPress 要在屏幕上呈现什么块。它们还为 JSON 对象中的块属性提供值。这些道具决定了块在屏幕上的呈现方式：

存储在 wp_posts 表中的博客文章。

设置您的 WordPress 开发环境

设置现代 JavaScript 开发环境需要扎实的高级技术知识，例如 Webpack、React 和 JSX、Babel、ESLint 等。

恐吓？不要！WordPress 社区已经通过提供强大的工具来帮助您避免繁琐的手动配置过程。

为简单起见，我们不会在本文中介绍转译（不过我们建议您在了解块开发的基础知识后熟悉一下）。相反，我们将介绍两种替代工具，您可以使用它们在几分钟内快速轻松地设置现代 JavaScript 开发环境。您可以选择最适合您的项目的一种。

设置 JavaScript 开发环境来构建 Gutenberg 块是一个三步过程：

安装 Node.js 和 npm
设置开发环境
设置块插件

让我们开始吧。

1. 安装 Node.js 和 npm

在安装开发环境和注册第一个块之前，您需要安装 Node.js 和 Node 包管理器 (npm)。

信息

Node.js 是一个基于 Chrome 的 V8 JavaScript 引擎构建的 JavaScript 运行时。npm，通常被称为 Node 包管理器，被认为是“世界上最大的软件注册表”。

您可以通过多种不同方式安装 Node.js 和 npm。但首先，您可能需要检查该软件是否已安装在您的机器上。

为此，请启动终端并运行以下命令：

节点 -v

如果结果是command not found，则说明你的电脑没有安装Node.js，你可以继续安装。

对于本文，我们选择了最简单的安装选项，即节点安装程序。您需要做的就是下载与您的操作系统相对应的版本并启动安装向导：

Node.js 下载页面。

安装 Node.js 后，再次在终端中运行命令 node -v。您还可以运行 npm -v 命令来确认您有可用的 npm 包。

您现在配备了以下工具：

npx Node.js 包运行程序（参见文档）。这允许您运行 npm 命令而无需先安装它。
npm Node.js 包管理器（参见文档）。这用于安装依赖项和运行脚本。

下一步是安装开发环境。

2. 设置您的开发环境

在本地机器上安装最新版本的 Node.js 和 npm 后，您将需要一个 WordPress 开发环境。

您可以使用 DevKinsta 等本地开发环境或使用官方 WordPress 工具。让我们看一下这两个选项。

选项 1：本地开发环境 (DevKinsta)

只需点击几下，您就可以使用我们现代的本地 WordPress 开发工具 DevKinsta 在本地安装 WordPress。或者您可以选择不同的本地开发工具，例如 MAMP 或 XAMPP：

在 DevKinsta 中创建一个新的 WordPress 网站。

选项 2：wp-env

您还可以选择官方 wp-env 工具，它提供了一个本地 WordPress 开发环境，您可以直接从命令行启动。Noah Alen 将其定义如下：

本地 WordPress 环境现在就像运行单个命令一样简单。wp-env 是一种用于无痛本地 WordPress 环境的零配置工具。它提供了对选项的决定，以便用户可以快速启动 WordPress 而不会浪费时间。事实上，我们的目标是让所有人都能轻松访问这些环境——无论您是开发人员、设计师、经理还是其他任何人。

如果您决定尝试一下，安装 wp-env 只需最少的努力。只需按照以下步骤操作：

第 1 步：确认 Docker 和 Node.js 安装

为了满足技术要求，您首先需要在您的计算机上安装 Docker 和 Node.js。那是因为 wp-env 创建了一个运行 WordPress 网站的 Docker 实例。对代码所做的任何更改都会立即反映在 WordPress 实例中。

第 2 步：从命令行安装 @wordpress/env

随着 Docker 和 Node.js 在您的计算机上运行，您可以继续安装 WordPress 开发环境。

您可以全局或本地安装 wp-env。要全局执行此操作，您需要从插件目录中运行以下命令（在下面的“重要”通知框中有更多相关信息）：

npm install -g @wordpress/env

让我们分解一下：

npm install 安装包。
-g 附加到命令后全局安装指定的包。
@wordpress/env 是您要安装的软件包。

重要的

默认情况下，在 Mac 或 Linux 上，节点包安装在 /usr/local/lib/node_modules 中。

如果当前用户对该目录没有写权限，则会发出 EACCES 错误。了解有关在全局安装软件包时解决 EACCES 权限错误的更多信息。

要确认 wp-env 已成功安装，请运行以下命令：

wp-env –version

您应该会看到当前的 wp-env 版本，这意味着您现在可以使用插件文件夹中的以下命令启动环境：

wp-env 开始

您可以使用以下地址访问 WordPress 仪表板：

http://localhost:8888/wp-admin/

默认凭据如下：

用户名：管理员
密码：密码

设置块插件

现在你需要一个启动块插件来构建。但是，无需手动创建包含所有必要文件和文件夹的开发块插件，您只需运行一个开发工具即可提供开始块开发所需的所有文件和配置。

同样，您有几个选项可供选择。让我们来看看每一个。

选项 1：使用 @wordpress/create-block 设置块插件

@wordpress/create-block 是用于创建古腾堡块的官方零配置工具：

创建块是官方支持的创建块的方式，用于为 WordPress 插件注册块。它提供了无需配置的现代构建设置。它生成 PHP、JS、CSS 代码以及启动项目所需的一切。

它很大程度上受到 create-react-app 的启发。向@gaearon、整个 Facebook 团队和 React 社区致敬。

本地环境启动并运行后，您可以通过简单地运行 npx @wordpress/create-block 命令来设置启动块，它将提供创建插件脚手架和注册新块所需的所有文件和文件夹.

让我们运行一个测试，看看它是如何工作的。

从您的命令行工具，导航到 /wp-content/plugins/ 目录并运行以下命令：

npx @wordpress/create-block my-first-block

当要求确认时，输入 y 继续：

使用@wordpress/create-block 创建一个块。

这个过程需要几分钟。完成后，您应该得到以下响应：

块插件已创建。

就是这样！

现在启动您的 WordPress 开发环境并转到 WordPress 仪表板中的插件屏幕。一个名为“My First Block”的新插件应该已添加到您的插件列表中：

块插件已成功安装。

信息

如果您使用 wp-env 工具并从包含插件的目录运行 wp-env start，它将自动挂载并激活插件。如果您从任何其他目录运行 wp-env start，将创建一个通用的 WordPress 环境（另请参阅 WordPress 开发站点）。

如果需要，激活插件，创建一个新的博客文章，将块插入器向下滚动到小部件部分，然后选择您的新块：

使用@wordpress/create-block 创建的示例块。

现在返回终端并将当前目录更改为 my-first-block：

cd my-first-block

然后运行以下命令：

海拔开始

这使您能够在开发模式下运行插件。要创建生产代码，您应该使用以下命令：

npm run build
选项 2：使用 create-guten-block 设置块插件

create-guten-block 是用于构建 Gutenberg 块的第三方开发工具：

create-guten-block 是零配置开发工具包 (#0CJS)，可在几分钟内开发 WordPress Gutenberg 块，无需配置 React、webpack、ES6/7/8/Next、ESLint、Babel 等。

就像官方的 create-block 工具一样，create-guten-block 基于 create-react-app，可以帮助您轻松生成第一个块插件。

该工具包提供了创建现代 WordPress 插件所需的一切，包括以下内容：

React、JSX 和 ES6 语法支持。

幕后的 webpack 开发/生产构建过程。

ES6 之外的语言附加功能，如对象扩展运算符。

自动前缀 CSS，因此您不需要 -webkit 或其他前缀。

一个构建脚本，用于将 JS、CSS 和图像与源映射捆绑在一起进行生产。

使用单个依赖项 cgb-scripts 轻松更新上述工具。

请注意以下警告：

权衡是这些工具预先配置为以特定方式工作。如果您的项目需要更多自定义，您可以“弹出”并自定义它，但是您将需要维护此配置。

手头有本地 WordPress 网站后，启动命令行工具，导航到安装的 /wp-content/plugins 文件夹，然后运行以下命令：

npx create-guten-block my-first-block

创建项目结构并下载依赖项时，您必须等待一两分钟：

使用 create-guten-block 创建古腾堡块。

该过程完成后，您应该看到以下屏幕：

使用 create-guten-block 成功创建了古腾堡块。

下图显示了在 Visual Studio Code 中运行终端的项目结构：

Visual Studio Code 中的块插件。

现在回到您的 WordPress 仪表板。插件屏幕中应该列出一个新项目——它是 my-first-block 插件：

带有使用 create-guten-block 创建的新插件的插件屏幕。

激活插件并返回终端。将当前目录更改为 my-first-block，然后运行 npm start：

cd my-first-block
npm start

您应该得到以下响应：

npm 开始了。

同样，这使您能够在开发模式下运行插件。要创建生产代码，您应该使用：

npm 运行构建

激活插件并创建新帖子或页面，然后浏览您的块并选择您全新的古腾堡块：

使用 create-guten-block 创建的新块。

如需更深入的概述或出现错误，请参阅 Ahmad Awais 提供的文档。

入门级脚手架演练

无论您选择两种开发工具中的哪一种——create-block 或 create-guten-block——，您现在都有一个块脚手架，您可以将其用作构建块插件的起点。

但究竟什么是块状脚手架？

块脚手架是一个速记术语，它描述了 WordPress 识别块所需的支持目录结构。通常，该目录包含诸如 index.php、index.js、style.css 等文件，这些文件又包含诸如 register_block_type 之类的调用。

我们选择了官方的 Create Block 开发工具，因为它在 Block Editor 手册中使用过。但即使您决定使用诸如 create-guten-block 之类的第三方工具，您的体验也不会有太大的不同。

话虽如此，让我们深入研究创建块工具。

仔细看看创建块开发工具

正如我们上面提到的，Create Block 是用于创建古腾堡块的官方命令行工具。在终端中运行 @wordpress/create-block 会生成注册新块类型所需的 PHP、JS 和 SCSS 文件和代码：

npx @wordpress/create-block [选项] [slug]

[slug] (可选) — 用于分配块 slug 并安装插件
[options] (optional) — 可用选项

默认情况下，分配了 ESNext 模板。这意味着您将获得下一个版本的 JavaScript，其中添加了 JSX 语法。

如果省略块名称，该命令将以交互模式运行，使您能够在生成文件之前自定义几个选项：

npx @wordpress/create-block
以交互模式运行 create-block。

以交互模式运行 create-block。

下图显示了使用官方创建块工具创建的块插件的文件结构：

使用@wordpress/create-block 创建的块插件的文件和文件夹。

话虽如此，让我们浏览一下新块插件的主要文件和文件夹。

插件文件

使用主插件文件在服务器上注册块：

/**
* 插件名称：My First Block
* 描述：使用 ESNext 标准和 JSX 支持编写的示例块 – 需要构建步骤。
* 至少需要：5.8
* 需要 PHP：7.0
* 版本：0.1.0
* 作者：WordPress 贡献者
* 许可证：GPL-2.0-或-later
* 许可证 URI：https://www.gnu.org/licenses/gpl -2.0.html
* 文本域：my-first-block
*
* @package create-block
*/
/**
* 使用从`block.json` 文件加载的元数据注册块。
* 在幕后，它还注册所有资产，以便它们可以
通过相应上下文中的块编辑器进行排队*。
*
* @see https://developer.wordpress.org/block-editor/tutorials/block-tutorial/writing-your-first-block-type/
*/
function create_block_my_first_block_block_init() {
register_block_type( __DIR__ );
}
add_action(‘init’, ‘create_block_my_first_block_block_init’);

register_block_type 函数使用存储在 block.json 文件中的元数据在服务器上注册块类型。

该函数有两个参数：

块类型名称，包括命名空间，或 block.json 文件所在文件夹的路径，或完整的 WP_Block_Type 对象
块类型参数数组

在上面的代码中，块类型参数由 __DIR__ 魔术常量提供。这意味着 block.json 文件与插件文件位于同一文件夹中。

package.json 文件

package.json 文件为您的项目定义 JavaScript 属性和脚本。您可以在此处安装项目依赖项。

为了更好地理解这个文件的用途，用你最喜欢的代码编辑器打开它：

{
“name”: “my-first-block”,
“version”: “0.1.0”,
“description”: “使用 ESNext 标准和 JSX 支持编写的示例块 – 需要构建步骤。”,
“author”: “The WordPress Contributors”,
“license”: “GPL-2.0-or-later”,
“main”: “build/index.js”,
“scripts”: {
“build”: “wp-scripts build”,
“format”: “wp-scripts 格式”,
“lint:css”: “wp-scripts lint-style”,
“lint:js”: “wp-scripts lint-js”,
“start”: “wp-scripts start”,
“packages -update”: “wp-scripts 包更新”
},
“dependencies”: {
“@wordpress/block-editor”: “^7.0.1”,
“@wordpress/blocks”: “^11.0.1”,
“@wordpress/i18n”: “^4.2.1”
},
“devDependencies”: {
“@wordpress/scripts”: “^18.0.0”
}
}

scripts 属性是一个字典，其中包含使用 npm run [cmd] 在包的生命周期中的不同时间运行的命令。

在本文中，我们将使用以下命令：

npm run build — 创建一个（压缩的）生产构建
npm run start — 创建一个（未压缩的）开发构建

dependencies 和 devDependencies 是将包名映射到版本的两个对象。生产中需要依赖关系，而 devDependences 仅用于本地开发（阅读更多）。

唯一的默认开发依赖项是 @wordpress/scripts 包，它被定义为“为 WordPress 开发量身定制的可重用脚本的集合”。

block.json 文件

从 WordPress 5.8 开始，block.json 元数据文件是注册块类型的规范方式。

拥有一个 block.json 文件提供了几个好处，包括改进的性能和更好的 WordPress 插件目录可见性：

从性能的角度来看，当主题支持延迟加载资产时，使用 block.json 注册的块将使其资产入队优化开箱即用。样式或脚本属性中列出的前端 CSS 和 JavaScript 资产仅在页面上存在块时才会加入队列，从而减小页面大小。

运行 @wordpress/create-block 命令会生成以下 block.json 文件：

{
“apiVersion”: 2,
“name”: “create-block/my-first-block”,
“version”: “0.1.0”,
“title”: “My First Block”,
“category”: “widgets” ,
“icon”: “smiley”,
“description”: “使用 ESNext 标准和 JSX 支持编写的示例块 – 需要构建步骤。”,
“supports”: {
“html”: false
},
“textdomain”: “my-first
-block “, “editorScript”: “file:./build/index.js”,
“editorStyle”: “file:./build/index.css”,
“style”: “file:./build/style-index .css”
}

这是默认属性的完整列表：

apiVersion — 区块使用的 API 版本（当前版本为 2）
name — 包含命名空间的块的唯一标识符
version — 区块的当前版本
title — 块的显示标题
category — 块类别
图标 — Dashicon slug 或自定义 SVG 图标
description — 在块检查器中可见的简短描述
支持 — 一组用于控制编辑器中使用的功能的选项
textdomain — 插件文本域
editorScript — 编辑器脚本定义
editorStyle — 编辑器样式定义
style — 为块提供替代样式

除了上面列出的属性之外，您还可以（并且可能会）定义一个属性对象，提供有关您的块存储的数据的信息。在您的 block.json 中，您可以在键/值对中设置任意数量的属性，其中键是属性名称，值是属性定义。

看看下面的属性定义示例：

“attributes”: {
“content”: {
“type”: “array”,
“source”: “children”,
“selector”: “p”
},
“align”: {
“type”: “string”,
“default “: “none”
},
“link”: {
“type”: “string”,
“default”: “https://kinsta.com”
}
},

我们将在本文后面深入研究 block.json 文件，但您可能还想查看 Block Editor Handbook 以获取有关 block.json 元数据和属性的更多详细信息。

源文件夹

src 文件夹是进行开发的地方。在该文件夹中，您将找到以下文件：

索引.js
编辑.js
保存.js
编辑器.scss
样式文件

索引.js

index.js 文件是您的起点。在这里，您将导入依赖项并在服务器上注册块类型：

从’@wordpress/blocks’ 导入 { registerBlockType };
导入’./style.scss’;
从’./edit’导入编辑；
从’./save’导入保存；

registerBlockType(‘create-block/my-first-block’, {
编辑：编辑，
保存，
});

第一条语句从@wordpress/blocks 包中导入 registerBlockType 函数。以下导入语句导入样式表以及编辑和保存功能。

registerBlockType 函数在客户端注册组件。该函数采用两个参数：一个块名称命名空间/块名称（与在服务器上注册的相同）和一个块配置对象。

Edit 函数提供在块编辑器中呈现的块界面，而 save 函数提供将被序列化并保存到数据库中的结构（阅读更多）。

编辑.js

edit.js 是您构建块管理界面的地方：

从’@wordpress/i18n’导入{__}；
从’@wordpress/block-editor’ 导入 { useBlockProps };
导入’./editor.scss’;

导出默认函数 Edit() {
return (
<p {…useBlockProps()}>
{__(‘My First Block – hello from the editor!’, ‘my-first-block’)}
</p>
);
}

首先，它从@wordpress/i18n 包（该包包含翻译函数的 JavaScript 版本）、useBlockProps React 钩子和 editor.scss 文件中导入 __ 函数。

之后，它导出 React 组件（阅读有关导入和导出语句的更多信息）。

保存.js

save.js 文件是我们构建要保存到数据库中的块结构的地方：

从’@wordpress/i18n’导入{__}；
从“@wordpress/block-editor”导入 { useBlockProps };

export default function save() {
return (
<p {…useBlockProps.save()}>
{__(
‘My First Block – hello from the saved content!’,
‘my-first-block’
)}
</p >
);
}
editor.scss 和 style.scss

除了脚本之外，两个 SASS 文件驻留在 src 文件夹中。editor.scss 文件包含应用于编辑器上下文中的块的样式，而 style.scss 文件包含用于在前端显示的块的样式。我们将在本指南的第二部分深入研究这些文件。

node_modules 和 build 文件夹

node_modules 文件夹包含节点模块及其依赖项。我们不会深入研究 node 包，因为它超出了本文的范围，但您可以在本文中阅读有关 npm 安装包的位置的更多信息。

build 文件夹包含构建过程产生的 JS 和 CSS 文件。您可以在 ESNext 语法和 JavaScript 构建设置指南中更深入地了解构建过程。

项目：建造你的第一个古腾堡街区

是时候弄脏我们的手了。本节将教你如何创建一个插件，提供一个名为 Affiliate Block 的 CTA 块。

该块将由两列组成，左侧是图像，右侧是文本段落。带有可自定义链接的按钮将放置在文本下方：

您将在本指南中学习构建的块类型。

这只是一个简单的例子，但它使我们能够涵盖古腾堡块开发的基础知识。一旦您对基础知识有了清晰的了解，您就可以在块编辑器手册和任何其他可用的大量资源的帮助下继续创建越来越复杂的古腾堡块。

信息

本教程中提供的示例代码也可以在 Gist 上找到以供您参考。

假设您在本地开发环境中运行了最新版本的 WordPress，以下是您将从这里学到的内容：

如何设置 Starter Block 插件
工作中的 block.json
使用内置组件：RichText 组件
向块工具栏添加控件
自定义块设置侧栏
添加和自定义外部链接
添加多个块样式
使用 InnerBlocks 组件嵌套块
其他改进

预备，准备，开始！

如何设置 Starter Block 插件

启动命令行工具并导航到 /wp-content/plugins 文件夹：

Mac OS 文件夹中的新终端。

现在，运行以下命令：

npx @wordpress/create-block

此命令会生成 PHP、SCSS 和 JS 文件，用于以交互模式注册块，让您可以轻松地为块添加必要的数据。对于我们的示例，我们将使用以下详细信息：

块 slug：my-affiliate-block
内部命名空间：my-affiliate-plugin
块显示标题：附属块
简短的块描述：Kinsta 阅读器的示例块
Dashicon：钱
类别名称：设计
插件作者：你的名字
执照： –
许可证文本链接： –
当前插件版本：0.1.0

安装插件和所有依赖项需要几分钟时间。该过程完成后，您将看到以下响应：

Affiliate 块已安装并注册用于开发。

现在，从 /wp-content/plugins 文件夹运行以下命令：

cd my-affiliate-block

信息

如果您正在运行 WordPress 环境，则应首先启动 Docker Desktop，然后从插件文件夹中运行 wp-env start。

然后，您可以从 Web 浏览器启动 http://localhost:8888/wp-login 并使用 Username: admin 和 Password: password 登录到您的 WordPress 仪表板。

从 Visual Studio Code 终端运行命令。

最后，从您的插件文件夹（在我们的示例中为 my-affiliate-block），您可以开始开发：

海拔开始

现在打开插件屏幕以查找并激活 Affiliate Block 插件：

联盟块插件。

创建一个新帖子，打开块插入器，然后向下滚动到设计类别。单击以添加联盟块：

使用@wordpress/create-block 构建的起始块。

工作中的 block.json

正如我们之前提到的，服务器端块注册发生在主 .php 文件中。但是，我们不会在 .php 文件中定义设置。相反，我们将使用 block.json 文件。

因此，再次打开 block.json 并仔细查看默认设置：

{
“apiVersion”: 2,
“name”: “my-affiliate-plugin/my-affiliate-block”,
“version”: “0.1.0”,
“title”: “Affiliate Block”,
“category”: “design “,
“icon”: “money”,
“description”: “Kinsta 读者的示例块”,
“supports”: {
“html”: false
},
“textdomain”: “my-affiliate-block”,
“editorScript” : “file:./build/index.js”,
“editorStyle”: “file:./build/index.css”,
“style”: “file:./build/style-index.css”
}
脚本和样式

editorScript、editorStyle 和 style 属性提供前端和后端脚本和样式的相对路径。

您不必手动注册此处定义的脚本和样式，因为它们会由 WordPress 自动注册和排队。为了证明这一点，启动浏览器检查器并打开网络选项卡：

在 Chrome DevTools 中检查资源。

从上图可以看出，我们在 build 文件夹中的 index.js 脚本已经定期排队，无需添加任何 PHP 代码。

订阅时事通讯

想知道我们是如何将流量增加超过 1000% 的吗？

加入 20,000 多名其他人，他们会收到我们的每周时事通讯，其中包含 WordPress 内幕技巧！

现在订阅

用户界面标签

title 和 description 属性提供了在编辑器中识别块所需的标签：

块侧边栏中的块名称和描述。

关键词

正如我们之前提到的，您可以使用属性和属性准确配置块设置。例如，您可以添加一个或多个关键字来帮助用户搜索块：

{ “关键字”: [ “kinsta”, “affiliate”, “money” ] }

如果您现在在快速插入器中输入“kinsta”、“affiliate”或“money”，编辑器会建议您选择 Affiliate 块：

在快速插入器中使用关键字搜索块。

本土化

如果您想知道 JSON 文件中字符串的本地化是如何发生的，答案如下：

在 JavaScript 中，您现在可以使用 @wordpress/blocks 包中的 registerBlockTypeFromMetadata 方法来使用从 block.json 文件加载的元数据注册块类型。所有本地化的属性都会自动包装在 _x（来自 @wordpress/i18n 包）函数调用中，类似于它在 PHP 中使用 register_block_type_from_metadata 的工作方式。唯一的要求是在 block.json 文件中设置 textdomain 属性。

这里我们使用 registerBlockType 函数而不是 registerBlockTypeFromMetadata，因为后者自古腾堡 10.7 以来已被弃用，但机制是相同的。

使用内置组件：RichText 组件

组成 Gutenberg 块的元素是 React 组件，您可以通过 wp 全局变量访问这些组件。例如，尝试在浏览器的控制台中键入 wp.editor。这将为您提供 wp.editor 模块中包含的组件的完整列表。

滚动列表并猜测组件名称的含义。

同样，您可以查看 wp.components 模块中包含的组件列表：

WP 编辑器组件。

信息

模块化编程是一种软件设计技术，它强调将程序的功能分成独立的、可互换的模块，这样每个模块都包含执行所需功能的一个方面所需的一切（来源：维基百科）。

现在回到 edit.js 文件并仔细查看脚本：

从’@wordpress/i18n’导入{__}；
从’@wordpress/block-editor’ 导入 { useBlockProps };
导入’./editor.scss’;

导出默认函数 Edit() {
return (
<p {…useBlockProps()}>
{__(‘My First Block – hello from the editor!’, ‘my-first-block’)}
</p>
);
}

此代码生成一个带有简单、不可编辑文本的静态块。但是我们可以很容易地改变事情：

代码编辑器中的起始块。

要使文本可编辑，您必须将当前的 <p> 标记替换为使输入内容可编辑的组件。为此，Gutenberg 提供了内置的 RichText 组件。

将内置组件添加到您的块是一个 5 步过程：

从 WordPress 包中导入所需的组件
在 JSX 代码中包含相应的元素
在 block.json 文件中定义必要的属性
定义事件处理程序
保存数据

步骤 1：从 WordPress 包中导入所需的组件

现在打开 edit.js 文件并更改以下导入语句：

从“@wordpress/block-editor”导入 { useBlockProps };

…到：

从“@wordpress/block-editor”导入 { useBlockProps, RichText };

这样，您将从@wordpress/block-editor 包中导入 useBlockProps 函数和 RichText 组件。

使用块道具

useBlockProps React 钩子标记块的包装元素：

使用 API 版本 2 时，您必须在块的编辑函数中使用新的 useBlockProps 钩子来标记块的包装元素。该钩子将插入启用块行为所需的属性和事件处理程序。您希望传递给块元素的任何属性都必须通过 useBlockProps 传递，并将返回值传播到元素上。

简单地说，useBlockProps 会自动将属性和类分配给包装元素（我们示例中的 p 元素）：

useBlockProps 生成的元素和类。

如果您从包装元素中删除 useBlockProps，您将拥有一个无法访问块功能和样式的简单文本字符串：

没有 useBlockProps 的相同块。

正如我们稍后将解释的，您还可以向 useBlockProps 传递一个属性对象来自定义输出。

富文本

RichText 组件提供了一个 contenteditable 输入，允许用户编辑和格式化内容。

您可以在 GitHub 上的 Gutenberg/packages/block-editor/src/components/rich-text/README.md 上找到该组件。

第 2 步：将相应元素包含到您的 JSX 代码中
…

const blockProps = useBlockProps();

return (
<RichText
{ …blockProps }
tagName=”p”
onChange={ onChangeContent }
allowedFormats={ [ ‘core/bold’, ‘core/italic’ ] }
value={ attributes.content }
placeholder={ __( ‘写下你的文字…’ ) }
/>
);

让我们逐行注释代码：

tagName — 可编辑 HTML 元素的标签名称
onChange — 元素内容改变时调用的函数
allowedFormats — 一组允许的格式。默认情况下，允许所有格式
value — 可编辑的 HTML 字符串
placeholder — 元素为空时显示的占位符文本

第 3 步：在 block.json 文件中定义必要的属性

属性提供有关块存储的数据的信息，例如丰富的内容、背景颜色、URL 等。

您可以在键/值对中的属性对象中设置任意数量的属性，其中键是属性名称，值是属性定义。

现在打开 block.json 文件并添加以下属性道具：

“attributes”: {
“content”: {
“type”: “string”,
“source”: “html”,
“selector”: “p”
}
},

content 属性允许将用户输入的文本存储在可编辑字段中：

type 表示属性存储的数据类型。除非您定义枚举属性，否则该类型是必需的。
source 定义了如何从帖子内容中提取属性值。在我们的示例中，它是 HTML 内容。请注意，如果您不提供源属性，数据将存储在块分隔符中（阅读更多）。
选择器是一个 HTML 标签或任何其他选择器，例如类名或 id 属性。

我们将向 Edit 函数传递一个属性对象。因此，返回到 edit.js 文件并进行以下更改：

导出默认函数 Edit( { attributes, setAttributes } ) { … }
第 4 步：定义事件处理程序

RichText 元素有一个 onChange 属性，提供了一个在元素内容更改时调用的函数。

让我们定义该函数并查看整个 edit.js 脚本：

从’@wordpress/i18n’导入{__}；
从“@wordpress/block-editor”导入 { useBlockProps, RichText };
导入’./editor.scss’;

导出默认函数 Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps();

const onChangeContent = ( newContent ) => {
setAttributes( { content: newContent } )
}

现在保存文件并在终端窗口中运行 npm run start 。然后，返回到您的 WordPress 仪表板，创建一个新的帖子或页面并添加您的 Affiliate 块：

块编辑器中 RichText 组件的输出。

添加一些文本并切换到代码视图。您的代码应该如下所示：

<!– wp:my-affiliate-plugin/my-affiliate-block –>
<p class=”wp-block-my-affiliate-plugin-my-affiliate-block”>这是我第一个可编辑的古腾堡块🤓 </p>
<!– /wp:my-affiliate-plugin/my-affiliate-block –>

如果您现在保存页面并检查前端结果，您可能会有点失望，因为您的更改不会影响站点。那是因为您必须修改 save.js 文件以在保存帖子时将用户输入存储在数据库中。

第 5 步：保存数据

现在打开 save.js 文件并按如下方式更改脚本：

从’@wordpress/i18n’导入{__}；
从“@wordpress/block-editor”导入 { useBlockProps, RichText };

导出默认函数 save( { attributes } ) {
const blockProps = useBlockProps.save();
return (
<RichText.Content
{ …blockProps }
tagName=”p”
value={ attributes.content }
/>
);
}

这就是我们在这里所做的：

从块编辑器包中导入 RichText 组件。
通过对象参数将多个属性传递给 save 函数（在此示例中，我们仅传递 attributes 属性）
返回 RichText 组件的内容

重要的

每当您更改保存功能时，您必须删除编辑器画布中的任何块实例并再次包含它以查看它是否正常工作。阅读有关块验证的更多信息。

您可以在 Block Editor Handbook 中阅读有关 RichText 组件的更多信息，并在 Github 上找到道具的完整列表。

现在让我们更进一步。在下一部分中，您将学习如何向块工具栏添加控件。

块工具栏包含一组控件，允许用户操作块内容的一部分。对于每个工具栏控件，您将找到一个组件：

核心段落块工具栏。

例如，您可以为块添加文本对齐控件。您需要做的就是从@wordpress/block-editor 包中导入两个组件。

我们将执行与上一个示例相同的步骤：

从 WordPress 包中导入所需的组件
在 JSX 代码中包含相应的元素
在 block.json 文件中定义必要的属性
定义事件处理程序
保存数据

第 1 步：从 @wordpress/block-editor 导入 BlockControls 和 AlignmentControl 组件

要将对齐控件添加到块工具栏，您需要两个组件：

厌倦了没有答案的低于 1 级的 WordPress 托管支持？试试我们世界一流的支持团队！查看我们的计划

BlockControls 呈现控件的动态工具栏（未记录）。
AlignmentControl 呈现一个下拉菜单，显示所选块的对齐选项（阅读更多）

打开edit.js文件，编辑import语句，如下图：

从“@wordpress/block-editor”导入 {
useBlockProps,
RichText,
AlignmentControl,
BlockControls
};
步骤 2：添加 BlockControls 和 AlignmentControl 元素

转到编辑功能并在与 <RichText /> 相同的级别插入 <BlockControls /> 元素。然后在 <BlockControls /> 中添加 <AlignmentControl /> ：

导出默认函数 Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps();
return (
<>
<BlockControls>
<AlignmentControl
value={ attributes.align }
onChange={ onChangeAlign }
/>
</BlockControls>
<RichText
{ …blockProps }
tagName=”p”
onChange={ onChangeContent }
allowedFormats={ [ ‘ core/bold’, ‘core/italic’ ] }
value={ attributes.content }
placeholder={ __( ‘Write your text…’ ) }
style={ { textAlign: attributes.align } }
/>
</>
);
}

在上面的代码中，<> 和 </> 是声明 React 片段的简短语法，这就是我们在 React 中返回多个元素的方式。

在这个例子中，AlignmentControl 有两个属性：

value 提供元素的当前值
onChange 提供了一个事件处理程序以在值更改时运行

我们还为 RichText 元素定义了额外的属性（通过示例查看完整的属性列表）

第 3 步：在 block.json 中定义 align 属性

现在转到 block.json 文件并添加 align 属性：

“对齐”：{
“类型”：“字符串”，
“默认”：“无”
}

返回终端，使用 ^C 停止当前进程并使用 npm run start 再次启动脚本。然后返回块编辑器，刷新页面并选择块。您应该会看到带有对齐控件的块工具栏：

对齐工具栏已成功添加。

现在，如果您尝试使用新的对齐控件格式化块内容，您将看到什么也没有发生。那是因为我们还没有定义事件处理程序。

步骤 4：定义事件处理程序

现在定义 onChangeAlign：

const onChangeAlign = ( newAlign ) => {
setAttributes( {
align: newAlign === undefined ? ‘none’ : newAlign,
} )
}

如果 newAlign 未定义，则我们将 newAlign 设置为 none。否则，我们使用 newAlign。

我们的 edit.js 脚本应该是完整的（现在）：

导出默认函数 Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps();
const onChangeContent = ( newContent ) => {
setAttributes( { content: newContent } )
}
const onChangeAlign = ( newAlign ) => {
setAttributes( {
align: newAlign === undefined ? ‘none’ : newAlign,
} )
}
return (
< >
<BlockControls>
<AlignmentControl
value={ attributes.align }
onChange={ onChangeAlign }
/>
</BlockControls>
<RichText
{ …blockProps }
tagName=”p”
onChange={ onChangeContent }
allowedFormats={ [ ‘core/bold ‘, ‘核心/斜体’

placeholder={ __( ‘写你的文字…’ ) }
style={ { textAlign: attributes.align } }
/>
</>
);
}

现在您可以返回编辑器并对齐块内容。

我们需要修改save函数来在数据库中存储块内容和属性。

第 5 步：保存数据

打开save.js，修改save函数如下：

导出默认函数 save( { attributes } ) {
const blockProps = useBlockProps.save();
return (
<RichText.Content
{ …blockProps }
tagName=”p”
value={ attributes.content }
style={ { textAlign: attributes.align } }
/>
);
}

最后，为了使代码更具可读性，您可以使用解构赋值语法从属性对象中提取各个属性：

导出默认函数 save( { attributes } ) {
const blockProps = useBlockProps.save();
const { 内容，对齐 } = 属性；
return (
<RichText.Content
{ …blockProps }
tagName=”p”
value={ content }
style={ { textAlign: align } }
/>
);
}

保存文件，重新启动进程并以代码编辑器模式返回编辑器。代码应如下所示：

<!– wp:my-affiliate-plugin/my-affiliate-block {“align”:”right”} –>
<p class=”wp-block-my-affiliate-plugin-my-affiliate-block” style=”text-align:right”>这是我第一个可编辑的<strong><em>Gutenberg</em></strong> <em>block</em> 🤓</p>
<!– /wp:我的附属插件/我的附属块 –>
将文本右对齐。

将文本右对齐。

蚂蚁就是这样！您刚刚在块工具栏中添加了一个对齐控件🤓

您可以在块编辑器手册中阅读有关块工具栏控件的更多信息。

您还可以向块设置侧边栏添加控件（甚至为您的应用程序创建一个新的侧边栏）。

API 为此提供了一个 InspectorControls 组件。

块编辑器手册解释了如何使用设置边栏：

设置边栏用于显示不常用的设置或需要更多屏幕空间的设置。设置边栏应仅用于块级设置。

如果您的设置仅影响块内选定的内容（例如：段落内选定文本的“粗体”设置）：请勿将其放置在设置边栏内。即使在 HTML 模式下编辑块时也会显示设置边栏，因此它应该只包含块级设置。

再次：

从 WordPress 包中导入所需的组件
在 JSX 代码中包含相应的元素
在 block.json 文件中定义必要的属性
定义事件处理程序
保存数据

步骤 1. 从@wordpress/block-editor 导入 InspectorControls 和 PanelColorSettings 组件

您可以添加多个控件以允许用户自定义块的特定方面。例如，您可以提供一个颜色控制面板。为此，您需要从块编辑器模块中导入 InspectorControls 和 PanelColorSettings 组件：

import {
useBlockProps,
RichText,
AlignmentControl,
BlockControls,
InspectorControls,
PanelColorSettings
} from ‘@wordpress/block-editor’;
第 2 步：将相应的元素包含到您的 JSX 代码中

现在您可以将相应的元素添加到 Edit 函数返回的 JSX 中：

导出默认函数 Edit( { attributes, setAttributes } ) {
const blockProps = useBlockProps();
const onChangeContent = ( newContent ) => {
setAttributes( { content: newContent } )
}
const onChangeAlign = ( newAlign ) => {
setAttributes( {
align: newAlign === undefined ? ‘none’ : newAlign,
} )
}
return (
< >
<InspectorControls>
<PanelColorSettings
title={ __( ‘颜色设置’, ‘my-affiliate-block’ ) }
initialOpen={ false }
colorSettings={ [
{
value: textColor,
onChange: onChangeTextColor,
label: __( ‘文本颜色’, ‘my-affiliate-block’ ),
},
{
文本颜色 } } /> </> ); }

请注意，我们还更新了 RichText 元素的 style 属性：

<RichText
{ …blockProps }
tagName=”p”
onChange={ onChangeContent }
allowedFormats={ [ ‘core/bold’, ‘core/italic’ ] }
value={ content }
placeholder={ __( ‘写你的文字。 ..’, ‘my-affiliate-block’ ) }
style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
/>
第三步：在block.json中定义必要的属性

现在在 block.json 文件中定义 backgroundColor 和 textColor 属性：

“attributes”: {
“content”: {
“type”: “string”,
“source”: “html”,
“selector”: “p”
},
“align”: {
“type”: “string”,
“default “: “none”
},
“backgroundColor”: {
“type”: “string”
},
“textColor”: {
“type”: “string”
}
},
第 4 步：定义事件处理程序

现在您需要定义两个函数来更新用户输入的 backgroundColor 和 textColor：

const onChangeBackgroundColor = ( newBackgroundColor ) => {
setAttributes( { backgroundColor: newBackgroundColor } )
}
const onChangeTextColor = ( newTextColor ) => {
setAttributes( { textColor: newTextColor } )
}
步骤5：保存数据

最后一步：打开 save.js 文件并更改脚本如下：

导出默认函数 save( { attributes } ) {
const blockProps = useBlockProps.save();
const { 内容，对齐，backgroundColor，textColor } = 属性；
return (
<RichText.Content
{ …blockProps }
tagName=”p”
value={ content }
style={ { textAlign: align, backgroundColor: backgroundColor, color: textColor } }
/>
);
}

现在停止进程 (^C) 并再次运行 npm run start。刷新页面，删除块的任何实例并将其再次添加到您的帖子中：

带有颜色设置面板的自定义块。

进行更改，保存帖子，然后在前端查看。您在块编辑器中所做的更改应反映在前端站点上。

添加和自定义外部链接

在本节中，您将向块类型添加新组件：

一个 ExternalLink 组件，允许用户向 Affiliate 块添加可自定义的链接
几个侧边栏控件允许用户自定义链接设置

步骤 1. 从 @wordpress/components 导入组件

现在您需要从@wordpress/components 导入几个组件。打开您的 edit.js 文件并添加以下导入语句：

import {
TextControl,
PanelBody,
PanelRow,
ToggleControl,
ExternalLink
} from ‘@wordpress/components’;

PanelBody 向设置侧栏添加了一个可折叠容器。
PaneRow 为侧边栏控件生成通用容器。
TextControl 提供了一个文本输入控件。
ToggleControl 提供了一个开关，使用户能够启用/禁用特定选项
ExternalLink 是一个简单的添加外部链接的组件。

步骤 2. 在 JSX 代码中包含相应的元素

您将首先在 div 容器中添加与 RichText 相同级别的 ExternalLink 元素：

<div { …blockProps }>
<RichText
…
/>
<ExternalLink
href={affiliateLink }
className=”affiliate-button”
rel={ hasLinkNofollow ? “nofollow” : “” }
>
{ linkLabel }
</ExternalLink>

</div>

ExternalLink 组件没有文档化，因此我们参考组件本身来获取可用属性列表。这里我们使用了 href、className 和 rel 属性。

默认情况下，rel 属性值设置为 noopener noreferrer。当切换控件打开时，我们的代码会将 nofollow 关键字添加到结果 a 标签的 rel 属性中。

现在您可以将链接设置添加到块侧边栏。

首先，您将在与 PanelColorSettings 相同级别的 InspectorControls 中添加一个 PanelBody 元素：

这是我们正在做的事情：

title 属性提供面板标题。
initialOpen 设置面板最初是否打开。

接下来，我们将在 PanelBody 中添加两个 PanelRow 元素，并在每个 PanelRow 中添加一个 TextControl 元素：

上面的代码现在看起来应该很简单了。这两个文本控件允许用户设置链接标签和 URL。

我们还将添加一个带有 ToggleControl 的额外 PanelRow 以打开/关闭特定选项，例如是否包含属性：

<PanelRow>
<fieldset>
<ToggleControl
label=”Add rel = nofollow”
help={
hasLinkNofollow
? “有rel nofollow。”
：’没有rel nofollow。
}
checked={ hasLinkNofollow }
onChange={ toggleNofollow }
/>
</fieldset>
</PanelRow>
第三步：在block.json中定义必要的属性

现在在 block.json 文件中定义affiliateLink、linkLabel 和hasLinkNofollow 属性：

“affiliateLink”: {
“type”: “string”,
“default”: “”
},
“linkLabel”: {
“type”: “string”,
“default”: “检查出来！”
},
“hasLinkNofollow”: {
“type”: “boolean”,
“default”: false
}

这里没有更多要添加的了！让我们继续定义事件处理函数。

步骤 4：定义事件处理程序

回到 edit.js 文件并添加以下函数：

const onChangeAffiliateLink = ( newAffiliateLink ) => {
setAttributes( {affiliateLink: newAffiliateLink === undefined ? ” : newAffiliateLink } )
}

const onChangeLinkLabel = ( newLinkLabel ) => {
setAttributes( { linkLabel: newLinkLabel === undefined ? ” : newLinkLabel } )
}

const toggleNofollow = () => {
setAttributes( { hasLinkNofollow: !hasLinkNofollow } )
}

这些函数根据用户输入更新相应的属性值。

第 5 步：保存数据

最后，我们必须更新 save.js 中的保存函数：

导出默认函数保存（{属性}）{

const { 对齐、内容、背景颜色、文本颜色、affiliateLink、linkLabel、hasLinkNofollow } = 属性；

const blockProps = useBlockProps.save();

return (
<div { …blockProps }>
<RichText.Content
tagName=”p”
value={ content }
style={ { backgroundColor: backgroundColor, color: textColor } }
/>
<p>
<a
href={affiliateLink }
className=”affiliate-button”
rel={ hasLinkNofollow ? “nofollow” : “noopener noreferrer” }
>
{ linkLabel }
</a>
</p>
</div>
);
}

请注意，这里我们使用了常规的 a 元素而不是 ExternalLink：

会员阻止链接设置。

现在保存数据并重新启动您的环境。

添加多个块样式

在上一节中，您学习了如何添加块工具栏控件以允许用户对齐用户输入。我们可以向块工具栏添加更多样式控件，但我们也可以提供一组预定义的块样式，用户只需单击一下即可从中进行选择。

为此，我们将使用 Block API 的一个有用功能：Block Styles。

您需要做的就是定义 block.json 样式属性并在样式表中声明相应的样式。

例如，您可以添加以下样式数组：

“styles”: [
{
“name”: “default”,
“label”: “Default”,
“isDefault”: true
},
{
“name”: “border”,
“label”: “Border”
}
],

有了这个，您刚刚添加了一个默认样式和一个称为边框的附加样式。现在回到块编辑器：

两种预定义的块样式。

通过单击块切换器，然后在块设置侧栏中查找样式面板，用户可以使用这些样式。

选择一种样式并检查应用于 p 元素的类。右键单击块并检查。添加了一个新类，其名称结构如下：

is-style-{style-name}

如果您选中了“Border”样式，那么将在 p 元素中添加一个 is-style-border 类。如果您选中“默认”样式，则会添加一个 is-style-default 类。

现在你只需要声明 CSS 属性。打开 editor.scss 文件并将当前样式替换为以下内容：

.wp-block-my-affiliate-plugin-my-affiliate-block {
padding: 2px;
&.is-style-default{
边框：0;
}
&.is-style-border{
边框：1px 实心 #000;
}
}

现在你可以用 style.scss 做同样的事情：

.wp-block-my-affiliate-plugin-my-affiliate-block {
&.is-style-default{
边框：0;
}
&.is-style-border{
边框：1px 实心 #000;
}
}

停止进程 (^C) 并再次运行 npm run start。

就是这样！刷新页面，享受新的块样式的乐趣：

附属块样式。

使用 InnerBlocks 组件嵌套古腾堡块

虽然功能齐全，但我们的会员块仍然不是很吸引人。为了让它更吸引观众，我们可以添加一张图片。

这可能会给我们的块增加一层复杂性，但幸运的是，您不需要重新发明轮子，因为 Gutenberg 提供了一个特定的组件，您可以使用它来创建嵌套块的结构。

InnerBlocks 组件定义如下：

InnerBlocks 导出一对组件，可用于块实现以启用嵌套块内容。

首先，您需要在 src 文件夹中创建一个新的 .js 文件。在我们的示例中，我们将此文件称为 container.js。

现在您需要将新资源导入 index.js 文件：

导入’./容器’;

回到 container.js 并导入必要的组件：

从“@wordpress/blocks”导入 { registerBlockType };
从“@wordpress/i18n”导入{__}；从“@wordpress/block-editor”
导入 {
useBlockProps,
InnerBlocks
};

下一步是定义一个模板，提供放置块的结构。在以下示例中，我们定义了一个模板，该模板由两列组成，其中包含一个核心 Image 块和我们的自定义 Affiliate 块：

const TEMPLATE = [ [ ‘core/columns’, { backgroundColor: ‘yellow’, verticalAlignment: ‘center’ }, [
[ ‘core/column’, { templateLock: ‘all’ }, [
[ ‘core/image’ ],
] ],
[ ‘core/column’, { templateLock: ‘all’ }, [
[ ‘my-affiliate-plugin/my-affiliate-block’, { placeholder: ‘输入侧边内容…’ } ],
] ] ,
] ] ];

该模板被构造为一个块类型数组（块名称和可选属性）。

在上面的代码中，我们使用了几个属性来配置 Columns 和 Column 块。具体来说， templateLock: ‘all’ 属性锁定 Column 块，以便用户不会添加、重新排序或删除现有块。templateLock 可以采用以下值之一：

all — InnerBlocks 被锁定，不能添加、重新排序或删除任何块。
insert — 块只能重新排序或删除。
false — 模板未锁定。

然后将模板分配给 InnerBlocks 元素：

为了防止任何兼容性问题，我们还在 InnerBlocks 组件中添加了 templateLock 属性（另请参阅问题 #17262 和 pull #26128）。

这是我们最终的 container.js 文件：

从“@wordpress/blocks”导入 { registerBlockType };
从“@wordpress/i18n”导入{__}；
从“@wordpress/block-editor”导入 { useBlockProps, InnerBlocks };

registerBlockType(‘my-affiliate-plugin/my-affiliate-container-block’, {
title: __( ‘Container’, ‘my-affiliate-block’ ),
category: ‘design’,

编辑（{类名}）{

return(
<div className={ className }>
<InnerBlocks
template={ TEMPLATE }
templateLock=”all”
/>
</div>
)
},

save() {
const blockProps = useBlockProps.save();
return(
<div { …blockProps }>
<InnerBlocks.Content />
</div>
)
},
});
编辑器中嵌套的 Affiliate 块。

编辑器中嵌套的 Affiliate 块。

其他改进

我们的块功能齐全，但我们可以通过一些小的更改对其进行改进。

我们将 backgroundColor 属性分配给 RichText 组件生成的段落。但是，我们可能更喜欢将背景颜色分配给容器 div：

因此，更改edit.js 文件和save.js div，如下所示：

这将允许用户更改整个块的背景。

另一方面，更相关的更改涉及 useBlockProps 方法。在原始代码中，我们定义了常量 blockProps 如下：

const blockProps = useBlockProps();

但是我们可以使用 useBlockProps 更有效地传递一组属性。例如，我们可以从 classnames 模块导入类名并相应地设置包装类名。

在以下示例中，我们根据 align 属性 (edit.js) 的值分配一个类名：

从 ‘classnames’ 导入类名；

…

导出默认函数 Edit( { attributes, setAttributes } ) {
…
const blockProps = useBlockProps( {
className: classnames( {
[ `has-text-align-${ align }` ]: align,
} )
} );
…
}

我们将在 save.js 文件中做同样的改变：

从 ‘classnames’ 导入类名；

…

导出默认函数 save( { attributes } ) {
…
const blockProps = useBlockProps.save({
className: classnames( {
[ `has-text-align-${ align }` ]: align,
} )
});
…
}

这是一个包装！您现在可以为生产运行构建。

如果您正在寻找有关古腾堡块开发入门的深入指南，那么这个庞大的指南适合您。立即查看并开始构建您的古腾堡积木！👷‍♀️🧱点击推文
总结

我们到了，结束了这段不可思议的旅程！我们从配置开发环境开始，最终创建了一个完整的块类型。

正如我们在介绍中提到的，Node.js、Webpack、Babel 和 React 的扎实知识对于创建高级 Gutenberg 块和将自己定位为专业的 Gutenberg 开发人员至关重要。

但是，您无需具备 React 经验即可开始享受块开发的乐趣。块开发可以为您提供动力和目标，以在古腾堡块背后的技术中获得越来越广泛的技能。

因此，本指南远未完成。它只是对各种主题的介绍，可帮助您开始构建您的第一个古腾堡积木。

因此，我们建议您通过仔细阅读在线文档和指南来加深您的知识。在众多可用资源中，我们推荐以下资源：

官方为初学者创建块教程
中级开发者的官方块教程
动态块
元盒
为您的插件创建侧边栏

如果您刚刚开始 WordPress 开发，您可能想了解前端开发的基本概念。以下是可以帮助您入门的快速资源列表：

如何在本地安装 WordPress（免费电子书）
托管 WordPress 托管的真正价值（免费电子书）
什么是 JavaScript？
HTML 与 HTML5
如何在 WordPress 中编辑 CSS
什么是 PHP？
WordPress 钩子训练营：如何使用操作、过滤器和自定义钩子

请记住，本指南示例的完整代码可在 Gist 上找到。

现在轮到你了：你开发过古腾堡积木吗？到目前为止，您遇到的主要困难是什么？在评论中让我们知道您的体验！

通过以下方式节省时间、成本并最大限度地提高站点性能：

来自 WordPress 托管专家的即时帮助，24/7。
Cloudflare 企业集成。
全球受众覆盖全球 28 个数据中心。
使用我们内置的应用程序性能监控进行优化。

所有这些以及更多，在一个没有长期合同、协助迁移和 30 天退款保证的计划中。查看我们的计划或与销售人员交谈以找到适合您的计划。

构建自定义古腾堡积木：最终积木开发教程

1. 安装 Node.js 和 npm

信息

2. 设置您的开发环境

重要的

设置块插件

信息

仔细看看创建块开发工具

插件文件

package.json 文件

block.json 文件

源文件夹

node_modules 和 build 文件夹

信息

如何设置 Starter Block 插件

信息

工作中的 block.json

想知道我们是如何将流量增加超过 1000% 的吗？

使用内置组件：RichText 组件

信息

重要的

自定义块设置侧栏

添加和自定义外部链接

添加多个块样式

使用 InnerBlocks 组件嵌套古腾堡块

其他改进

如何在没有插件的情况下在 WordPress 中导入 CSV 文件

如何将 WordPress 置于维护模式（安全且简单的方法）

如何向 WordPress 帖子添加多媒体

谷歌域名与WordPress集成：建立您的专业网站

了解WordPress社区：专访揭示内部运作

Azure 提供的 WordPress 免费游乐场

构建自定义古腾堡积木：最终积木开发教程

1. 安装 Node.js 和 npm

信息

2. 设置您的开发环境

重要的

设置块插件

信息

仔细看看创建块开发工具

插件文件

package.json 文件

block.json 文件

源文件夹

node_modules 和 build 文件夹

信息

如何设置 Starter Block 插件

信息

工作中的 block.json

想知道我们是如何将流量增加超过 1000% 的吗？

使用内置组件：RichText 组件

信息

重要的

向块工具栏添加控件

自定义块设置侧栏

添加和自定义外部链接

添加多个块样式

使用 InnerBlocks 组件嵌套古腾堡块

其他改进

相关文章