开始使用WordPress块开发-css教程-PHP中文网

首页

web前端

css教程

开始使用WordPress块开发

Christopher Nolan

Mar 10, 2025 am 11:11 AM

Getting Started With WordPress Block Development

WordPress开发目前正经历转型期，无论您是WordPress新手还是资深开发者，“全站编辑”（FSE）功能的引入，包括区块编辑器（WordPress 5.0）和站点编辑器（WordPress 5.9），都颠覆了我们构建WordPress主题和插件的传统方式。

尽管我们第一次接触区块编辑器已经五年了，但它的开发仍然充满挑战，因为文档要么缺失，要么过时。这更多地反映了FSE功能快速迭代的现状。

例如，2018年，CSS-tricks上曾发表过一个关于Gutenberg开发入门的系列文章。但时过境迁，虽然那种开发方式仍然有效，但已不再推荐（此外，它所基于的create-guten-block项目也不再维护）。

本文旨在帮助您开始WordPress区块开发，并遵循当前的方法。当然，本文发布后，情况可能会发生变化。但我将尝试关注其核心思想，因为即使工具会随着时间推移而发展，核心概念很可能保持不变。

WordPress区块究竟是什么？

首先，让我们澄清一些术语，例如“区块”。在WordPress 5.0之前的这些功能的所有开发都使用代号“Gutenberg”（印刷术的发明者）。

从那时起，“Gutenberg”已被用来描述与区块相关的一切，包括区块编辑器和站点编辑器，因此它变得复杂到一些人讨厌这个名字的程度。最重要的是，还有一个Gutenberg插件用于测试实验性功能，以供将来可能包含。如果您认为将所有这些称为“全站编辑”可以解决问题，那么也存在一些担忧。

因此，在本文中，当我们提到“区块”时，指的是在WordPress区块编辑器中创建内容的组件。区块被插入页面或文章中，并为特定类型的内容提供结构。WordPress自带了一些用于常见内容类型的“核心”区块，例如段落、列表、图像、视频和音频等等。

除了这些核心区块外，我们还可以创建自定义区块。这就是WordPress区块开发的重点（还可以过滤核心区块以修改其功能，但您可能暂时不需要）。

区块的作用

在我们深入创建区块之前，我们必须首先了解区块的内部工作原理。这绝对可以节省我们以后很多麻烦。

我喜欢将区块抽象地理解为：一个具有某些属性（称为属性）的实体，代表某些内容。我知道这听起来很模糊，但请耐心听我解释。区块基本上以两种方式表现出来：作为区块编辑器中的图形界面，或作为数据库中的数据块。

当您打开WordPress区块编辑器并插入一个区块（例如，Pullquote区块）时，您会得到一个不错的界面。您可以点击该界面并编辑引用的文本。区块编辑器UI右侧的“设置”面板提供用于调整文本和设置区块外观的选项。

当您完成创建精美的引用并点击“发布”时，整篇文章都会存储在数据库的wp_posts表中。由于Gutenberg，这没有什么新意。这就是事情一直以来的工作方式——WordPress将文章内容存储在数据库中的指定表中。但新的是Pullquote区块的表示是存储在wp_posts表的post_content字段中的内容的一部分。

这种表示是什么样的？让我们来看看：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

看起来像普通的HTML，对吧？！用技术术语来说，这就是“序列化”的区块。请注意HTML注释中的JSON数据，“textAlign”：“right”。这是一个属性——与区块相关的属性。

假设您关闭了区块编辑器，然后一段时间后再次打开它。区块编辑器将检索相关post_content字段中的内容。然后，编辑器解析检索到的内容，并在遇到以下内容时：

<code>...</code>

它会自言自语：

好吧，这看起来像一个Pullquote区块。嗯……它也有一个属性……我确实有一个JavaScript文件，它告诉我如何根据其属性在编辑器中构造Pullquote区块的图形界面。我现在应该这样做，以便以其全部荣耀呈现此区块。

作为区块开发者，您的工作是：

告诉WordPress您要注册特定类型的区块，以及相关细节。
向区块编辑器提供JavaScript文件，这将帮助它在编辑器中呈现区块，同时将其“序列化”以将其保存到数据库中。
提供区块正常运行所需的任何其他资源，例如样式和字体。

