gutenbergdocs/docs/getting-started/fundamentals/file-structure-of-a-block.md

## 附加资源

- [展示区块文件结构的示意图](https://excalidraw.com/#json=YYpeR-kY1ZMhFKVZxGhMi,mVZewfwNAh_oL-7bj4gmdw)

### `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`文件导出的函数用于返回将被保存到WordPress数据库的静态HTML标记。该函数会被传入`index.js`文件内`registerBlockType`函数的[`save`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#save)属性。

### `style.(css|scss|sass)`

扩展名为`.css`、`.scss`或`.sass`的`style`文件包含将在块编辑器和前端同时加载的区块样式。在构建过程中，该文件会被转换为`style-index.css`，通常通过`block.json`中的[`style`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style)属性进行定义。

<div class="callout callout-info">
    <code>wp-scripts</code>内部使用的webpack配置包含串联的
    <a href="https://webpack.js.org/loaders/css-loader/">css-loader</a>、
    <a href="https://webpack.js.org/loaders/postcss-loader/">postcss-loader</a>和
    <a href="https://webpack.js.org/loaders/sass-loader/">sass-loader</a>，
    使其能够处理CSS、SASS或SCSS文件。更多信息请参阅
    <a href="https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#default-webpack-config">默认webpack配置</a>。
</div>

### `editor.(css|scss|sass)`

扩展名为`.css`、`.scss`或`.sass`的`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`文件夹中的内容在块编辑器和前端渲染区块。

<div class="callout callout-info">
    您可以使用<code>wp-scripts</code>构建命令的<code>webpack-src-dir</code>和<code>output-path</code>选项来
    <a href="https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#automatic-block-json-detection-and-the-source-code-directory">自定义入口和输出路径</a>。
</div>

# 区块的文件结构

为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文件中通过服务器端注册区块。这可以通过使用[`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/)函数来实现。

<div class="callout callout-info">
    有关创建WordPress插件的更多信息，请参阅<a href="https://developer.wordpress.org/plugins/plugin-basics/">插件基础</a>文档以及主PHP文件的<a href="https://developer.wordpress.org/plugins/plugin-basics/header-requirements/">头部要求</a>。
</div>

## `package.json`

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

## `src`文件夹

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

通过`wp-scripts`提供的[构建过程](docs/block-editor/getting-started/fundamentals/javascript-in-the-block-editor/#javascript-build-process.md)会从此文件夹中获取文件，并在项目的`build`文件夹中生成可用于生产环境的文件。

### `block.json`

`block.json`文件包含[区块的元数据](docs/block-editor/reference-guides/block-api/block-metadata/)，可简化其在客户端和服务器端环境中的定义和注册过程。

该文件包括区块名称、描述、[属性](docs/block-editor/reference-guides/block-api/block-attributes/)、[支持特性](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中打开构建输出示意图")