# 区块的文件结构 为 WordPress 开发自定义区块时，最佳实践是在插件中注册它们，而非主题中。此策略确保即使用户切换主题，您的区块仍可访问。虽然在某些情况下将区块直接嵌入主题可能合适，但本指南重点介绍插件中的区块。具体而言，它详细说明了由 [`create-block`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/) 工具生成的文件结构。 遵循 `create-block` 工具的结构并非强制要求，但它是一个可靠的参考。它生成的文件包含了区块定义和注册所需的一切。遵循此结构有助于保持一致性，并确保您的区块组织良好且易于维护。 [![打开区块文件结构示意图](https://developer.wordpress.org/files/2023/11/file-structure-block.png)](https://developer.wordpress.org/files/2023/11/file-structure-block.png "打开区块文件结构示意图") ## `.php` 在 WordPress 插件中创建区块时，需要在插件的主 PHP 文件中于服务器端注册该区块。对于使用 `wp-scripts` 构建的插件（WordPress 6.8+），推荐的方法是使用 [`wp_register_block_types_from_metadata_collection()`](https://developer.wordpress.org/reference/functions/wp_register_block_types_from_metadata_collection/)，它通过一次调用即可注册生成的 `blocks-manifest.php` 文件中的所有区块。对于较简单的设置或较旧的 WordPress 版本，可以使用 [`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/) 来注册单个区块。有关所有可用注册方法的完整详细信息，请参阅[区块注册](/docs/getting-started/fundamentals/registration-of-a-block)。
有关创建 WordPress 插件的更多信息，请参阅关于插件基础的文档以及主 PHP 文件的头部要求。
## `package.json` `package.json` 文件用于配置 Node.js 项目，从技术上讲，区块插件就是这样的项目。在此文件中，您可以定义区块的 `npm` 依赖项以及用于本地开发的脚本。 ## `src` 文件夹 在标准项目中，`src`（源代码）文件夹包含原始的、未编译的代码，包括开发区块所需的 JavaScript、CSS 和其他资源。这是您编写和编辑区块源代码的地方，可以利用现代 JavaScript 功能和 JSX 来编写 React 组件。 随后，`wp-scripts` 提供的[构建过程](docs/getting-started/fundamentals/docs/block-editor/getting-started/fundamentals/javascript-in-the-block-editor#javascript-build-process.md)将从此文件夹中获取文件，并在项目的 `build` 文件夹中生成可用于生产环境的文件。 ### `block.json` `block.json` 文件包含[区块的元数据](docs/getting-started/fundamentals/docs/block-editor/reference-guides/block-api/block-metadata)，用于简化其在客户端和服务器端环境中的定义和注册。 该文件包含区块名称、描述、[属性](docs/getting-started/fundamentals/docs/block-editor/reference-guides/block-api/block-attributes)、[支持特性](docs/getting-started/fundamentals/docs/block-editor/reference-guides/block-api/block-supports)等，以及负责区块功能、外观和样式的重要文件的位置。 当应用构建过程时，`block.json` 文件和其他生成的文件会被移动到一个指定文件夹（通常是 `build` 文件夹）。因此，`block.json` 中指定的文件路径指向这些经过处理、打包后的文件版本。 可以在 `block.json` 中定义的一些最重要的属性包括： - **[`editorScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-script):** 通常设置为从 `src/index.js` 构建的打包 `index.js` 文件的路径。 - **[`style`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style):** 通常设置为从 `src/style.(css|scss|sass)` 构建的打包 `style-index.css` 文件的路径。 - **[`editorStyle`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-style):** 通常设置为从 `src/editor.(css|scss|sass)` 构建的打包 `index.css` 文件的路径。 - **[`render`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render):** 通常设置为从 `src/render.php` 复制而来的打包 `render.php` 文件的路径。 - **[`viewScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#view-script):** 通常设置为从 `src/view.js` 构建的打包 `view.js` 文件的路径。 [![在 excalidraw 中打开构建输出图](https://developer.wordpress.org/files/2023/11/file-structure-build-output.png)](https://excalidraw.com/#json=c22LROgcG4JkD-7SkuE-N,rQW_ViJBq0Yk3qhCgqD6zQ "在 excalidraw 中打开构建输出图") ### `index.js` `index.js` 文件（或 `block.json` 中 `editorScript` 属性定义的任何其他文件）是仅应在区块编辑器中加载的 JavaScript 入口文件。它负责调用 `registerBlockType` 函数在客户端注册区块，并通常导入 `edit.js` 和 `save.js` 文件以获取区块注册所需的函数。 ### `edit.js` `edit.js` 文件包含负责渲染区块编辑用户界面的 React 组件，允许用户在区块编辑器中与区块内容和设置进行交互及自定义。该组件会被传递给 `index.js` 文件中 `registerBlockType` 函数的 [`edit`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#edit) 属性。 ### `save.js` `save.js` 导出的函数会返回静态 HTML 标记，这些标记将被保存到 WordPress 数据库中。该函数会传递给 `index.js` 文件中 `registerBlockType` 函数的 [`save`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#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`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style) property in `block.json`
The webpack configuration used internally by wp-scripts includes a css-loader chained with postcss-loader and sass-loader that allows it to process CSS, SASS or SCSS files. Check Default webpack config for more info
### `editor.(css|scss|sass)` 扩展名为 `.css`、`.scss` 或 `.sass` 的 `editor` 文件包含应用于块编辑器（Block Editor）中块的附加样式。此文件通常用于定义块用户界面的特定样式。在构建过程中，该文件会被转换为 `index.css`，通常在 `block.json` 中通过 `editorStyle` 属性定义。 ### `render.php` `render.php` 文件（或在 `block.json` 的 [`render`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render) 属性中定义的任何其他文件）定义了服务器端处理流程，当从前端收到请求时，该流程会返回区块的标记。如果定义了此文件，它将优先于其他在前端渲染区块标记的方式。 ### `view.js` 当区块在前端显示时，`view.js` 文件（或 `block.json` 中 [`viewScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#view-script) 属性定义的任何其他文件）将被加载。 ## `build` 文件夹 `build` 文件夹包含来自 `src` 文件夹的代码经过编译和优化的版本。这些文件由 [构建过程](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/#the-build-process-with-wp-scripts) 生成，该过程由 `wp-scripts` 的 `build` 或 `start` 命令触发。 此转换过程包括代码压缩、将现代 JavaScript 转译为兼容更广泛浏览器的版本，以及资源捆绑以实现高效加载。WordPress 最终会加载并使用 `build` 文件夹中的内容，以在区块编辑器和前端渲染区块。
你可以使用 `wp-scripts` 构建命令的 webpack-src-dir 和 output-path 选项来 自定义入口点和输出点。
## 其他资源 - [展示区块文件结构的示意图](https://excalidraw.com/#json=YYpeR-kY1ZMhFKVZxGhMi,mVZewfwNAh_oL-7bj4gmdw)