需要注意的是，所有这些从序列化数据到图形界面的转换——反之亦然——只发生在区块编辑器中。在前端，内容的显示方式与存储方式完全相同。因此，从某种意义上说，区块是一种将数据放入数据库的巧妙方法。

希望这能使您更清楚地了解区块的工作原理。

区块只是插件

区块只是插件。好吧，从技术上讲，您可以将区块放在主题中，也可以将多个区块放在一个插件中。但是，通常情况下，如果您想制作一个区块，您将要制作一个插件。因此，如果您曾经创建过WordPress插件，那么您已经部分掌握了制作WordPress区块的方法。

但是，让我们假设您从未设置过WordPress插件，更不用说区块了。你甚至从哪里开始？

设置区块

我们已经介绍了什么是区块。让我们开始设置来制作一个。

确保已安装Node

这将使您可以访问npm和npx命令，其中npm安装区块的依赖项并帮助编译内容，而npx在不安装软件包的情况下运行软件包上的命令。如果您使用的是macOS，您可能已经安装了Node，并且可以使用nvm更新版本。如果您使用的是Windows，则需要下载并安装Node。

创建项目文件夹

现在，您可能会遇到其他教程，它们直接跳转到命令行并指示您安装名为@wordpress/create-block的软件包。此软件包非常棒，因为它会生成一个完整的项目文件夹，其中包含开始开发所需的所有依赖项和工具。

我个人在设置自己的区块时会采用这种方法，但请暂时容忍我一下，因为我想消除它引入的主观内容，并仅关注基本开发环境的必需部分，以便理解。

这些是我想特别指出的文件：

readme.txt：这有点像插件目录的正面，通常用于描述插件并提供有关用法和安装的更多详细信息。如果您将区块提交到WordPress插件目录，则此文件有助于填充插件页面。如果您计划为区块插件创建GitHub存储库，那么您也可以考虑使用包含相同信息的README.md文件，以便它在那里很好地显示。
package.json：这定义了开发所需的Node软件包。我们将在安装时打开它。在经典的WordPress插件开发中，您可能习惯于使用Composer和composer.json文件。这是它的等效项。
plugin.php：这是主要的插件文件，是的，它是经典的PHP！我们将在这里放置插件标题和元数据，并使用它来注册插件。

除了这些文件外，还有一个src目录，它应该包含区块的源代码。

拥有这些文件和src目录就足以开始了。在那组中，请注意我们实际上只需要一个文件（plugin.php）来制作插件。其余的要么提供信息，要么用于管理开发环境。

前面提到的@wordpress/create-block软件包为我们搭建了这些文件（以及更多）。您可以将其视为自动化工具，而不是必需品。无论如何，它确实使工作更容易，因此您可以通过运行以下命令来自由地使用它来搭建区块：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

安装区块依赖项

假设您已准备好上一节中提到的三个文件，现在该安装依赖项了。首先，我们需要指定我们将需要的依赖项。我们通过编辑package.json来做到这一点。使用@wordpress/create-block实用程序时，会为我们生成以下内容（添加了注释；JSON不支持注释，因此如果您复制代码，请删除注释）：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

查看无注释版本

