如何使用 @wordpress/scripts 向 Gutenberg 编辑器添加按钮

大约一年半前，Antonio 写了这篇博文，解释了我们在将插件适应新的 WordPress 块编辑器时遇到的困难之一。 他的教程的结果是这样的：

幸运或不幸的是，古腾堡在这一年半中发生了很大的变化。 开发堆栈一直在扩展和改进，插件和主题开发人员必须接受和适应新技术。 我们中那些也写下我们的经验并分享我们所学知识的人现在“被迫”更新我们的教程，以便您可以跟上最新情况。 但我们对此感到高兴！

几周前，我们的一位读者 Ivan 在 Antonio 的教程中给我们留言寻求帮助。 显然他无法实现安东尼奥的插件。 而且，老实说，这并不让我感到惊讶，因为最近情况发生了很大变化。 因此，为了帮助 Ivan 和所有阅读我们并希望继续了解 WordPress 的人，让我们重新创建有关如何利用 WordPress 为我们提供的所有新工具向 Gutenberg 块编辑器添加按钮的教程！

创建插件

我们必须做的第一件事是创建一个 WordPress 插件。 这很简单。 基本上，我们所要做的就是在wp-content/plugins中创建一个文件夹，其名称是我们想要为我们的插件提供的名称（例如， gutenberg-button ），并在其中创建一个具有相同名称和一个.php扩展。 然后在您的插件文件中键入以下代码：

现在，让我们仔细看看前面的代码片段做了什么：

• 首先我们打开一个<?php标签。 这里没有惊喜。
• 接下来，在这个主文件中，我们添加一个多行注释。 注释包括几行“键/值”对。 例如，我们看到我们如何指定插件的名称 ( Plugin Name )、它的版本 ( Version ) 或作者的姓名 ( Author )。 所有这些信息都将在 WordPress 的插件部分中可见。
• 最后，我们添加一些样板代码：
  • 我们指定一个namespace （我们在这里讨论了命名空间），
  • 我们确保，如果文件运行，它作为 WordPress 的一部分运行，并且
  • 我们定义了一些关于插件的常量（稍后会有所帮助）。

完成所有这些后，如果我们转到 WordPress 的插件屏幕，我们将看到Gutenberg 按钮在那里：

我们激活它，然后……瞧！ 当然，它不会做任何事情，但它已经存在了。

JavaScript 插件开发

如今，WordPress 开发人员必须精通 JavaScript。 我猜，这就是古腾堡处于核心地位的后果之一。 本教程也不例外。

准备环境

如果我们想向 Gutenberg 界面添加一个新按钮，我们必须在 JavaScript 中编写此功能。 因此，让我们在插件中准备 JavaScript 开发环境。 为此，只需从命令行运行以下命令（这样做时请确保您位于wp-content/plugins/gutenberg-button ）：

 npm init

