分类： 搭建新区块

搭建新区块

当你为区块开发安装了必要的工具后，就可以开始开发你的第一个区块了。

在本课中，你将了解一个名为 create-block 的工具，它能让你快速搭建第一个区块插件。你将学习为什么要使用 create-block、如何使用它，并审查它生成的代码。

什么是 create-block？

与任何软件开发项目一样，为 WordPress 开发区块需要以特定方式设置一系列文件和文件夹。

有多种方法可以做到这一点，但你理想的做法是遵循某些最佳实践来构建区块。

Create-block 是一个命令行工具，可帮助你按照这些最佳实践搭建新的区块插件。

在软件开发中，脚手架搭建是指为项目创建基本结构的过程，以便你在此基础上进行构建。

使用 create-block，你可以运行一个终端命令来创建新的区块插件，create-block 会按照区块开发的最佳实践为你设置必要的文件和文件夹。

为什么用插件？

虽然不要求必须将区块作为插件的一部分来开发，但这通常是推荐的做法。

主要原因之一是，提交到 WordPress.org 主题目录的主题中不允许包含自定义区块。

然而，如果你是为自己或客户开发主题，则可以在主题中包含自定义区块，区别在于注册区块的方式不同。

但归根结底，区块开发体验和工具设计为与插件配合使用效果最佳，因此本系列课程将遵循这一方式。

我们要构建什么？

在本系列课程中，你将构建一个“版权日期区块”。

这是一个基础但实用的区块，具有以下功能：

  • 显示文本“Copyright”，后跟版权符号（©），然后是起始年份和当前年份
  • 用户应能调整区块在页面上的对齐方式
  • 它应始终应用以下 CSS：border: 1px solid #111111; padding: 5px;
  • 用户还应能调整起始年份

使用 Create Block

要搭建你的第一个区块，请在本地计算机上打开终端，并切换到本地 WordPress 安装目录的 /wp-content/plugins 目录。

通常通过运行以下命令来完成：

cd /path/to/your/wordpress/wp-content/plugins

然后，运行 create-block 命令，并包含一个插件别名。别名是你想创建的插件的唯一名称。

npx @wordpress/create-block copyright-date-block

如果系统要求确认安装 create-block 包，请输入 y 并按回车键。

这将在 copyright-date-block 目录中创建一个新插件，安装所有必需的包，并创建必要的文件。

一旦新插件搭建完成，你的 WordPress 安装目录中应该会出现一个新的插件文件夹，其名称与你定义的别名一致。

如果你浏览到 WordPress 仪表盘并导航到插件页面，应该会看到你的新插件列在那里。

激活它，一旦激活，创建一篇新文章。

你应该能够在编辑器中添加你新搭建的区块。

搭建好的插件

通过在代码编辑器中打开 copyright-date-block 目录，查看搭建好的区块插件的样子。

首先，有三个目录：

  • build 目录是区块代码最终可部署构建版本所在的位置。这是在编辑器中使用区块时驱动区块的代码。你通常不需要触碰此目录或其任何文件。
  • node_modules 目录是所有 Node.js 包所在的位置。这些也称为项目依赖项，你仅在本地区块开发时需要它们。
  • src 目录是你编写区块代码时花费大部分时间的地方。此目录包含你将用于开发区块的文件。这些文件最终会被编译到 build 目录中的代码中。

在这三个目录之后，还有一些文件。

.editorconfig 文件用于统一不同编辑器和 IDE 的编码风格。

.gitignore 由 Git 版本控制系统使用，用于管理哪些代码提交到版本控制。

这些文件的作用超出了区块开发所需的知识范围，所以如果你不知道它们是做什么用的，暂时可以放心忽略它们。

如果你看不到这两个文件，可能需要在目录浏览器或代码编辑器中启用“显示隐藏文件”功能。

接下来是 copyright-date-block.php 文件。这是启动插件执行的主插件文件。