```json { "name": "block-example", "version": "0.1.0", "description": "Example block scaffolded with Create Block tool.", "author": "The WordPress Contributors", "license": "GPL-2.0-or-later", "main": "build/index.js", "scripts": { "build": "wp-scripts build", "format": "wp-scripts format", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "packages-update": "wp-scripts packages-update", "plugin-zip": "wp-scripts plugin-zip", "start": "wp-scripts start" }, "devDependencies": { "@wordpress/scripts": "^24.1.0" } }

<code>...</code>

现在package.json已设置完毕，我们应该能够通过在命令行中导航到项目文件夹并运行npm install来安装所有这些依赖项。

添加插件标题

如果您来自经典的WordPress插件开发，那么您可能知道所有插件在主插件文件中都有一块信息，这有助于WordPress识别插件并在WordPress管理面板的“插件”屏幕上显示有关它的信息。

以下是@wordpress/create-block为我生成的，用于一个创造性地称为“Hello World”的插件：

npx @wordpress/create-block

这在主插件文件中，您可以根据需要随意命名。您可以将其命名为index.php或plugin.php之类的通用名称。create-block包会自动将其命名为您在安装时提供的项目名称。由于我将此示例称为“Block Example”，因此该包为我们提供了一个block-example.php文件，其中包含所有这些内容。

您需要更改一些详细信息，例如将自己设为作者等等。并非所有这些都是必要的。如果我从“头”开始，那么它可能更接近于此：

{
  // 定义项目名称
  "name": "block-example",
  // 使用语义版本控制设置项目版本号
  "version": "0.1.0",
  // 项目的简短描述
  "description": "Example block scaffolded with Create Block tool.",
  // 您可以将其替换为您自己
  "author": "The WordPress Contributors",
  // 标准许可信息
  "license": "GPL-2.0-or-later",
  // 定义主JavaScript文件
  "main": "build/index.js",
  // 我们在开发过程中构建和编译插件所需的一切
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // 定义使用脚本包的哪个版本（撰写本文时为24.1.0）
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

我不会详细介绍每一行的确切用途，因为这在WordPress插件手册中已经是一个完善的模式了。

文件结构

我们已经查看了区块所需的文件。但是，如果您使用的是@wordpress/create-block，您将在项目文件夹中看到许多其他文件。

以下是目前包含的内容：

<code>
这里的@wordpress/scripts包是主要的依赖项。如您所见，它是一个devDependency，这意味着它有助于开发。如何？它公开了wp-scripts二进制文件，我们可以使用它来编译我们的代码，从src目录到build目录，等等。

WordPress维护了许多其他软件包，用于各种目的。例如，@wordpress/components软件包为WordPress区块编辑器提供了一些预制UI组件，可用于为区块创建一致的用户体验，并符合WordPress设计标准。

您实际上*不需要*安装这些软件包，即使您想使用它们也是如此。这是因为这些@wordpress依赖项不会与您的区块代码捆绑在一起。相反，任何引用实用程序软件包代码的导入语句——例如@wordpress/components——都用于在编译期间构造“资产”文件。此外，这些导入语句被转换为将导入映射到全局对象的属性的语句。例如，import { \_\_ } from "@wordpress/i18n"被转换为const \_\_ = window.wp.i18n.\_\_的缩小版本。（window.wp.i18n是一个保证在全局范围内可用的对象，一旦相应的i18n软件包文件被排队）。

在插件文件中注册区块期间，隐式使用“资产”文件来告诉WordPress区块的软件包依赖项。这些依赖项会自动排队。所有这些都在幕后完成，前提是您使用的是scripts软件包。也就是说，您仍然可以选择在package.json文件中本地安装依赖项以进行代码完成和参数信息：

```json
// etc.
"devDependencies": {
  "@wordpress/scripts": "^24.1.0"
},
"dependencies": {
  "@wordpress/components": "^19.17.0"
}</code>

哇，好多！让我们指出新的内容：

build/：此文件夹在处理生产用途的文件时接收已编译的资产。
node_modules：此文件夹保存我们运行npm install时安装的所有开发依赖项。
src/：此文件夹保存插件的源代码，这些源代码将被编译并发送到build目录。我们稍后将查看其中的每个文件。
.editorconfig：这包含用于调整代码编辑器以实现代码一致性的配置。
.gitignore：这是一个标准的存储库文件，用于识别应从版本控制跟踪中排除的本地文件。您的node_modules绝对应该包含在此处。
package-lock.json：这是一个自动生成的文件，用于跟踪使用npm install安装的所需软件包的更新。

区块元数据

我想与您一起深入研究src目录，但首先将重点放在其中的一个文件上：block.json。如果您使用的是create-block，它已经为您准备好了；如果没有，请继续创建它。WordPress正在大力推动将其作为标准的规范方法来注册区块，方法是提供元数据，这些元数据为WordPress提供上下文，以便同时识别区块并在区块编辑器中呈现它。

以下是@wordpress/create-block为我生成的内容：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

实际上，我们可以在此处包含许多不同的信息，但实际上只需要name和title。一个超级精简的版本可能如下所示：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