并按照说明进行操作：

 This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install <pkg>` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (gutenberg-button) version: (1.0.0) description: Adding a formatting button in Gutenberg. entry point: (index.js) ...

此过程的结果是一个package.json文件。 正如您稍后将看到的，此文件在未来将非常有用。

正如我已经在这篇文章的标题中透露的那样，我们将使用@wordpress/scripts来创建我们的插件。 因此，让我们通过运行以下命令将其添加为依赖项：

 npm install --save-dev @wordpress/scripts

该命令将在我们的插件中（在node_modules下）下载一堆依赖项，并将修改我们的package.json以便很明显@wordpress/scripts现在是一个开发依赖项。

如果你看一下这个包的文档，你会发现它包含很多用于构建、验证语法、格式化代码等的脚本：

 { "scripts": { "build": "wp-scripts build", "check-engines": "wp-scripts check-engines", "check-licenses": "wp-scripts check-licenses", "format:js": "wp-scripts format-js", "lint:css": "wp-scripts lint-style", "lint:js": "wp-scripts lint-js", "lint:md:docs": "wp-scripts lint-md-docs", "lint:md:js": "wp-scripts lint-md-js", "lint:pkg-json": "wp-scripts lint-pkg-json", "packages-update": "wp-scripts packages-update", "start": "wp-scripts start", "test:e2e": "wp-scripts test-e2e", "test:unit": "wp-scripts test-unit-js" } }

所以让我们编辑我们的package.json文件，以便"scripts"部分包含所有推荐的命令。

如何验证一切正常……

让我们在项目的根目录下创建一个src文件夹，并在其中添加一个index.js文件。 这将是我们插件的主要 JavaScript 文件，并将包含您的所有代码（然后您可以随意组织代码，只要主文件是src/index.js ）。

让我们通过添加以下语句index.js来测试事情是否按预期工作：

 console.log( 'Hi!' );

并使用npm run build项目。 这会将您的代码转换为浏览器可以运行的内容（现在实际上不需要，但只需几分钟）并在build文件夹中生成一个新脚本。

我们现在要做的就是告诉 WordPress 这个脚本存在，以便它可以加载它。 为此，只需打开插件的主文件 ( gutenberg-button.php ) 并在末尾添加以下行：

 function enqueue_script() { wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', [], GUTENBERG_BUTTON_VERSION ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

如果您注意，您会看到我们只是告诉 WordPress 将我们的新脚本/build/index.js作为块编辑器资源排入队列。 这样，当用户访问块编辑器时，我们的脚本将成为编辑器将包含的资产的一部分。

所以让我们看看这个。 转到您的 WordPress 仪表板，编辑帖子并查看浏览器的 JavaScript 控制台。 如果事情按预期进行，您应该会看到“嗨！” 写在控制台上：

复制我们的教程以向 Gutenberg 添加按钮

好的，既然我们已经看到我们可以编写 JavaScript 代码并npm run build成我们的浏览器可以理解的内容，那么是时候复制 Antonio 的教程了。 亲爱的读者，这非常简单。

打开src/index.js文件并将之前的console.log语句替换为以下内容：

如您所见，这与 Antonio 几个月前编写的代码几乎相同。 主要区别在于我们不再使用全局变量wp来访问 Gutenberg 的函数和组件。 相反，我们现在依赖于import语句。 但除此之外，它几乎是一样的。

编写好代码后，只需npm run build即可！ 您现在在 Gutenberg 中拥有按钮：

让我们通过选择一些文本并单击按钮来确保它有效：

你去吧，我们看到文本再次出现在控制台中！

关于依赖关系的最后说明......

如果您查看build文件夹，您会看到@wordpress/scripts不仅创建了一个index.js文件，而且还有一个index.asset.php文件。 该文件定义了一个具有两个属性的小对象：

• 我们的插件所需的依赖项列表（即 WordPress 脚本）
• 构建版本

如果我们想确保脚本能够正常运行，我们可以（并且应该）在 WordPress 中对我们的脚本进行排队时使用这两个属性。 为此，只需返回gutenberg-button.php并更改它，如下所示：

 function enqueue_script() { $asset = include GUTENBERG_BUTTON_PATH . '/build/index.asset.php'; wp_enqueue_script( 'gutenberg-button', GUTENBERG_BUTTON_URL . '/build/index.js', $asset['dependencies'], $asset['version'] ); }//end enqueue_script() add_action( 'enqueue_block_editor_assets', __NAMESPACE__ . '\enqueue_script' );

只需使用include语句加载index.asset.php中的对象，并将我们拥有的依赖项列表 ( [] ) 替换为实际依赖项，并使用内部版本号作为插件版本。

结论

创建真正有用的 WordPress 插件很棘手。 您必须充分了解 JavaScript 的工作原理并熟悉 WordPress 拥有的所有资源。 但是多亏了@wordpress/scripts包，准备 JavaScript 开发环境和构建可以在 WordPress 中运行的 JavaScript 插件比以往任何时候都容易。

我希望你喜欢今天的帖子。 而且，与往常一样，如果您在任何时候遇到困难或有任何疑问，请发表评论，我们会为您提供帮助。

哦，顺便说一下，这里是项目的链接，如果您愿意，可以下载和测试。 只需克隆项目， npm install所有依赖项， npm run build它并试一试！

Ashim D'Silva 在 Unsplash 上的特色图片。