在该文件中，你会看到标准的插件头部信息以及用于注册区块的 PHP 代码。

这里，copyright_date_block_copyright_date_block_block_init 函数调用了 register_block_type() 函数，并将前面提到的 build 目录的路径作为参数传入。

这个函数随后被挂载到 init 动作上。

接下来，你会看到 package-lock.json 文件和 package.json 文件。

package.json 文件是 npm 在开发 JavaScript 项目时使用的文件。

{
    "name": "copyright-date-block",
    "version": "1.0.0",
    "description": "Example block scaffolded with Create Block tool.",
    "main": "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": "^27.9.0"
    }
}

它包含了项目的关键信息，包括可以在项目上运行的任何脚本以及所有依赖项。

依赖项是你的项目正常运行所需的外部包或模块。就区块开发而言，你需要的依赖项是 @wordpress/scripts 包的开发依赖项。这些依赖项会被安装到你的 node_modules 目录中。

scripts 对象包含了一系列可以在开发过程中运行的命令行脚本。其中最重要的有：

  • build：将 src 目录中的文件编译到 build 目录中
  • start：启动一个开发服务器，监视 src 目录中文件的变化，并自动将它们编译到 build 目录中

当你开始开发区块时，会学习如何使用这些脚本。

package-lock.json 文件包含了所有已安装依赖项的列表，以及所使用的依赖项的版本号。它将所需的依赖项锁定到此文件中指定的版本号。这是另一个你现在可以忽略的文件。

最后，还有一个 readme.txt 文件，只有当你打算将插件发布到 WordPress 插件目录时，才需要编辑它。

src 目录

你所有的区块开发工作都在 src 目录中进行。让我们看看生成了哪些文件：

  • block.json 以 JSON 对象的形式存储区块的元数据。你可以在区块元数据手册页面中了解更多关于区块元数据的信息。此文件允许你定义区块名称、标题、图标、组成区块的各种文件等等。
  • edit.js 是你在开发区块时花费大部分时间的地方。此文件导出一个 React Edit() 组件，该组件在编辑器中渲染，并决定区块在编辑器中的外观和功能。
  • editor.scss 包含控制区块在区块编辑器中外观的样式。通常，你会希望区块在编辑器中的外观与网站前端一致，因此你通常根本不需要此文件。
  • index.js 是区块 JavaScript 执行的起点。它设置并执行 registerBlockType 函数，以在编辑器中注册区块。
  • save.js 导出一个 save() 函数，该函数决定在保存文章或页面时将保存到 wp_posts 表中 post_content 字段的标记，因此也决定了区块在前端的外观和功能。
  • style.scss 包含控制区块在编辑器和前端外观的样式。如果你需要区块在编辑器中显示不同，此处的样式可以被 editor.scss 中的样式覆盖。
  • view.js 是一个用于在前端为区块添加任何额外 JavaScript 的文件。这是另一个你通常不需要的文件。

build 目录

在开发过程中，你将执行之前在 package.json 文件中看到的脚本，将 src 目录中的文件编译到 build 目录中。

构建区块代码的过程，也称为打包代码，是将区块代码转换为所有浏览器兼容格式的过程。

当你生成区块脚手架时，create-block 工具也运行了构建过程，为你生成了 build 目录。

你会注意到，有些文件（如 block.json 文件）会原样打包到 build 目录中，而其他文件（如 index.js 文件）则会被转换。还有一些额外的文件，如 index.asset.php 文件，是在构建过程中生成的。

当 WordPress 在编辑器或前端加载你的区块时，它执行的是来自 build 目录中的代码。

在 package.json 文件中定义为开发依赖的 @wordpress/scripts 包，使用一个名为 Webpack 的工具来打包你的区块代码。

关于其工作原理的细节超出了本课程的范围，但你可以在 Webpack 文档中了解更多信息。

附加资源

要了解更多关于 create-block 工具及其提供的所有不同选项，请查看区块编辑器手册中关于 create-block 的包参考文档。