$schema定义用于验证文件内容的模式格式。听起来像是一个必需的东西，但它完全是可选的，因为它允许支持的代码编辑器验证语法并提供其他额外功能，例如工具提示提示和自动完成。
apiVersion指的是插件使用的Block API的哪个版本。今天，版本2是最新版本。
name是一个必需的唯一字符串，有助于识别插件。请注意，我已经在前面添加了css-tricks/，我将其用作命名空间，以帮助避免与可能具有相同名称的其他插件发生冲突。您可以选择使用您的姓名首字母缩写之类的东西（例如as/block-example）。
version是WordPress建议用作发布新版本时的缓存清除机制。
title是另一个必需的字段，它设置在显示插件的任何位置使用的名称。
category将区块与其他区块分组，并将其一起显示在区块编辑器中。当前存在的类别包括文本、媒体、设计、小部件、主题和嵌入，您甚至可以创建自定义类别。
icon允许您从Dashicons库中选择一些内容，以便在区块编辑器中以可视方式表示您的区块。我使用format-quote图标，因为我们在这个示例中正在制作我们自己的pullquote之类的东西。我们可以利用现有的图标而不是必须创建我们自己的图标，这很好，尽管这当然也是可能的。
editorScript是主JavaScript文件index.js所在的位置。

注册区块

在我们进入实际代码之前，还有一件事，那就是注册插件。我们刚刚设置了所有这些元数据，我们需要一种方法让WordPress使用它。这样，WordPress就知道在哪里可以找到所有插件资产，以便可以将它们排队用于区块编辑器。

注册区块是一个两步过程。我们需要在PHP和JavaScript中注册它。对于PHP方面，打开主插件文件（在本例中为block-example.php），并在插件标题之后添加以下内容：

<code>...</code>

这就是create-block实用程序为我生成的内容，这就是为什么函数的命名方式如此的原因。我们可以使用不同的名称。关键是避免与其他插件冲突，因此最好在此处使用您的命名空间以使其尽可能唯一：

npx @wordpress/create-block

如果包含所有区块元数据的block.json位于src中，为什么我们要指向build目录？这是因为我们的代码仍然需要编译。scripts软件包处理src目录中文件的代码并将生产中使用的已编译文件放置在build目录中，同时复制block.json文件。

好了，让我们转到注册区块的JavaScript方面。打开src/index.js并确保它如下所示：

