title: "区块的文件结构" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Fundamentals - Getting Started - Repos

区块的文件结构

为 WordPress 开发自定义区块时，最佳实践是在插件中注册它们，而非主题中。此策略确保即使用户切换主题，您的区块仍可访问。虽然在某些情况下将区块直接嵌入主题可能合适，但本指南重点介绍插件中的区块。具体而言，它详细说明了由 create-block 工具生成的文件结构。

遵循 create-block 工具的结构并非强制要求，但它是一个可靠的参考。它生成的文件包含了区块定义和注册所需的一切。遵循此结构有助于保持一致性，并确保您的区块组织良好且易于维护。

<plugin-file>.php

在 WordPress 插件中创建区块时，需要在插件的主 PHP 文件中于服务器端注册该区块。对于使用 wp-scripts 构建的插件（WordPress 6.8+），推荐的方法是使用 wp_register_block_types_from_metadata_collection()，它通过一次调用即可注册生成的 blocks-manifest.php 文件中的所有区块。对于较简单的设置或较旧的 WordPress 版本，可以使用 register_block_type() 来注册单个区块。有关所有可用注册方法的完整详细信息，请参阅区块注册。

package.json

package.json 文件用于配置 Node.js 项目，从技术上讲，区块插件就是这样的项目。在此文件中，您可以定义区块的 npm 依赖项以及用于本地开发的脚本。

src 文件夹

在标准项目中，src（源代码）文件夹包含原始的、未编译的代码，包括开发区块所需的 JavaScript、CSS 和其他资源。这是您编写和编辑区块源代码的地方，可以利用现代 JavaScript 功能和 JSX 来编写 React 组件。

随后，wp-scripts 提供的构建过程将从此文件夹中获取文件，并在项目的 build 文件夹中生成可用于生产环境的文件。

block.json

block.json 文件包含区块的元数据，用于简化其在客户端和服务器端环境中的定义和注册。

该文件包含区块名称、描述、属性、支持特性等，以及负责区块功能、外观和样式的重要文件的位置。

当应用构建过程时，block.json 文件和其他生成的文件会被移动到一个指定文件夹（通常是 build 文件夹）。因此，block.json 中指定的文件路径指向这些经过处理、打包后的文件版本。

可以在 block.json 中定义的一些最重要的属性包括：

• editorScript: 通常设置为从 src/index.js 构建的打包 index.js 文件的路径。
• style: 通常设置为从 src/style.(css|scss|sass) 构建的打包 style-index.css 文件的路径。
• editorStyle: 通常设置为从 src/editor.(css|scss|sass) 构建的打包 index.css 文件的路径。
• render: 通常设置为从 src/render.php 复制而来的打包 render.php 文件的路径。
• viewScript: 通常设置为从 src/view.js 构建的打包 view.js 文件的路径。

index.js

index.js 文件（或 block.json 中 editorScript 属性定义的任何其他文件）是仅应在区块编辑器中加载的 JavaScript 入口文件。它负责调用 registerBlockType 函数在客户端注册区块，并通常导入 edit.js 和 save.js 文件以获取区块注册所需的函数。

edit.js

edit.js 文件包含负责渲染区块编辑用户界面的 React 组件，允许用户在区块编辑器中与区块内容和设置进行交互及自定义。该组件会被传递给 index.js 文件中 registerBlockType 函数的 edit 属性。

save.js

save.js 导出的函数会返回静态 HTML 标记，这些标记将被保存到 WordPress 数据库中。该函数会传递给 index.js 文件中 registerBlockType 函数的 save 属性。

style.(css|scss|sass)

A style file with extensions .css, .scss, or .sass contains the styles of the block that will be loaded in both the Block Editor and on the front end. In the build process, this file is converted into style-index.css, which is usually defined using the style property in block.json

editor.(css|scss|sass)

扩展名为 .css、.scss 或 .sass 的 editor 文件包含应用于块编辑器（Block Editor）中块的附加样式。此文件通常用于定义块用户界面的特定样式。在构建过程中，该文件会被转换为 index.css，通常在 block.json 中通过 editorStyle 属性定义。

render.php

render.php 文件（或在 block.json 的 render 属性中定义的任何其他文件）定义了服务器端处理流程，当从前端收到请求时，该流程会返回区块的标记。如果定义了此文件，它将优先于其他在前端渲染区块标记的方式。

view.js

当区块在前端显示时，view.js 文件（或 block.json 中 viewScript 属性定义的任何其他文件）将被加载。

build 文件夹

build 文件夹包含来自 src 文件夹的代码经过编译和优化的版本。这些文件由 构建过程 生成，该过程由 wp-scripts 的 build 或 start 命令触发。

此转换过程包括代码压缩、将现代 JavaScript 转译为兼容更广泛浏览器的版本，以及资源捆绑以实现高效加载。WordPress 最终会加载并使用 build 文件夹中的内容，以在区块编辑器和前端渲染区块。

其他资源

• 展示区块文件结构的示意图