{
  // 定义项目名称
  "name": "block-example",
  // 使用语义版本控制设置项目版本号
  "version": "0.1.0",
  // 项目的简短描述
  "description": "Example block scaffolded with Create Block tool.",
  // 您可以将其替换为您自己
  "author": "The WordPress Contributors",
  // 标准许可信息
  "license": "GPL-2.0-or-later",
  // 定义主JavaScript文件
  "main": "build/index.js",
  // 我们在开发过程中构建和编译插件所需的一切
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // 定义使用脚本包的哪个版本（撰写本文时为24.1.0）
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

我们正在进入React和JSX领域！这告诉WordPress：

从@wordpress/blocks软件包导入registerBlockType模块。
从block.json导入元数据。
从其相应的文件导入Edit和Save组件。我们稍后将向这些文件中添加代码。
注册区块，并使用Edit和Save组件来呈现区块并将内容保存到数据库中。

Edit和save函数是怎么回事？WordPress区块开发的细微之处之一是区分“后端”和“前端”，这些函数用于在这些上下文中呈现区块的内容，其中edit处理后端呈现，save将内容从区块编辑器写入数据库以在网站的前端呈现内容。

快速测试

我们可以快速操作一下，看看我们的区块是否在区块编辑器中工作并在前端呈现。让我们再次打开index.js，并使用edit和save函数返回一些基本内容，以说明它们的工作方式：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

这基本上是我们之前代码的精简版本，只是我们直接指向block.json中的元数据来获取区块名称，并且省略了Edit和Save组件，因为我们直接从此处运行函数。

我们可以通过在命令行中运行npm run build来编译它。之后，我们可以在区块编辑器中访问名为“Block Example”的区块：

如果我们将区块放入内容区域，我们将获得从edit函数返回的消息：

如果我们保存并发布文章，则在前端查看时，我们应该获得从save函数返回的消息：

创建区块

看起来一切正常！现在我们已经确认一切正常，我们可以恢复到测试之前的index.js中的内容：

<code>...</code>

请注意，edit和save函数与src目录中@wordpress/create-block为我们生成的两个现有文件相关联，并且包含我们在每个文件中需要的其他导入。更重要的是，这些文件建立了包含区块标记的Edit和Save组件。

后端标记（src/edit.js）

npx @wordpress/create-block

看看我们做了什么？我们正在从@wordpress/block-editor软件包导入props，这允许我们生成稍后可以用于样式的类。我们还导入了__国际化函数，用于处理翻译。

前端标记（src/save.js）

这将创建一个Save组件，我们将使用与src/edit.js几乎相同的内容，但文本略有不同：

{
  // 定义项目名称
  "name": "block-example",
  // 使用语义版本控制设置项目版本号
  "version": "0.1.0",
  // 项目的简短描述
  "description": "Example block scaffolded with Create Block tool.",
  // 您可以将其替换为您自己
  "author": "The WordPress Contributors",
  // 标准许可信息
  "license": "GPL-2.0-or-later",
  // 定义主JavaScript文件
  "main": "build/index.js",
  // 我们在开发过程中构建和编译插件所需的一切
  "scripts": {
    "build": "wp-scripts build",
    "format": "wp-scripts format",
    "lint:css": "wp-scripts lint-style",
    "lint:js": "wp-scripts lint-js",
    "packages-update": "wp-scripts packages-update",
    "plugin-zip": "wp-scripts plugin-zip",
    "start": "wp-scripts start"
  },
  // 定义使用脚本包的哪个版本（撰写本文时为24.1.0）
  // https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/
  "devDependencies": {
    "@wordpress/scripts": "^24.1.0"
  }
}

同样，我们得到了一个可以在CSS中使用的不错的类：

样式区块

我们刚刚介绍了如何使用区块属性来创建类。您正在CSS相关的网站上阅读这篇文章，因此我觉得如果我们没有特别介绍如何编写区块样式，我会错过一些东西。

区分前端和后端样式

如果您查看src目录中的block.json，您会发现两个与样式相关的字段：

editorStyle提供应用于后端的样式的路径。
style是应用于前端和后端的共享样式的路径。

Kev Quirk有一篇详细的文章展示了他使后端编辑器看起来像前端UI的方法。

回想一下，@wordpress/scripts软件包在处理/src目录中的代码并将已编译的资产放置在/build目录中时，会复制block.json文件。用于注册区块的是build/block.json文件。这意味着我们在src/block.json中提供的任何路径都应相对于build/block.json编写。

使用Sass

我们可以将几个CSS文件放入build目录中，在src/block.json中引用路径，运行build，然后就完成了。但这并没有充分利用@wordpress/scripts编译过程的功能，该过程能够将Sass编译成CSS。相反，我们将样式文件放在src目录中，并在JavaScript中导入它们。

这样做时，我们需要注意@wordpress/scripts如何处理样式：

导入到JavaScript代码中的名为style.css或style.scss或style.sass的文件将编译为style-index.css。
所有其他样式文件都将被编译并捆绑到index.css中。

@wordpress/scripts软件包使用webpack进行捆绑，并使用PostCSS插件进行样式处理。PostCSS可以使用其他插件进行扩展。scripts软件包使用Sass、SCSS和Autoprefixer的插件，所有这些插件都无需安装其他软件包即可使用。

事实上，当您使用@wordpress/create-block启动初始区块时，您可以很好地开始使用SCSS文件，您可以使用这些文件快速上手：

editor.scss包含应用于后端编辑器的所有样式。
style.scss包含前端和后端共享的所有样式。

现在让我们通过编写一些我们将编译成区块CSS的Sass来实际操作一下。尽管这些示例不会非常Sass化，但我仍然将它们写入SCSS文件以演示编译过程。

前端和后端样式

好的，让我们从应用于前端和后端的样式开始。首先，我们需要创建src/style.scss（如果您使用的是@wordpress/create-block，它已经存在），并确保我们导入它，我们可以在index.js中执行此操作：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

打开src/style.scss并在其中使用从区块属性为我们生成的类放入一些基本样式：

<code>...</code>

现在就这些！当我们运行build时，这将编译成build/style.css，并由区块编辑器和前端引用。

后端样式

您可能需要编写特定于区块编辑器的样式。为此，请创建src/editor.scss（同样，@wordpress/create-block为您执行此操作），并在其中放入一些样式：

npx @wordpress/create-block

然后在edit.js中导入它，该文件包含我们的Edit组件（我们可以在任何地方导入它，但由于这些样式是用于编辑器的，因此在此处导入组件更合乎逻辑）：

<blockquote>
    <p>It is not an exaggeration to say that peas can be described as nothing less than perfect spheres of joy.</p>
    <cite>The Encyclopedia of world peas</cite>
  </blockquote>

现在，当我们运行npm run build时，样式将应用于这两种上下文中的区块：