2551654928/gutenbergdocs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
unknown
2025-10-22 01:40:18 +08:00
parent 2080fa3878
commit 28ad1b3935
251 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/getting-started/README.md Normal file
View File

@@ -0,0 +1,41 @@
# 入门指南
欢迎阅读入门指南文档。从搭建开发环境到构建第一个区块，再到理解基础概念，本部分内容都是绝佳的起点——无论您是区块开发新手，还是希望提升技能的开发者。
## 本章导航
通过以下链接快速定位本章节内容。若从未构建过区块，建议按所列顺序阅读文档。
- **[区块开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/)**: 配置专属开发环境，认识区块开发基础工具：[`wp-env`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)、[`create-block`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/) 与 [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/)
- **[快速入门指南](https://developer.wordpress.org/block-editor/getting-started/quick-start-guide/)**: 一分钟内快速创建可运行的自定义区块
- **[教程：构建你的第一个区块](https://developer.wordpress.org/block-editor/getting-started/tutorial/)**: 从零开始构建功能完整的自定义区块
- **[区块开发基础](https://developer.wordpress.org/block-editor/getting-started/fundamentals/)**: 掌握区块开发核心概念
- **[术语表](https://developer.wordpress.org/block-editor/getting-started/glossary/)**: 区块编辑器常用术语释义
- **[常见问题解答](https://developer.wordpress.org/block-editor/getting-started/faq/)**: 古腾堡项目近年来的高频问答合集
## 跟进WordPress项目动态
完成本章学习后，您将对区块开发形成系统认知。接下来该关注什么？
WordPress项目（特别是古腾堡）迭代迅速。为帮助您持续跟进，以下推荐核心开发者资源。请根据自身需求选择合适的信息渠道：
- **[WordPress发展路线图](https://wordpress.org/about/roadmap/)**: 项目高层级发展规划
- **[核心开发博客](https://make.wordpress.org/core/)**: 获取WordPress核心更新的主阵地
- **[WordPress Slack社区](https://make.wordpress.org/chat/)**: 官方协作平台，建议加入`#core`与`#core-editor`频道
- **[古腾堡GitHub仓库](https://github.com/WordPress/gutenberg/)**: 区块编辑器开发实况窗口
- **[古腾堡动态追踪](https://make.wordpress.org/core/handbook/references/keeping-up-with-gutenberg-index/)**: 跨团队动态合集
- **[古腾堡新功能速递](https://make.wordpress.org/core/tag/gutenberg-new/)**: 双周版本更新详解
- **[开发者月报](https://developer.wordpress.org/news/)**: 月度重要开发变更汇总
## 扩展资源
如需更多区块开发与编辑器扩展资源，请查阅区块编辑器手册的其他章节。[block-development-examples](https://github.com/WordPress/block-development-examples)代码库中还有更多实践案例。
若想系统学习，欢迎访问[Learn WordPress](https://learn.wordpress.org/)平台，这里提供精选教程与课程：
- [区块开发入门：构建你的第一个自定义区块](https://learn.wordpress.org/course/introduction-to-block-development-build-your-first-custom-block/)
- [短代码转区块开发实战](https://learn.wordpress.org/course/converting-a-shortcode-to-a-block/)
- [WordPress数据层应用详解](https://learn.wordpress.org/course/using-the-wordpress-data-layer/)
- [区块模式注册指南](https://learn.wordpress.org/workshop/registering-block-patterns/)
- [古腾堡区块开发入门](https://learn.wordpress.org/workshop/intro-to-gutenberg-block-development/)
- [区块编辑器发布流程详解](https://learn.wordpress.org/workshop/intro-to-publishing-with-the-block-editor/)

61
docs/getting-started/devenv/README.md Normal file
View File

@@ -0,0 +1,61 @@
# 区块开发环境
本指南将帮助您搭建合适的开发环境，用于创建扩展和修改WordPress区块编辑器的区块及其他插件。
区块开发环境包含在计算机上成功进行区块编辑器开发所需的工具。以下三项是基本要求：
- [区块开发环境](#区块开发环境)
- [代码编辑器](#代码编辑器)
- [Node.js开发工具](#nodejs开发工具)
- [本地WordPress环境](#本地wordpress环境)
<div class="callout callout-info">
若想为Gutenberg项目本身做贡献，请参阅<a href="https://developer.wordpress.org/block-editor/contributors/code/getting-started-with-code-contribution">代码贡献指南</a>中的补充文档。
</div>
## 代码编辑器
代码编辑器用于编写代码。您可以使用任何熟悉的编辑器，关键是要具备打开、编辑和保存文本文件的功能。
如果您还没有偏好的代码编辑器，[Visual Studio Code](https://code.visualstudio.com/)（VS Code）是核心贡献者中进行JavaScript开发的流行选择。它完美兼容三大主流平台（Windows、Linux和Mac），是微软积极维护的开源软件。VS Code还拥有活跃的社区提供插件和扩展支持，其中包含许多适用于WordPress开发的工具。
## Node.js开发工具
Node.js（`node`）是一个开源运行时环境，允许您在网络浏览器之外执行JavaScript。虽然并非所有WordPress JavaScript开发都需要Node.js，但在使用现代JavaScript工具和进行区块编辑器开发时它必不可少。
Node.js及其配套开发工具使您能够：
- 安装并运行区块编辑器开发所需的WordPress包，例如`wp-scripts`
- 使用`wp-env`和`@wp-playground/cli`搭建本地WordPress环境
- 使用最新ECMAScript特性并以ESNext规范编写代码
- 对JavaScript代码进行格式检查、格式化与测试
- 使用`create-block`包快速创建自定义区块
其功能远不止于此。虽然现代JavaScript开发可能具有挑战性，但WordPress提供了[`wp-scripts`](/docs/getting-started/devenv/get-started-with-wp-scripts.md)和[`create-block`](/docs/getting-started/devenv/get-started-with-create-block.md)等工具来简化流程，这些都得益于Node.js开发工具的支持。
**区块开发推荐使用Node.js的[Active LTS](https://nodejs.org/en/about/previous-releases)（长期支持）版本**。但有时您可能需要使用不同版本。强烈推荐使用`nvm`等Node.js版本管理工具，它允许您在需要时切换`node`版本。您还需要Node包管理器（`npm`）和Node包执行工具（`npx`）来处理某些WordPress包，这两者会随Node.js自动安装。
为了使用Node.js工具和[WordPress提供的开发包](https://github.com/WordPress/gutenberg/tree/trunk/packages)进行区块开发，您需要在计算机上配置合适的Node.js运行时环境。具体设置方法请参考以下链接：
- [在Mac和Linux上安装Node.js](/docs/getting-started/devenv/nodejs-development-environment.md#node-js-installation-on-mac-and-linux-with-nvm)
- [在Windows上安装Node.js](/docs/getting-started/devenv/nodejs-development-environment.md#node-js-installation-on-windows-and-others)
## 本地WordPress环境
本地WordPress环境（站点）为开发提供了受控、高效且安全的空间，让您可以在部署到生产站点之前构建和测试代码。WordPress的相同[运行要求](https://en-gb.wordpress.org/about/requirements/)也适用于本地站点。
在更广泛的WordPress社区中，有许多工具可用于在计算机上搭建本地WordPress环境。本《区块编辑器手册》重点介绍由WordPress项目自身维护的开源工具`wp-env`，它也是Gutenberg开发的推荐工具。
具体设置说明请参阅[`wp-env`入门指南](/docs/getting-started/devenv/get-started-with-wp-env.md)。
<div class="callout callout-info">
在本手册中，您可能还会看到对<code><a href="https://github.com/WordPress/wordpress-playground/tree/trunk/packages/playground/cli">@wp-playground/cli</a></code>的引用。这是一个由<a href="https://developer.wordpress.org/playground/">WordPress Playground</a>驱动的轻量级工具，可简化本地WordPress环境的搭建。虽然仍处于实验阶段，但该工具非常适合快速测试WordPress版本、插件和主题。
</div>
以下列举了部分备选方案（若您不想使用`wp-env`）：
- [WordPress Studio](https://developer.wordpress.com/studio/)
- [Local](https://localwp.com/)
- [XAMPP](https://www.apachefriends.org/)
- [MAMP](https://www.mamp.info/en/mamp/mac/)
- [Varying Vagrant Vagrants](https://varyingvagrantvagrants.org/)（VVV）

95
docs/getting-started/devenv/get-started-with-create-block.md Normal file
View File

@@ -0,0 +1,95 @@
# 使用 create-block 快速入门
WordPress 区块编辑器的自定义区块通常通过插件注册，并由特定文件集合定义。[`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) 是官方支持的脚手架工具，可快速生成创建和注册区块所需的文件结构。它能生成项目初始代码，并集成现代化的 JavaScript 构建环境（使用 [`wp-scripts`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/)），无需额外配置。
该工具包旨在帮助开发者遵循 WordPress 最佳实践快速搭建区块开发环境。
## 快速开始
### 安装配置
请先确保计算机已安装 Node.js 和 `npm`。若未安装，请查阅 [Node.js 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/)指南。
您可以在任意目录使用 `create-block` 创建区块脚手架，然后在生成的插件文件夹内[使用 `wp-env`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/) 创建本地 WordPress 开发环境，该环境会自动安装并激活您的新区块插件。
若已搭建[本地 WordPress 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment)，请通过终端进入 `plugins/` 目录。
执行以下命令创建示例区块插件：
```bash
npx @wordpress/create-block@latest todo-list
cd todo-list
```
其中提供的 `slug` 参数（`todo-list`）将作为插件文件夹名称和内部区块标识。
进入本地 WordPress 的插件管理页面，激活 "Todo List" 插件后，即可在编辑器中找到该示例区块。
### 基础使用
`create-block` 默认采用现代 JavaScript（ESNext 与 JSX）构建区块，这需要构建步骤将代码编译为浏览器可识别的格式。幸运的是，`wp-scripts` 工具包已自动处理此过程。关于该工具的详细介绍请参阅 [wp-scripts 入门指南](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts)。
当 `create-block` 生成区块脚手架时，会自动安装 `wp-scripts` 并将常用脚本添加到区块的 `package.json` 文件中，默认包含：
```json
{
"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"
}
}
```
这些脚本可通过 `npm run {脚本名称}` 命令运行。最常使用的两个脚本是 `start` 和 `build`，它们负责构建流程。
开发区块时请运行 `npm run start` 命令，这将启动开发服务器并在检测到代码变更时自动重新构建。
准备部署区块时请运行 `npm run build` 命令，该命令会对代码进行优化并生成生产环境版本。
各脚本的详细说明请参阅 `wp-scripts` 的[工具包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
## 其他实现方式
### 交互模式
为偏好引导式操作的开发者，`create-block` 提供了交互模式。此模式会逐步提示输入配置参数，无需像前文示例那样手动预先指定 `slug` 等所有选项。
运行以下命令启用此模式：
```bash
npx @wordpress/create-block@latest
```
根据提示逐步完成区块设置即可。
### 快速启动模式（选项参数）
若您已熟悉 `create-block` 的[选项参数](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#options)并希望快速完成配置，可使用快速启动模式。通过命令行直接传递特定参数，省去交互提示步骤。
例如，要快速创建命名空间为 "my-plugin"、区块标识为 "my-block" 的动态区块，可使用：
```bash
npx @wordpress/create-block@latest --namespace="my-plugin" --slug="my-block" --variant="dynamic"
```
### 使用模板
`create-block` 支持模板功能，允许基于预定义配置和结构创建区块。当您有特定区块结构偏好，或需构建多个相似配置的区块时，此功能尤为实用。
使用模板时，需通过 `--template` 选项指定模板名称或路径：
```bash
npx @wordpress/create-block --template="my-custom-template"
```
模板需预先设置以确保 `create-block` 能正确识别。更多细节请参阅 `create-block` 的[模板文档](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/#template)，并查阅[外部项目模板指南](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/)。
## 扩展资源
- [使用 create-block 工具](https://learn.wordpress.org/tutorial/using-the-create-block-tool/)（Learn WordPress 教程）
- [@wordpress/create-block](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)（官方文档）
- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)（官方文档）

144
docs/getting-started/devenv/get-started-with-wp-env.md Normal file
View File

@@ -0,0 +1,144 @@
# 开始使用 wp-env
[@wordpress/env](https://www.npmjs.com/package/@wordpress/env) 包（简称 `wp-env`）可帮助您快速搭建本地 WordPress 环境（站点），用于插件和主题的开发测试，无需任何额外配置。
在按照本指南操作前，请先确保已安装 [Node.js 开发工具](/docs/getting-started/devenv#node-js-development-tools)。
![wp-env 基础架构图](https://developer.wordpress.org/files/2023/10/wp-env-diagram.png)
## 快速开始
1. 根据操作系统说明下载、安装并启动 [Docker Desktop](https://www.docker.com/products/docker-desktop)
2. 在终端中运行 `npm -g install @wordpress/env` 全局安装 `wp-env`
3. 在终端中进入现有插件目录、主题目录或新建工作目录
4. 运行 `wp-env start` 启动本地 WordPress 环境
5. 脚本运行完成后，访问 <code>http://localhost:8888/wp-admin</code>，使用用户名 `admin` 和密码 `password` 登录 WordPress 管理后台
## 配置 Docker Desktop
`wp-env` 工具使用 [Docker](https://www.docker.com/) 创建运行本地 WordPress 站点的虚拟机。Docker Desktop 应用程序对小型企业、个人用户、教育机构和非商业开源项目免费。详见官方 [FAQ](https://docs.docker.com/desktop/faqs/general/#do-i-need-to-pay-to-use-docker-desktop)。
点击对应链接下载并安装适用于您操作系统的 Docker Desktop：
- [Mac 版 Docker Desktop](https://docs.docker.com/desktop/install/mac-install/)
- [Windows 版 Docker Desktop](https://docs.docker.com/desktop/install/windows-install/)
- [Linux 版 Docker Desktop](https://docs.docker.com/desktop/install/linux-install/)
若使用早于 20.04.1 的 Ubuntu 版本，请参阅下方的[故障排除说明](#ubuntu-docker-setup)。
成功安装后启动 Docker Desktop 应用程序，按提示完成设置。通常使用推荐（默认）设置即可，创建 Docker 账户为可选步骤。
## 安装并运行 `wp-env`
`wp-env` 工具用于通过 Docker 创建本地 WordPress 环境。配置好 Docker Desktop 后，在终端中运行以下命令安装 `wp-env`：
```sh
npm -g install @wordpress/env
```
此命令将全局安装 `wp-env`，使该工具可在任意目录运行。可通过运行 `wp-env --version` 验证安装，成功会显示版本号。
接着在终端中进入现有插件目录、主题目录或新建工作目录，运行：
```sh
wp-env start
```
脚本执行完毕后，即可通过 <code>http://localhost:8888</code> 访问本地环境。使用用户名 `admin` 和密码 `password` 登录 WordPress 管理后台。
<div class="callout callout-tip">
部分项目（如 Gutenberg）包含特定的 <code>wp-env</code> 配置，文档可能会要求您运行 <code>npm run wp-env start</code> 命令
</div>
有关控制 Docker 环境的更多信息，请参阅 [@wordpress/env 包](/packages/env/README.md) 说明文档。
### 运行环境配置
`wp-env` 工具几乎可在任意目录运行。在开发单个插件时，在插件所在目录执行 `wp-env start` 可自动挂载并激活该插件。此规则同样适用于主题开发目录。
若在非插件/主题目录运行 `wp-env start`，将创建通用 WordPress 环境。此时脚本会显示以下警告，若属预期行为可忽略：
```
!! 警告：未找到 .wp-env.json 配置文件，且无法判定“DIR”是否为 WordPress 安装目录、插件或主题
```
您还可以通过 `.wp-env.json` 配置文件创建支持多插件和/或主题的环境。详细配置说明请参阅 [@wordpress/env 包](/packages/env/README.md#wp-envjson) 文档。
### 卸载或重置 `wp-env`
以下是一些操作指南，适用于需要重新开始或希望移除已安装内容的情况。
- 如果只需重置并清理 WordPress 数据库，请运行 `wp-env clean all`
- 若要完全移除特定项目的本地环境，请运行 `wp-env destroy`
- 若要全局卸载 `wp-env` 工具，请运行 `npm -g uninstall @wordpress/env`
## 故障排除
### 常见错误
使用 `wp-env` 时，常见错误提示：`执行 docker-compose 命令时出错`
- 请检查 Docker Desktop 是否已启动并正在运行。
- 查看 Docker Desktop 控制面板中的日志，重启或移除现有的虚拟机。
- 然后尝试重新运行 `wp-env start`。
如果出现错误：`主机已被其他容器占用`
- 您尝试启动的容器已在运行，或者存在其他容器占用。您可以通过在启动该容器的目录中运行 `wp-env stop` 来停止现有容器。
- 如果不记得启动 `wp-env` 的目录，可以通过运行 `docker stop $(docker ps -q)` 停止所有容器。此操作会停止所有 Docker 容器，请谨慎使用。
- 然后尝试重新运行 `wp-env start`。
### Ubuntu Docker 设置
如果您使用的 Ubuntu 版本早于 20.04.1，在使用 `wp-env` 设置本地 WordPress 环境时可能会遇到错误。
要解决此问题，请先按照 Docker 的[安装指南](https://docs.docker.com/install/linux/docker-ce/ubuntu/)进行操作。同时需要安装 `docker-compose`，您可能需要单独安装。请参阅 [Docker compose 文档](https://docs.docker.com/compose/install/)。
安装 Docker 和 `wp-env` 后，假设 `wp-env` 已全局配置，尝试在某个目录中运行 `wp-env start`。如果遇到以下错误：
```
错误：无法在 http+docker://localhost 连接到 Docker 守护进程——它是否正在运行？
如果它位于非标准位置，请使用 DOCKER_HOST 环境变量指定 URL。
```
首先，请确保 Docker 正在运行。可以通过运行 `ps -ef | grep docker` 来检查，应返回类似以下内容：
```
/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
```
如果 Docker 未运行，请尝试通过运行 `sudo systemctl start docker.service` 启动服务。
如果 Docker 正在运行，但未监听 WordPress 环境的通信方式。请尝试添加以下服务覆盖文件以包含对 `tcp` 的监听。有关如何配置 Docker 守护进程的远程访问，请参阅 [Docker 文档](https://docs.docker.com/config/daemon/remote-access/)。
```
# /etc/systemd/system/docker.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// -H tcp://0.0.0.0:2376
```
从命令行重启服务：
```
sudo systemctl daemon-reload
sudo systemctl restart docker.service
```
重启服务后，设置环境变量 `DOCKER_HOST` 并尝试启动 `wp-env`：
```
export DOCKER_HOST=tcp://127.0.0.1:2376
wp-env start
```
现在您的环境应设置在 <code>http://localhost:8888</code>。
## 其他资源
- [@wordpress/env](https://www.npmjs.com/package/@wordpress/env)（官方文档）
- [Docker Desktop](https://docs.docker.com/desktop)（官方文档）
- [使用 wp-env 快速轻松地进行本地 WordPress 开发](https://developer.wordpress.org/news/2023/03/quick-and-easy-local-wordpress-development-with-wp-env/)（WordPress 开发者博客）
- [wp-env：简单的 WordPress 本地环境](https://make.wordpress.org/core/2020/03/03/wp-env-simple-local-environments-for-wordpress/)（Make WordPress Core 博客）
- [`wp-env` 基础示意图](https://excalidraw.com/#json=8Tp55B-R6Z6-pNGtmenU6,_DeBR1IBxuHNIKPTVEaseA)（Excalidraw）

150
docs/getting-started/devenv/get-started-with-wp-scripts.md Normal file
View File

@@ -0,0 +1,150 @@
### 高级配置
虽然 `wp-scripts` 提供了可靠的默认配置，但在某些情况下可能需要更专业的设置。好消息是 `wp-scripts` 具有高度适应性。例如，您可以扩展和覆盖默认的 webpack 配置，从而能够添加加载器和插件，或修改构建流程的几乎所有环节。这种灵活性确保当项目规模扩大或需求变化时，`wp-scripts` 能够根据您不断变化的需求进行定制。
有关所有配置选项，请参阅 `wp-scripts` 的[包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
## 扩展资源
- [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/)（官方文档）
- [webpack 与 WordPress 包的交互机制](https://developer.wordpress.org/news/2023/04/how-webpack-and-wordpress-packages-interact/)（WordPress 开发者博客）
# 开始使用 wp-scripts
[`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) 包（通常简称为 `wp-scripts`）是一组配置文件和脚本，主要旨在标准化和简化需要 JavaScript 构建步骤的 WordPress 项目的开发流程。
JavaScript 构建步骤指的是将 JavaScript 源代码和相关资源转换、打包并优化为适合生产环境格式的过程。这些构建步骤通常会将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的版本，还可以将多个文件打包成一个，通过代码压缩减小文件大小，并执行各种其他任务来优化代码。
在为区块编辑器开发时，您通常会使用 ESNext 和 JSX，区块编辑器手册中的所有示例都采用这些语法。学习如何设置构建步骤至关重要，但配置 [webpack](https://webpack.js.org/)、[Babel](https://babeljs.io/) 和 [ESLint](https://eslint.org/) 等必要工具可能变得复杂。这正是 `wp-scripts` 的用武之地。
以下是 `wp-scripts` 能够实现的功能：
- **代码编译：** 使用 Babel 将现代 JavaScript（ESNext 和 JSX）转换为与大多数浏览器兼容的代码
- **资源打包：** 使用 webpack 将多个 JavaScript 文件合并为单一包以提升性能
- **代码检查：** 提供 ESLint 配置，帮助确保代码质量并符合编码规范
- **代码格式化：** 集成 Prettier 实现自动化代码风格统一，保持项目间代码格式一致性
- **Sass 编译：** 将 Sass（.scss 或 .sass）文件转换为标准 CSS
- **代码压缩：** 为生产环境缩减 JavaScript 代码体积，确保更快的页面加载速度
该软件包封装了现代 WordPress JavaScript 开发中大量初始设置、配置和样板代码，让您可以专注于构建区块和区块编辑器扩展功能。
## 快速开始
<div class="callout callout-tip">
如果您使用 <a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/"><code>@wordpress/create-block</code></a> 包来搭建创建和注册区块所需的文件结构，您将同时获得现代化的 JavaScript 构建设置（使用 <code>wp-scripts</code>）且无需任何配置，因此无需担心安装 <code>wp-scripts</code> 或注册资源。详细信息请参阅<a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/">开始使用 <code>create-block</code></a>。
</div>
### 安装步骤
请确保计算机已安装 Node.js 和 `npm`。若未安装，请查阅 [Node.js 开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development-environment/)指南。
接着创建项目文件夹，确保其中包含 `package.json` 文件、`build` 文件夹和 `src` 文件夹。`src` 文件夹内还需包含 `index.js` 文件。
如果尚未创建 `package.json` 文件，请在终端中进入项目文件夹并运行 `npm init` 命令。交互式提示将引导您完成设置步骤。您可以按需配置，但当询问 "entry point"（入口点）时，请输入 `build/index.js`。
当然，使用 `wp-scripts` 设置项目有多种方式，但这是区块编辑器手册全程推荐的实践方案。
最后，通过以下命令将 `wp-scripts` 包安装为开发依赖项：
```bash
npm install @wordpress/scripts --save-dev
```
安装完成后，您的项目文件夹结构应如下所示：
```bash
示例项目文件夹/
├── build/
├── node_modules/ (自动生成)
├── src/
│ └── index.js
├── package-lock.json (自动生成)
└── package.json
```
### 基础用法
安装完成后，您可以通过在 `package.json` 文件的脚本部分引用 `wp-scripts` 提供的预定义脚本来运行它们。以下是一个示例：
```json
{
"scripts": {
"start": "wp-scripts start",
"build": "wp-scripts build"
}
}
```
随后可以使用 `npm run {脚本名称}` 命令来运行这些脚本。
### 使用 `wp-scripts` 的构建流程
您最常使用的两个脚本是 `start` 和 `build`，因为它们负责构建步骤。有关所有选项，请参阅[包文档](https://developer.wordpress.org/block-editor/packages/packages-scripts/)。
在开发项目时，使用 `npm run start` 命令。这将启动开发服务器，并在检测到任何更改时自动重新构建项目。请注意，`build/index.js` 中的编译代码不会被优化。
当您准备部署项目时，使用 `npm run build` 命令。这会优化您的代码，使其适合生产环境。
构建完成后，您将看到在 `build/index.js` 中创建的编译后的 JavaScript 文件。
构建过程中还会生成一个 `build/index.asset.php` 文件，其中包含依赖项数组和一个版本号（用于缓存清除）。请注意，如果没有使用 `wp-scripts` 构建流程注册块，您需要手动创建 `*.asset.php` 依赖文件（参见[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-no-build-e621a6)）。
### 加载资源
如果您通过 `register_block_type` 注册块，`block.json` 中定义的脚本将自动加载（参见[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)）。
要在编辑器或其他上下文中手动加载文件，可以参考[在编辑器中加载资源](https://developer.wordpress.org/block-editor/how-to-guides/enqueueing-assets-in-the-editor/)指南获取更多信息。以下是一个典型的实现示例：
```php
/**
* 加载编辑器资源。
*/
function example_project_enqueue_editor_assets() {
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');
wp_enqueue_script(
'example-editor-scripts',
plugins_url( 'build/index.js', __FILE__ ),
$asset_file['dependencies'],
$asset_file['version']
);
}
add_action( 'enqueue_block_editor_assets', 'example_project_enqueue_editor_assets' );
```
这里有一个在编辑器中手动加载文件的[示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8)。
## 后续步骤
虽然 `start` 和 `build` 是两个最常用的脚本，但 `wp-scripts` 还提供了其他几个有用的工具，值得探索。以下是一些示例。
### 保持代码质量
为了帮助开发者提高代码质量，`wp-scripts` 预配置了 ESLint 和 Prettier 等工具。ESLint 确保您的 JavaScript 遵循最佳实践和 [WordPress 编码标准](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/)，而 Prettier 会自动格式化您的代码。可用的脚本包括：
```json
{
"scripts": {
"format": "wp-scripts format",
"lint:css": "wp-scripts lint-style",
"lint:js": "wp-scripts lint-js",
}
}
```
定期对代码进行格式化和检查可以确保代码功能正常、清晰且易于维护，无论是您自己还是其他开发者都能受益。
### 运行测试
除了编写代码，验证其功能也至关重要。`wp-scripts` 包含了 [Jest](https://jestjs.io/)（一个 JavaScript 测试框架）以及端到端测试和单元测试脚本：
```json
{
"scripts": {
"test:e2e": "wp-scripts test-e2e",
"test:unit": "wp-scripts test-unit-js"
}
}
```
单元测试验证代码的独立单元（例如函数）是否按预期工作，而端到端测试通过模拟真实用户场景来评估整个项目，确保系统的所有部分无缝协作。

49
docs/getting-started/devenv/nodejs-development-environment.md Normal file
View File

@@ -0,0 +1,49 @@
# Node.js 开发环境
进行区块编辑器开发时，您需要准备 [Node.js](https://nodejs.org/en) 开发工具、代码编辑器以及本地 WordPress 环境（详见[区块开发环境](/docs/getting-started/devenv/README.md)）。Node.js（`node`）是一个开源运行时环境，可让您通过终端（也称为命令行界面 CLI 或 Shell）执行 JavaScript 代码。
安装 `node` 将自动包含 Node 包管理器（`npm`）和 Node 包执行工具（`npx`），这两个工具在区块和插件开发中会频繁使用。
Node 包管理器 ([`npm`](https://docs.npmjs.com/cli/v10/commands/npm)) 具有依赖管理和脚本执行等多重功能，是官方推荐的包管理工具，所有文档中均大量涉及其使用方法。
Node 包执行工具 ([`npx`](https://docs.npmjs.com/cli/v10/commands/npx)) 用于运行未全局安装的软件包命令，在使用 [`create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) 包搭建区块时尤为常用。
## Mac 和 Linux 系统安装 Node.js（通过 `nvm`）
推荐使用 [Node 版本管理器](https://github.com/nvm-sh/nvm)（`nvm`）安装 Node.js。通过该工具可安装并管理特定版本的 `node`，所有版本将本地化安装在用户目录中，有效避免全局权限问题。
以下是通过 `nvm` 安装 `node` 并设置区块开发推荐版本的快速指南，详见[完整安装指南](https://github.com/nvm-sh/nvm#installing-and-updating)。
1. 打开终端执行以下命令安装 `nvm`。macOS 系统默认未安装开发者工具，若出现提示请按指引安装。
```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
```
2. 关闭并重启终端
3. 在终端运行 `nvm install --lts` 安装最新的 [LTS](https://nodejs.org/en/about/previous-releases)（长期支持）版 Node.js
4. 在终端运行 `node -v` 和 `npm -v` 验证安装的 `node` 与 `npm` 版本
如需安装特定版本 `node`，可运行 `nvm install 18` 安装 18 版本，通过 `nvm use [版本号]` 切换不同版本。更多操作详见 `nvm` [使用指南](https://github.com/nvm-sh/nvm#usage)。
部分项目（如 Gutenberg）包含 [`.nvmrc`](https://github.com/WordPress/gutenberg/blob/trunk/.nvmrc) 文件来指定所需 `node` 版本。此时运行 `nvm use` 将自动选择对应版本。若该版本未安装，系统会提示需要安装的版本号，请依次运行 `nvm install [版本号]` 和 `nvm use`。
## Windows 及其他系统安装 Node.js
您可直接从 [Node.js 官网下载安装包](https://nodejs.org/en/download/)，推荐选择最新版本。系统提供 Windows 和 Mac 安装程序，以及 Linux 二进制文件。
微软官方还提供了 [详细指南](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows#install-nvm-windows-nodejs-and-npm)，说明如何在 Windows 和 WSL 中安装 `nvm` 与 Node.js。
## 故障排除
若安装 `node` 时出现 `zsh: command not found: nvm` 错误，可能需要创建默认配置文件。
macOS 系统默认 Shell 为 `zsh`，请在终端运行 `touch ~/.zshrc` 创建配置文件（若文件已存在亦可直接运行）。Ubuntu 系统（含 WSL）默认使用 `bash`，请改用 `touch ~/.bashrc` 命令。完成后重复步骤 2-4。
最新版 `node` 适用于多数开发项目，但请注意某些软件包和工具可能存在特定版本要求。若遇到问题，可能需要安装并使用旧版 `node`。同时请确认项目是否包含 `.nvmrc` 文件，并使用其中指定的 `node` 版本。
## 扩展资源
- [Node.js](https://nodejs.org/en)（官方文档）
- [Node 版本管理器](https://github.com/nvm-sh/nvm)（官方文档）
- [为本地 WordPress 开发安装 Node.js 和 npm](https://learn.wordpress.org/tutorial/installing-node-js-and-npm-for-local-wordpress-development/)（Learn WordPress 教程）

214
docs/getting-started/faq.md Normal file
View File

@@ -0,0 +1,214 @@
### 能否为我的站点停用古腾堡编辑器？
存在一种“经典”区块，其功能与当前编辑器几乎完全相同，只是以区块形式呈现。
另外还有[经典编辑器插件](https://wordpress.org/plugins/classic-editor/)，可恢复旧版编辑器，详情请参阅该插件说明。WordPress核心团队已承诺[在2021年12月之前](https://make.wordpress.org/core/2018/11/07/classic-editor-plugin-support-window/)持续支持经典编辑器插件。
### 自定义TinyMCE按钮在古腾堡中如何运作？
自定义TinyMCE按钮在“经典”区块中仍然有效，该区块是当前经典编辑器的区块化版本。
古腾堡配备了全新的通用插入工具，可让您访问所有可用区块，支持搜索功能，并按最近使用时间和分类排序。这一插入工具为每个向编辑器添加内容的插件提供了公平的竞争环境，并提供了统一的操作界面供用户学习使用。
### 短代码在古腾堡中如何运作？
短代码仍保持现有功能不变。
但我们认为区块是`[shortcode]`的进化形态。您无需手动输入代码，只需通过通用插入面板选择区块，即可获得更丰富的配置界面和预览效果。我们建议用户最终将短代码升级为区块。
### 是否应将短代码转换为内容区块？
我们认为基于以下多重因素（包括但不限于）应该转换：
- 区块内置可视化编辑功能，为网站建设提供更丰富、更动态的体验
- 区块本质上是HTML格式，不会在前端保留浏览器无法识别的内容。相比之下，如果您停用了支持短代码的插件，前端会显示异常视觉效果（通常以纯文本形式显示短代码）
- 随着区块目录的推出，区块将比短代码更易被发现，让更多用户获得更丰富的功能
最终，区块设计旨在直观呈现最终视觉效果，随着5.5版本区块目录的推出，这将成为用户在WordPress中发现和插入内容的预期标准方式。
## 其他事项
### 古腾堡是否充分考虑无障碍访问？
无障碍设计并非事后补充。目前古腾堡并非所有功能都实现完全无障碍。您可在此处查看已记录的问题。我们深知WordPress服务所有用户，无障碍设计关乎包容性，这是我们的核心价值。
如果您愿意为古腾堡的无障碍改进贡献力量，我们始终欢迎更多测试者和贡献者。
### 数据如何存储？我注意到HTML注释，其作用是什么？
如技术概述介绍中所述，我们的方法是在不破坏WordPress十五年来内容数据结构的前提下，对现有数据格式进行增强。换言之，这种格式优化优先考虑人类可读性（网页HTML文档）和跨平台渲染便利性，而非主要服务于编辑场景的机器便捷文件（文章元数据中的JSON格式）。
这种设计也赋予我们灵活性，可将那些本质上独立于内容流的区块（如可重用小组件或文章类型元素）存储在其他位置，仅保留其位置的标记引用。
建议您查阅古腾堡核心概念文档，深入了解该功能的运作机制。
### 如何通过PHP或JS将文章内容解析回区块？
JS方法：
```js
var blocks = wp.blocks.parse( postContent );
```
PHP方法：
```php
$blocks = parse_blocks( $post_content );
```
## 编辑体验
### 什么是“区块”？为何要使用它们？
经典WordPress编辑器是一个开放的文本窗口——它始终是绝佳的写作空白画布，但在构建包含图片、多媒体、社交媒体嵌入内容、投票及其他元素的文章与页面时，往往需要混合使用多种并不直观的操作方式：
- 通过媒体库/HTML处理图片、多媒体和授权文件
- 使用粘贴链接实现内容嵌入
- 通过短代码调用插件的特殊资源
- 使用特色图像设置文章/页面顶部图片
- 通过摘要字段设置副标题
- 通过小工具管理页面侧边内容
在思考这些使用场景并寻求直观统一的解决方案时，我们开始采用“区块”概念。上述所有元素均可转化为区块：易于检索理解，并能动态调整页面布局。区块概念极具潜力，经过精心设计后，能提供卓越的编辑发布体验。区块的终极目标是建立WordPress全新通用语言，构建连接用户与插件的新范式，取代短代码、小工具等传统内容类型——这些旧模式通常需要用户精通WordPress特性才能掌握。
### 写作体验如何？
Gutenberg的目标不仅是打造无缝的文章与页面构建体验，更致力于提供流畅的写作环境。欢迎访问[演示页面亲自体验](https://wordpress.org/gutenberg/)！
### Gutenberg基于TinyMCE开发吗？
并非如此。[TinyMCE](https://www.tinymce.com/)仅用于“经典”区块。
### Gutenberg支持键盘快捷键吗？
支持。快捷键非常丰富！可通过帮助模态窗查看所有可用快捷键。
具体操作：点击新编辑器右上角菜单中的“键盘快捷键”（或使用快捷键<kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>H</kbd>（Linux/Windows系统）/<kbd>⌃</kbd><kbd>⌥</kbd><kbd>H</kbd>（macOS系统））。
以下动画演示如何查找和使用键盘快捷键：
![展示如何访问键盘快捷键的GIF](https://make.wordpress.org/core/files/2020/07/keyboard-shortcuts.gif)
### Gutenberg支持分栏功能吗？
支持，Gutenberg提供分栏区块。
### Gutenberg支持嵌套区块吗？
支持多层嵌套——区块内可包含子区块。详见[嵌套区块教程](https://developer.wordpress.org/block-editor/tutorials/block-tutorial/nested-blocks-inner-blocks/)。
### 能否通过拖放调整区块顺序？
支持拖放区块进行重新排序。
## 开发体验
### 如何创建自定义区块？
建议从[创建区块教程](https://developer.wordpress.org/block-editor/getting-started/create-block/)开始学习。
### Gutenberg支持前端编辑文章/页面吗？
不支持。Gutenberg主要设计为替代传统文章/页面编辑界面。需注意的是，前端编辑常被误解为编辑器界面与前端完全一致。Gutenberg允许主题通过自定义区块并为编辑器提供对应样式来实现类似效果。由于内容需要适配多种场景（从桌面端、移动端到全文订阅和联合发布平台），我们认为仅基于单一前端体验进行内容创作并非理想方案。
### 鉴于Gutenberg基于JavaScript开发，传统元框（PHP）如何兼容？
请参阅[元框教程](https://developer.wordpress.org/block-editor/how-to-guides/metabox/)了解如何在新版区块编辑器中兼容元框。
# 常见问题解答
以下是古腾堡项目过去几年开发过程中积累的一系列问题。如果您有任何希望得到解答并纳入本文档的问题，[请直接在GitHub上提交问题](https://github.com/WordPress/gutenberg/issues)。我们非常乐意解答那些未曾考虑到的问题。如需回顾历史背景，请查阅Matt于2018年11月发布的文章[《WordPress 5.0：古腾堡常见问题解答》](https://ma.tt/2018/11/a-gutenberg-faq/)。
## 古腾堡项目
### 什么是古腾堡？
“古腾堡”是为WordPress创建全新编辑器体验的项目代号——贡献者自2017年1月启动该项目，这是WordPress近年来最具颠覆性的变革之一。其核心理念是采用“区块”模式来编写和设计文章与页面。这将成为WordPress未来升级的基石，包括将区块功能从内容设计延伸至全站设计。总体目标是简化WordPress新用户的操作体验——涵盖内容创作、编辑、发布及网页设计的全流程。该编辑器致力于让用户更直观地预览发布后的内容呈现效果。项目启动时的核心目标如下：
> 编辑器将致力于打造全新的页面构建体验，让富媒体内容创作变得轻松自如。通过“区块”功能，实现目前需要短代码、自定义HTML或“神秘拼盘”式嵌入操作才能完成的效果。
关键要点包括：
- 布局精美的内容创作是WordPress的核心优势
- 采用区块交互模式，可将多重操作界面统一整合。用户无需掌握短代码和自定义HTML的编写，也无需通过粘贴URL来嵌入媒体，通过统一可靠的操作流程即可插入各类内容
- “神秘拼盘”指软件中需要用户自行探索的隐藏功能。WordPress已支持大量区块和30多种嵌入内容，现在要让这些功能浮出水面
古腾堡项目在WordPress组织下的[GitHub平台](https://github.com/WordPress/gutenberg)进行开发。自WordPress 5.0起，区块编辑器已集成至核心程序。若想体验古腾堡的新功能，可[在插件库获取测试版](https://wordpress.org/plugins/gutenberg/)。
### 长期发展规划是什么？
根据[官方路线图](https://wordpress.org/about/roadmap/)，古腾堡分为四个发展阶段（截至本文撰写时正处于第二阶段）：
1. 更便捷的编辑——自WordPress 5.0起已实现，持续优化中
2. 全面定制——全站编辑、区块模式、区块目录、区块主题
3. 协同创作——更直观的多用户协作体验
4. 多语言支持——原生多语言站点解决方案
### 项目启动于何时？
编辑器专项于2017年初启动，前三个月主要进行设计规划、原型构建与测试验证，为项目实施奠定基础。首个测试插件于2017年6月欧洲WordCamp大会期间发布。
### 何时并入WordPress核心？
古腾堡于2018年12月首次并入[WordPress 5.0](https://wordpress.org/news/2018/12/bebo/)。完整版本对应关系请参阅[WordPress中的版本记录](https://developer.wordpress.org/block-editor/principles/versions-in-wordpress/)。
### WordPress已是全球最流行的发布平台，为何还要改造编辑器？
编辑器是WordPress日常使用最频繁的核心模块，在封闭环境中打磨区块体验能获得最佳效果。作为开源项目，我们坚信WordPress必须持续创新，让核心体验始终直观易用。古腾堡作为社区项目正承载着这一使命，我们期待共同实现这个目标。如果您愿意参与测试、贡献代码或反馈建议，欢迎[在GitHub分享您的发现](https://github.com/WordPress/gutenberg/issues)。
### 插件如何扩展古腾堡界面？
我们想要强调的主要扩展点是创建新块。通过插件可以将区块添加到区块编辑器中，请参阅[构建你的第一个区块教程](https://developer.wordpress.org/block-editor/getting-started/tutorial/)开始学习。
### 自定义文章类型是否仍受支持？
是的。自定义文章类型可以通过多种方式利用古腾堡。计划允许它们指定支持的区块，并为文章类型定义默认区块。目前尚未实现，但如果文章类型禁用了内容字段，页面底部的“高级”部分将填充页面。
## 样式
### 主题能否为区块设置样式？
可以。区块可以提供自己的样式，主题可以在此基础上添加或覆盖样式，或者它们完全不提供样式，完全依赖主题提供的样式。
### 区块样式在前端和后端如何工作？
区块能够提供基础的结构性CSS样式，主题可以在此基础上添加样式。一些区块，如分隔符（`<hr/>`），可能不需要任何前端样式，而其他区块，如图库，则需要一些样式。
其他功能，如新的宽幅和全宽对齐选项，仅仅是应用于支持此对齐方式的区块的CSS类。我们正在研究主题如何选择加入此功能，例如使用`add_theme_support`。
这目前仍在开发中，我们建议查阅[基于区块的主题文档](https://developer.wordpress.org/themes/block-themes/)以了解更多信息。
### 什么是区块变体？它们与区块样式相同吗？
不，[区块变体](/docs/reference-guides/block-api/block-variations.md)是单个基础区块的不同版本，共享相似的功能，但在实现或设置（属性、内部区块等）上略有不同。区块变体对用户是透明的，一旦注册了区块变体，它将显示为一个新块。例如，`embed`区块注册了不同的区块变体，以嵌入来自特定提供商的内容。
同时，[区块样式](/docs/reference-guides/filters/block-filters.md#block-style-variations)允许您为现有区块提供替代样式，它们通过向区块包装器添加`className`来工作。一旦区块注册了区块样式，区块样式选择器将出现在其侧边栏中，用户可以在不同的注册样式之间进行选择。
### 编辑器样式如何工作？
常规的编辑器样式是选择加入的，在大多数情况下按原样工作。主题还可以通过以下钩子加载额外的样式表：
```php
function gutenbergtheme_editor_styles() {
wp_enqueue_style( 'gutenbergtheme-blocks-style', get_template_directory_uri() . '/blocks.css');
}
add_action( 'enqueue_block_editor_assets', 'gutenbergtheme_editor_styles' );
```
_参见：_[编辑器样式](/docs/how-to-guides/themes/theme-support.md#editor-styles)
## 兼容性
### 古腾堡支持哪些浏览器？
古腾堡在现代浏览器中运行。
[支持的浏览器列表可以在Make WordPress手册中找到](https://make.wordpress.org/core/handbook/best-practices/browser-support/)。术语“现代浏览器”通常指的是每个主要浏览器的_当前版本及前两个版本_。
自WordPress 5.8起，古腾堡不再支持任何版本的Internet Explorer。
### 我需要担心古腾堡会让我的插件过时吗？
古腾堡的目标不是让任何人失业，而是推动WordPress的发展，以便未来为每个人带来更多的商业机会。
除了实现丰富的文章和页面构建体验外，一个元目标是_推动WordForward作为一个平台向前发展_，不仅通过现代化用户界面，还通过现代化基础架构。
我们意识到这是一个巨大的变化。我们也认为插件将会有许多新的机会。WordPress可能会附带一系列基础区块，但高度定制化的高级插件仍有充足的空间来增强现有区块或添加新块。

12
docs/getting-started/fundamentals/README.md Normal file
View File

@@ -0,0 +1,12 @@
# 区块开发基础
本节将介绍区块开发中最核心的相关概念。通过以下链接深入了解：
1. **[区块的文件结构](https://developer.wordpress.org/block-editor/getting-started/fundamentals/file-structure-of-a-block):** 解析构成区块插件的每个文件用途、文件间的关联关系及其在区块输出中的作用
1. **[`block.json`配置文件](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json):** 如何通过`block.json`元数据定义区块，并详解该文件的关键属性（如`attributes`和`supports`）
1. **[区块注册机制](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block):** 如何在服务端与客户端完成区块注册
1. **[区块包装器](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper):** 如何为区块标记包装器配置正确的属性参数
1. **[编辑器中的区块](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-in-the-editor):** 区块作为React组件在区块编辑器中的加载原理与结构概述
1. **[区块的标记表示](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block):** 区块在数据库、主题模板和模式中的呈现方式
1. **[区块的静态与动态渲染](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering):** 区块如何通过动态或静态方式生成前端输出
1. **[区块编辑器中的JavaScript](https://developer.wordpress.org/block-editor/getting-started/fundamentals/javascript-in-the-block-editor):** 为区块编辑器开发时如何运用现代JavaScript技术

169
docs/getting-started/fundamentals/block-in-the-editor.md Normal file
View File

@@ -0,0 +1,169 @@
## 补充资源
- [WordPress 组件故事书](https://wordpress.github.io/gutenberg/?path=/docs/docs-introduction--page)
- [@wordpress/block-editor](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/)
- [@wordpress/components](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/)
- [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
- [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)
# 编辑器中的区块
区块编辑器是一个React单页应用程序（SPA）。编辑器中的每个区块都是通过React组件显示的，该组件定义在客户端[注册区块](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registering-a-block-with-javascript-client-side)时所用设置对象的`edit`属性中。
区块的`Edit` React组件接收到的`props`对象包含：
- **[`attributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes)：** 包含区块所有属性的对象
- **[`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes)：** 用于更新属性对象的方法
- **[`isSelected`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#isselected)：** 表示区块当前是否被选中的布尔值
WordPress提供了许多内置标准组件，可用于在编辑器中定义区块界面。这些内置组件可通过以下软件包获取：[`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) 和 [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/)。
<div class="callout">
WordPress Gutenberg项目使用 <a href="https://wordpress.github.io/gutenberg/?path=/docs/docs-introduction--page">Storybook</a> 来记录WordPress软件包中可用的用户界面组件。
</div>
区块工具栏或设置侧边栏中的自定义设置控件也可以通过这个`Edit` React组件使用内置组件来定义，例如：
- [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
- [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)
## 内置组件
[`@wordpress/components`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-components/) 软件包包含一个通用WordPress组件库，用于为区块编辑器和WordPress仪表盘创建常见的UI元素。该软件包中最常用的一些组件包括：
- [`TextControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-textcontrol--docs)
- [`Panel`](https://wordpress.github.io/gutenberg/?path=/docs/components-panel--docs)
- [`ToggleControl`](https://wordpress.github.io/gutenberg/?path=/docs/components-togglecontrol--docs)
- [`ExternalLink`](https://wordpress.github.io/gutenberg/?path=/docs/components-externallink--docs)
[`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/) 软件包包含一个用于区块编辑器的组件和钩子库，包括用于定义区块自定义设置控件的组件。该软件包中最常用的一些组件包括：
- [`RichText`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md)
- [`BlockControls`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-editor/src/components/block-controls)
- [`InspectorControls`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md)
- [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md)
<div class="callout callout-info">
<a href="https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/"><code>@wordpress/block-editor</code></a> 软件包还提供了创建和使用独立区块编辑器的工具。
</div>
在区块编辑器中使用组件时，一个良好的工作流程是：
- 从WordPress软件包中导入组件
- 以JSX格式将组件的对应代码添加到项目中
- 大多数内置组件将用于设置[区块属性](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#using-attributes-to-store-block-data)，因此在`block.json`中定义必要的属性，并在组件中创建事件处理程序以使用`setAttributes`更新这些属性
- 根据需要调整代码以进行序列化并存储在数据库中
## 区块控制项：区块工具栏与设置侧边栏
为简化区块定制并确保一致的用户体验，系统内置了多种UI模式来辅助生成区块的编辑器预览界面。
下图详细展示了选中段落区块时的区块工具栏与设置侧边栏。
![展示选中段落区块时的区块工具栏与设置侧边栏示意图](https://developer.wordpress.org/files/2023/12/block-toolbar-settings-sidebar.png)
### 区块工具栏
当用户选中区块时，选定区块上方会显示包含多个控制按钮的工具栏。部分区块级控件会自动包含其中，您也可以自定义工具栏以添加针对特定区块类型的控件。若区块类型`Edit`函数的返回值包含`BlockControls`元素，这些控件将显示在选定区块的工具栏中。
```jsx
export default function Edit( { className, attributes: attr, setAttributes } ) {
const onChangeContent = ( newContent ) => {
setAttributes( { content: newContent } );
};
const onChangeAlignment = ( newAlignment ) => {
setAttributes( {
alignment: newAlignment === undefined ? 'none' : newAlignment,
} );
};
return (
<div { ...useBlockProps() }>
<BlockControls>
<ToolbarGroup>
<AlignmentToolbar
value={ attr.alignment }
onChange={ onChangeAlignment }
/>
</ToolbarGroup>
</BlockControls>
<RichText
className={ className }
style={ { textAlign: attr.alignment } }
tagName="p"
onChange={ onChangeContent }
value={ attr.content }
/>
</div>
);
}
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-toolbar-ab967f/src/edit.js)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-toolbar-ab967f)。_
请注意：`BlockControls`仅在区块被选中且处于可视化编辑模式时可见。在HTML编辑模式下编辑区块时不会显示`BlockControls`。
### 设置侧边栏
设置侧边栏用于显示使用频率较低的设置项或需要更多屏幕空间的设置项。该区域**仅应用于区块级设置**，并在选中区块时显示。
若设置项仅影响区块内选定的内容（如文本"加粗"功能），**请勿将其置于设置侧边栏中**，而应使用工具栏。设置侧边栏在HTML编辑模式下仍会显示，因此应仅包含区块级设置项。
与渲染工具栏类似，若在区块类型`Edit`函数的`return`值中包含`InspectorControls`组件，这些控件将显示在设置侧边栏区域。
```jsx
export default function Edit( { attributes, setAttributes } ) {
const onChangeBGColor = ( hexColor ) => {
setAttributes( { bg_color: hexColor } );
};
const onChangeTextColor = ( hexColor ) => {
setAttributes( { text_color: hexColor } );
};
return (
<div { ...useBlockProps() }>
<InspectorControls key="setting">
<div>
<fieldset>
<legend className="blocks-base-control__label">
{ __( '背景颜色', 'block-development-examples' ) }
</legend>
<ColorPalette // Gutenberg标准颜色选择器元素标签
onChange={ onChangeBGColor } // 变更事件回调函数
/>
</fieldset>
<fieldset>
<legend className="blocks-base-control__label">
{ __( '文字颜色', 'block-development-examples' ) }
</legend>
<ColorPalette
onChange={ onChangeTextColor }
/>
</fieldset>
</div>
</InspectorControls>
<TextControl
__nextHasNoMarginBottom
__next40pxDefaultSize
value={ attributes.message }
onChange={ ( val ) => setAttributes( { message: val } ) }
style={ {
backgroundColor: attributes.bg_color,
color: attributes.text_color,
} }
/>
</div>
);
}
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/settings-sidebar-82c525/src/edit.js)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/settings-sidebar-82c525)。_
当选中多个同类型区块时，工具栏和侧边栏中渲染的区块控制项将同时生效。
<div class="callout callout-note">
对于常见定制设置（包括颜色、边框、间距等），您可依赖<a href="https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#enable-ui-settings-panels-for-the-block-with-supports">区块支持功能</a>而非自定义方案。区块支持功能提供与其他核心区块功能一致的标准化UI界面。
</div>

134
docs/getting-started/fundamentals/block-json.md Normal file
View File

@@ -0,0 +1,134 @@
## 补充资源
- [block.json 结构图](https://excalidraw.com/#json=v1GrIkGsYGKv8P14irBy6,Yy0vl8q7DTTL2VsH5Ww27A)
- [属性关系图](https://excalidraw.com/#json=pSgCZy8q9GbH7r0oz2fL1,MFCLd6ddQHqi_UqNp5ZSgg)
# block.json
`block.json` 文件通过使用相同的 JSON 格式区块定义，在服务端和客户端（区块编辑器）上注册区块，从而简化了定义和注册区块的过程。
下图详细说明了 `block.json` 文件的基本结构。
[![打开 block.json 图示](https://developer.wordpress.org/files/2023/11/block-json.png)](https://developer.wordpress.org/files/2023/11/block-json.png "打开 block.json 图示")
<div class="callout callout-info">
要查看完整的区块示例及其相关的 <a href="https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-supports-6aa4dd/src/block.json"><code>block.json</code></a> 文件，请访问 <a href="https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd">区块开发示例</a> GitHub 仓库。
</div>
除了简化区块注册外，使用 `block.json` 还有[诸多优势](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file)，包括性能提升。
[block.json 中的元数据](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)文档提供了关于可在区块的 `block.json` 文件中使用的所有属性的完整指南。本文将介绍最常用的选项，这些选项允许你指定：
- 区块的基本元数据
- 控制区块功能、外观和输出的文件
- 数据在区块内的存储方式
- 用户界面中区块的设置面板
## 区块的基本元数据
使用 `block.json` 属性，你可以定义区块的唯一标识方式以及在区块编辑器中显示的信息。这些属性包括：
- **[`apiVersion`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#api-version)：** 指定区块使用的 [API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/) 版本。除非有特定要求，否则请使用最新版本。
- **[`name`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#name)：** 区块的唯一名称，包括命名空间（例如 `my-plugin/my-custom-block`）。
- **[`title`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#title)：** 区块的显示标题，在插入器中显示。
- **[`category`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#category)：** 区块在插入器中出现的分类。常见分类包括 `text`、`media`、`design`、`widgets` 和 `theme`。
- **[`icon`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#icon)：** 在插入器中代表区块的图标。可以是 [Dashicon](https://developer.wordpress.org/resource/dashicons) 标识或自定义 SVG 图标。
- **[`description`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#description)：** 区块的简短描述，提供比标题更多的上下文信息。
- **[`keywords`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#keywords)：** 关键词数组，帮助用户在搜索时找到区块。
- **[`textdomain`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#text-domain)：** 区块的文本域，用于国际化。
## 控制区块行为、输出或样式的文件
`block.json` 文件还允许你指定区块功能所需的关键文件：
- **[`editorScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-script)：** 仅用于区块编辑器的 JavaScript 文件。
- **[`editorStyle`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-style)：** 用于区块编辑器内样式设置的 CSS 文件。
- **[`script`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#script)：** 在区块编辑器和前端均可加载的 JavaScript 文件。
- **[`style`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style)：** 在区块编辑器和前端均可应用的 CSS 文件。
- **[`viewScript`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#view-script)：** 仅用于前端的 JavaScript 文件。
对于所有这些属性，你可以提供[文件路径](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#wpdefinedpath)（以 `file:` 开头）、使用 `wp_register_script` 或 `wp_register_style` 注册的[句柄](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#wpdefinedasset)，或结合这两种选项的数组。
此外，[`render`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render) 属性（[在 WordPress 6.1 中引入](https://make.wordpress.org/core/2022/10/12/block-api-changes-in-wordpress-6-1/)）指定了一个 PHP 模板文件的路径，该文件负责生成[动态渲染](/docs/getting-started/fundamentals/static-dynamic-rendering.md)区块的前端标记。如果未向 `register_block_type()` 函数提供 `$render_callback` 函数，则使用此方法。
## 使用区块 `attributes` 存储数据
区块[属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#attributes)是分配给区块的设置或数据。它们可以决定区块的各个方面，例如其内容、布局、样式以及需要随区块结构存储的任何其他特定信息。如果用户更改了区块（例如修改字体大小），您需要一种方法来保留这些更改。属性正是解决方案。
在注册新的区块类型时，`block.json` 的 `attributes` 属性描述了区块所需的自定义数据以及这些数据在数据库中的存储方式。这使得区块编辑器能够正确解析这些值，并将 `attributes` 传递给区块的 `Edit` 组件和 `save` 函数。
以下是在 `block.json` 中定义的三个属性的示例：
```json
"attributes": {
"fallbackCurrentYear": {
"type": "string"
},
"showStartingYear": {
"type": "boolean"
},
"startingYear": {
"type": "string"
}
},
```
区块使用包含类似 JSON 特定属性的 HTML 样式注释标签进行“界定”。这些界定符使得在渲染文章内容或在区块编辑器中编辑文章时能够识别区块边界并解析区块属性。
以下代码示例展示了区块界定符中定义的属性。
```html
<!-- wp:block-development-examples/copyright-date-block-09aac3 {"fallbackCurrentYear":"2023","showStartingYear":true,"startingYear":"2020"} -->
<p class="wp-block-block-development-examples-copyright-date-block-09aac3">© 2020–2023</p>
<!-- /wp:block-development-examples/copyright-date-block-09aac3 -->
```
默认情况下，所有属性都会被序列化并存储在区块的界定符中，但这可以根据您的需求进行配置。查看[理解区块属性](https://developer.wordpress.org/news/2023/09/understanding-block-attributes/)文章以了解更多信息。
### 读取和更新属性
这些[属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#attributes)会传递给区块的 `Edit` React 组件以在区块编辑器中显示，传递给 `save` 函数以生成存储在数据库中的标记，并传递给区块的任何服务器端渲染定义。
`Edit` 组件独特地具有通过 [`setAttributes`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#setattributes) 函数修改这些属性的能力。
下图详细说明了在典型区块中属性是如何存储、读取和更新的。
[![打开属性图表图像](https://developer.wordpress.org/files/2023/11/attributes.png)](https://developer.wordpress.org/files/2023/11/attributes.png "打开属性图表图像")
_在此[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/copyright-date-block-09aac3)中查看属性如何传递给 [`Edit`](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/edit.js) 组件、[`save`](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/save.js) 函数和 [`render.php`](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/copyright-date-block-09aac3/src/render.php)。_
有关属性以及如何在自定义区块中使用它们的更多信息，请访问[属性 API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) 参考页面。
## 使用区块支持启用设置和样式
许多区块（包括核心区块）提供类似的定制选项，例如背景颜色、文本颜色和内边距调整。
`block.json` 中的 [`supports`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#supports) 属性允许区块声明支持一组这些常见的定制选项。启用后，区块用户可以直接从设置侧边栏调整颜色或内边距等内容。
利用这些预定义的区块支持有助于确保您的区块与核心区块行为一致，无需从头重新创建类似功能。
以下是在 `block.json` 中定义颜色支持的示例：
```json
"supports": {
"color": {
"text": true,
"link": true,
"background": true
}
}
```
使用区块支持会生成一组需要手动添加到[区块包装元素](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-wrapper/)的属性。这确保它们作为区块数据的一部分被正确存储，并在生成将交付给前端的区块标记时被考虑在内。
以下代码演示了通过启用区块支持生成的属性和 CSS 类如何存储在区块的标记表示中。
```html
<!-- wp:block-development-examples/block-supports-6aa4dd {"backgroundColor":"contrast","textColor":"accent-4"} -->
<p class="wp-block-block-development-examples-block-supports-6aa4dd has-accent-4-color has-contrast-background-color has-text-color has-background">Hello World</p>
<!-- /wp:block-development-examples/block-supports-6aa4dd -->
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/block-supports-6aa4dd/src/block.json)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd)。_
有关支持以及如何在自定义区块中使用它们的更多信息，请访问[支持 API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) 参考页面。

111
docs/getting-started/fundamentals/block-wrapper.md Normal file
View File

@@ -0,0 +1,111 @@
# 区块包装器
区块编辑器中的每个区块都包含在HTML包装器中，该包装器必须具备特定属性才能在编辑器和前端正常运作。作为开发者，我们可以直接操作这些标记，WordPress提供了诸如`useBlockProps()`等工具来修改添加到区块包装器的属性。
在使用自定义样式或[区块支持](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/)等功能时，确保区块包装器具有正确的属性尤为重要。
WordPress中的区块可以通过三种不同类型的标记来定义，每种标记都有其独特作用：
- **编辑器标记**：这是区块在区块编辑器中的可视化呈现。当通过[`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#registerblocktype)在客户端注册区块时，使用React的`Edit`组件来定义。
- **保存标记**：这是保存区块内容时存入数据库的标记。通过提供给`registerBlockType`的`save`函数来指定。如果区块不使用动态渲染，前端将显示此保存的标记。
- **动态渲染标记**：当区块内容需要动态生成时，将使用此标记。它在服务端定义，可以通过[`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/)中的`render_callback`函数，或`block.json`中指定的[`render.php`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#render)文件来定义。如果存在，此标记将覆盖任何已保存的标记，并用于区块的前端显示。
对于[`Edit`组件和`save`函数](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/)，重要的是使用标准DOM元素（如`<div>`）或将所有附加属性传递给原生DOM元素的React组件作为包装器元素。使用React片段（`<Fragment>`）或`<ServerSideRender>`组件不适用于这些包装器。
## 编辑器标记
[`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor)包提供的[`useBlockProps()`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#useblockprops)钩子，用于在`Edit`组件中定义区块的外部标记。
此钩子简化了多项任务，包括：
- 为区块的HTML结构分配唯一的`id`
- 添加各种可访问性和`data-`属性以增强功能和信息
- 包含反映区块自定义设置的类和内联样式。默认情况下包括：
- 用于通用区块样式的`wp-block`类
- 结合区块命名空间和名称的特定区块类，确保唯一且有目标的样式能力
在以下示例中，区块的编辑器标记在`Edit`组件中使用`useBlockProps()`钩子定义。
```js
const Edit = () => <p { ...useBlockProps() }>Hello World - 区块编辑器</p>;
registerBlockType( ..., {
edit: Edit
} );
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/src/index.js)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)。_
区块在区块编辑器中的标记可能如下所示，其中类和属性会自动应用：
```html
<p
tabindex="0"
id="block-4462939a-b918-44bb-9b7c-35a0db5ab8fe"
role="document"
aria-label="区块：Minimal Gutenberg Block ca6eda"
data-block="4462939a-b918-44bb-9b7c-35a0db5ab8fe"
data-type="block-development-examples/minimal-block-ca6eda"
data-title="Minimal Gutenberg Block ca6eda"
class="
block-editor-block-list__block
wp-block
is-selected
wp-block-block-development-examples-minimal-block-ca6eda
"
>Hello World - 区块编辑器</p>
```
在区块的`Edit`组件中，使用`useBlockProps()`钩子并通过传递参数来包含额外的类和属性。（参见[示例](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/edit.js)）
当使用`supports`属性启用功能时，任何相应的类或属性都会自动包含在`useBlockProps`返回的对象中。
## 保存标记
在数据库中保存标记时，重要的是将`useBlockProps.save()`返回的属性添加到区块的包装元素中。`useBlockProps.save()`确保区块类名正确渲染，同时还包括区块支持API注入的任何HTML属性。
考虑以下在客户端注册区块的代码。注意它如何定义编辑区块和将区块保存到数据库时应使用的标记。
```js
const Edit = () => <p { ...useBlockProps() }>Hello World - 区块编辑器</p>;
const save = () => <p { ...useBlockProps.save() }>Hello World - 前端</p>;
registerBlockType( ..., {
edit: Edit,
save,
} );
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/src/index.js)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)。_
区块在前端的标记可能如下所示，其中类会自动应用：
```html
<p class="wp-block-block-development-examples-minimal-block-ca6eda">Hello World – 前端</p>
```
如果要在区块的`save`函数中添加任何额外的类或属性，应将它们作为`useBlockProps.save()`的参数传递。（参见[示例](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/stylesheets-79a4c3/src/save.js)）
当为任何功能添加`supports`时，适当的类会添加到`useBlockProps.save()`钩子返回的对象中。在下面的示例中，文本和背景颜色类已添加到段落区块中。
```html
<p class="
wp-block-block-development-examples-block-supports-6aa4dd
has-accent-4-color
has-contrast-background-color
has-text-color
has-background
">Hello World</p>
```
生成此HTML的[示例区块](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/block-supports-6aa4dd)可在[区块开发示例](https://github.com/WordPress/block-development-examples)存储库中找到。
## 动态渲染标记
在动态区块中，前端标记在服务端渲染，您可以使用[`get_block_wrapper_attributes()`](https://developer.wordpress.org/reference/functions/get_block_wrapper_attributes/)函数输出必要的类和属性，就像在`save`函数中使用`useBlockProps.save()`一样。（参见[示例](https://github.com/WordPress/block-development-examples/blob/f68640f42d993f0866d1879f67c73910285ca114/plugins/block-dynamic-rendering-64756b/src/render.php#L11)）
```php
<p <?php echo get_block_wrapper_attributes(); ?>>
<?php esc_html_e( '动态渲染区块 – hello!!!', 'block-development-examples' ); ?>
</p>
```

95
docs/getting-started/fundamentals/file-structure-of-a-block.md Normal file
View File

@@ -0,0 +1,95 @@
## 附加资源
- [展示区块文件结构的示意图](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中打开构建输出示意图")

94
docs/getting-started/fundamentals/javascript-in-the-block-editor.md Normal file
View File

@@ -0,0 +1,94 @@
# 区块编辑器中的JavaScript开发
为区块编辑器开发区块通常涉及使用现代JavaScript（ESNext和JSX），本手册中的大多数示例都采用这些语法编写。
然而，这种形式的JavaScript必须转换为浏览器兼容的格式，因此需要构建步骤。这个过程会将JavaScript源代码及相关资源进行转换、打包和优化，最终生成适用于生产环境的格式。
## 使用构建流程的JavaScript开发
采用构建流程进行区块开发能充分发挥现代JavaScript的潜力，便于使用ESNext和JSX。
[ESNext](https://developer.mozilla.org/en-US/docs/Web/JavaScript/JavaScript_technologies_overview#standardization_process) 指的是JavaScript的最新语法和特性。[JSX](https://react.dev/learn/writing-markup-with-jsx) 是React项目开发的语法扩展，允许您编写类似HTML的JavaScript代码。
由于浏览器无法直接执行ESNext和JSX，这些语法必须转换为浏览器兼容的JavaScript。
[webpack](https://webpack.js.org/concepts/why-webpack/) 是一个可插拔工具，用于处理和打包JavaScript以实现浏览器兼容性。[Babel](https://babeljs.io/) 作为webpack的插件，能够将ESNext和JSX转换为标准JavaScript。
配置webpack和Babel可能具有挑战性，因此建议使用 [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) 工具包。该工具通过预配置两者来简化开发，您通常无需编写自定义的webpack或Babel配置。
入门指南请参阅 [wp-scripts入门指南](/docs/getting-started/devenv/get-started-with-wp-scripts.md)。
### `wp-scripts`概览
下图概述了使用`wp-scripts`工具包时的构建流程。该工具专为开发和生产环境的[标准配置](/docs/getting-started/devenv/get-started-with-wp-scripts.md#basic-usage)设计，开箱即用。
[![打开构建流程图](https://developer.wordpress.org/files/2023/11/build-process.png)](https://developer.wordpress.org/files/2023/11/build-process.png "打开构建流程图")
- **生产模式 (`npm run build`):** 在此模式下，`wp-scripts`会编译JavaScript并对输出进行压缩，以减小文件大小并提升浏览器加载速度。这非常适合将代码部署至生产环境。
- **开发模式 (`npm start`):** 此模式专为活跃开发定制。它会跳过压缩以便于调试，生成源码映射以优化错误追踪，并监听源文件变更。当检测到更改时，会自动重建受影响文件，让您可以实时查看更新。
`wp-scripts`工具包还支持使用JavaScript模块，允许代码分布在多个文件中，并在构建流程后生成精简的打包文件。[block-development-example](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8) GitHub代码库提供了一些优秀示例。
<div class="callout callout-tip">
大多数情况下无需自定义配置，但您可以在使用<code>wp-scripts</code>时提供<a href="https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#provide-your-own-webpack-config"><code>webpack.config.js</code></a>文件来调整构建流程以满足需求。
</div>
## 无构建流程的JavaScript开发
在某些特定场景下，无需构建流程即可将JavaScript集成到WordPress项目中可能是最直接的方法。这对于不涉及JSX或其他需要编译的高级JavaScript特性的项目尤为适用。
当您选择不使用构建流程时，需通过全局`wp`对象直接与WordPress的[JavaScript API](/docs/reference-guides/packages.md)进行交互。这意味着WordPress提供的所有方法和工具包都立即可用，但需要注意：您必须手动管理脚本依赖关系。这需要将每个对应工具包的[句柄](/docs/contributors/code/scripts.md)添加到您入队JavaScript文件的依赖数组中。
例如，假设您正在创建一个使用[`blocks`](/packages/blocks/README.md)工具包中的`registerBlockVariation`函数来注册新[区块变体](/docs/reference-guides/block-api/block-variations.md)的脚本。您必须在脚本的依赖数组中包含`wp-blocks`。这能确保在脚本执行时，`wp.blocks.registerBlockVariation`方法可用且已定义。
以下示例展示了在入队`variations.js`文件时定义`wp-blocks`依赖项：
```php
function example_enqueue_block_variations() {
wp_enqueue_script(
'example-enqueue-block-variations',
get_template_directory_uri() . '/assets/js/variations.js',
array( 'wp-blocks' ),
wp_get_theme()->get( 'Version' ),
false
);
}
add_action( 'enqueue_block_editor_assets', 'example_enqueue_block_variations' );
```
然后在`variations.js`文件中，您可以像这样为"媒体与文本"区块注册新变体：
```js
wp.blocks.registerBlockVariation(
'core/media-text',
{
name: 'media-text-custom',
title: '自定义媒体与文本',
attributes: {
align: 'wide',
backgroundColor: 'tertiary'
},
}
);
```
对于需要在区块编辑器中运行的脚本，请确保使用[`enqueue_block_editor_assets`](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/)钩子配合标准的[`wp_enqueue_script`](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)函数。
更多信息请参阅[在编辑器中加载资源](/docs/how-to-guides/enqueueing-assets-in-the-editor.md)。
<div class="callout callout-tip">
在编辑文章或使用站点编辑器时，打开浏览器开发者工具并在控制台中尝试运行<code>wp.data.select('core/editor').getBlocks()</code>。此命令将返回所有可用区块。
</div>
## 扩展资源
- [工具包参考](/docs/reference-guides/packages.md)
- [wp-scripts入门指南](/docs/getting-started/devenv/get-started-with-wp-scripts.md)
- [在编辑器中加载资源](/docs/how-to-guides/enqueueing-assets-in-the-editor.md)
- [WordPress工具包句柄](/docs/contributors/code/scripts.md)
- [JavaScript参考](https://developer.mozilla.org/en-US/docs/Web/JavaScript) | MDN Web文档
- [block-development-examples](https://github.com/WordPress/block-development-examples) | GitHub代码库
- [block-theme-examples](https://github.com/wptrainingteam/block-theme-examples) | GitHub代码库
- [webpack与WordPress工具包的交互原理](https://developer.wordpress.org/news/2023/04/how-webpack-and-wordpress-packages-interact/) | 开发者博客
- [构建流程图](https://excalidraw.com/#json=4aNG9JUti3pMnsfoga35b,ihEAI8p5dwkpjWr6gQmjuw)

51
docs/getting-started/fundamentals/markup-representation-block.md Normal file
View File

@@ -0,0 +1,51 @@
# 区块的标记表示
区块通过独特的[基于HTML的语法](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/#data-and-attributes)存储在数据库或HTML模板中，这种语法以HTML注释作为清晰的区块分隔符。这确保了区块标记在技术上是有效的HTML。
以下是定义区块标记的几条准则：
- 核心区块以`wp:`前缀开头，后跟区块名称（例如`wp:image`）。值得注意的是，`core`命名空间被省略。
- 自定义区块以`wp:`前缀开头，后跟区块命名空间和名称（例如`wp:namespace/name`）。
- 注释可以是单行、自闭合或HTML内容的包装器。
- 区块设置和属性以JSON对象形式存储在区块注释内部。
以下是图像区块的简化标记表示：
```html
<!-- wp:image {"sizeSlug":"large"} -->
<figure class="wp-block-image size-large">
<img src="source.jpg" alt="" />
</figure>
<!-- /wp:image -->
```
区块标记在区块编辑器和前端显示区块时都至关重要：
- WordPress在编辑器内分析区块标记以提取其数据，并向用户呈现可编辑版本。
- 在前端，WordPress再次解析标记以提取数据并渲染最终HTML输出。
<div class="callout callout-tip">
有关区块数据在WordPress中如何解析的深入探讨，请参阅<a href="https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/">数据流</a>文章。
</div>
当区块保存时，会执行`save`函数（在[客户端注册区块](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side)时定义）以生成存储在数据库中的标记，并用区块分隔符注释包裹。对于动态渲染的区块（通常将`save`设置为`null`），仅保存带有区块属性的占位符注释。
以下是动态渲染区块（`save` = `null`）的标记表示。请注意，除了注释外没有HTML标记。
```html
<!-- wp:latest-posts {"postsToShow":4,"displayPostDate":true} /-->
```
当区块具有`save`函数时，区块编辑器会检查`save`函数创建的标记是否与保存到数据库的区块标记相同：
- 差异将触发[验证错误](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation)，通常是由于`save`函数输出的更改引起的。
- 开发者可以通过实现[区块弃用](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/)来解决潜在的验证问题，以应对更改。
如上例所示，动态渲染区块的存储标记非常简洁。通常，这只是一个包含区块属性的分隔符注释，不受区块编辑器验证的约束。这种方法反映了这些区块的动态特性，实际HTML在服务器端生成，不存储在数据库中。
## 附加资源
- [数据流与数据格式](https://developer.wordpress.org/block-editor/explanations/architecture/data-flow/)
- [静态与动态区块：有何不同？](https://developer.wordpress.org/news/2023/02/27/static-vs-dynamic-blocks-whats-the-difference/) | 开发者博客
- [区块弃用教程](https://developer.wordpress.org/news/2023/03/10/block-deprecation-a-tutorial/) | 开发者博客
- [模板入门 > 区块标记](https://developer.wordpress.org/themes/templates/introduction-to-templates/#block-markup) | 主题手册

122
docs/getting-started/fundamentals/registration-of-a-block.md Normal file
View File

@@ -0,0 +1,122 @@
# 区块注册
WordPress中的区块通常以插件形式打包，并通过`block.json`元数据在服务端和客户端进行注册。
虽然可以仅在客户端注册区块，但最佳实践强烈建议在服务端和客户端同时注册。这种双重注册对于启用服务端功能至关重要，例如动态渲染、区块支持、区块钩子和样式变体。若缺少服务端注册，这些功能将无法正常运行。
例如，若希望区块[通过`theme.json`设置样式](https://developer.wordpress.org/themes/global-settings-and-styles/settings/blocks/)，则必须在服务端进行注册。否则，该区块将无法识别或应用在`theme.json`中为其分配的任何样式。
以下流程图详细说明了区块的注册过程。
[![打开区块注册流程图](https://developer.wordpress.org/files/2023/11/block-registration-e1700493399839.png)](https://developer.wordpress.org/files/2023/11/block-registration-e1700493399839.png "打开区块注册流程图")
## 使用PHP注册区块（服务端）
区块在服务端的注册通常发生在主插件PHP文件中，通过[`init`](https://developer.wordpress.org/reference/hooks/init/)钩子调用[`register_block_type()`](https://developer.wordpress.org/reference/functions/register_block_type/)函数。该函数通过读取`block.json`文件中存储的元数据来简化区块类型注册。
此函数专为注册区块类型而设计，在此上下文中主要使用两个参数（虽然可支持更多变体）：
- **`$block_type`（字符串）：** 可以是包含`block.json`文件的目录路径，或元数据文件的完整路径（如果文件名不同）。此参数告知WordPress在哪里查找区块配置。
- **`$args`（数组）：** 这是一个可选参数，可用于指定区块类型的其他参数。默认情况下为空数组，但可以包含各种选项，其中之一是`$render_callback`。此回调用于在前端渲染区块，是`block.json`中`render`属性的替代方案。
在开发过程中，`block.json`文件通常作为代码编译的一部分从`src`（源）目录移动到`build`目录。因此，在注册区块时，请确保`$block_type`路径指向`build`目录中的`block.json`文件。
`register_block_type()`函数在成功时返回注册的区块类型（`WP_Block_Type`），失败时返回`false`。以下是一个使用`render_callback`的简单示例。
```php
register_block_type(
__DIR__ . '/build',
array(
'render_callback' => 'render_block_core_notice',
)
);
```
以下是一个更完整的示例，包括`init`钩子。
```php
function minimal_block_ca6eda___register_block() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'minimal_block_ca6eda___register_block' );
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/plugin.php)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)_
### 仅限PHP的自动注册区块
对于仅需服务端渲染的区块，您可以使用[`auto_register`](/docs/reference-guides/block-api/block-supports.md#auto_register)标志和`render_callback`在PHP中单独注册。这些区块会自动出现在编辑器中，无需任何JavaScript注册或客户端代码，并使用[动态渲染](/docs/getting-started/fundamentals/static-dynamic-rendering.md)。
```php
register_block_type( 'my-plugin/server-block', array(
'render_callback' => function( $attributes ) {
$wrapper_attributes = get_block_wrapper_attributes();
return sprintf(
'<div %1$s>服务器内容</div>',
$wrapper_attributes
);
},
'supports' => array(
'auto_register' => true,
'color' => array(
'background' => true,
),
),
) );
```
## 使用JavaScript注册区块（客户端）
当区块已在服务端注册且未使用[仅限PHP的自动注册区块](#仅限php的自动注册区块)时，您只需使用`@wordpress/blocks`包中的[`registerBlockType`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-blocks/#registerblocktype)方法在JavaScript中注册客户端设置。只需确保使用与区块`block.json`文件中定义的相同区块名称。以下是一个示例：
```js
import { registerBlockType } from '@wordpress/blocks';
registerBlockType( 'my-plugin/notice', {
edit: Edit,
// ...其他客户端设置
} );
```
虽然通常建议使用PHP在服务端注册区块，以获得["使用元数据文件的好处"](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-using-the-metadata-file)部分所述的优势，但您也可以选择仅在客户端注册区块。`registerBlockType`方法允许您使用元数据注册区块类型。
该函数接受两个参数：
- **`blockNameOrMetadata`（字符串|对象）：** 可以是区块类型的名称（字符串），也可以是包含区块元数据的对象（通常从`block.json`文件加载）。
- **`settings`（对象）：** 这是一个包含区块客户端设置的对象。
<div class="callout callout-tip">
如果您使用构建过程（例如<a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/#the-build-process-with-wp-scripts"><code>wp-scripts</code></a>提供的构建过程），可以直接将<code>block.json</code>文件（或任何其他<code>.json</code>文件）的内容导入到JavaScript文件中。
</div>
作为第二个参数传递的`settings`对象包含许多属性，但以下两个是最重要的：
- **`edit`：** 在编辑器中用于我们区块的React组件。
- **`save`：** 返回保存到数据库的静态HTML标记的函数。
`registerBlockType()`函数在成功时返回注册的区块类型（`WPBlock`），失败时返回`undefined`。以下是一个示例：
```js
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';
import metadata from './block.json';
const Edit = () => <p { ...useBlockProps() }>Hello World - 区块编辑器</p>;
const save = () => <p { ...useBlockProps.save() }>Hello World - 前端</p>;
registerBlockType( metadata.name, {
edit: Edit,
save,
} );
```
_查看[上述代码](https://github.com/WordPress/block-development-examples/blob/trunk/plugins/minimal-block-ca6eda/src/index.js)的[完整区块示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/minimal-block-ca6eda)_
## 附加资源
- [`register_block_type` PHP函数](https://developer.wordpress.org/reference/functions/register_block_type/)
- [`registerBlockType` JS函数](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-blocks/#registerblocktype)
- [为什么区块需要在服务端和客户端同时注册？](https://github.com/WordPress/gutenberg/discussions/55884) | GitHub讨论
- [区块注册流程图](https://excalidraw.com/#json=PUQu7jpvbKsUHYfpHWn7s,61QnhpZtjykp3s44lbUN_g)

178
docs/getting-started/fundamentals/static-dynamic-rendering.md Normal file
View File

@@ -0,0 +1,178 @@
### 数据库中动态区块的HTML呈现方式（`save`方法）
对于动态区块，`save`回调函数可以直接返回`null`，这将告知编辑器仅将区块分隔注释（以及现有的[区块属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)）保存至数据库。这些属性随后会被传递到服务端渲染回调函数，由该函数决定如何在前端站点上显示区块。
当`save`返回`null`时，区块编辑器将跳过[区块标记验证流程](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation)，避免因频繁变化的标记引发问题。
具有动态渲染功能的区块也可以保存区块的HTML表示作为备用方案。如果您提供了服务端渲染回调，数据库中代表区块的HTML将被回调输出所替代，但若区块被停用（注册区块的插件被卸载）或渲染回调被移除，则会呈现原保存的HTML。
在某些情况下，区块会保存其HTML表示，并在满足特定条件时使用动态渲染来优化标记。核心区块中使用此方法的示例包括：
- [封面区块](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover)通过[save方法](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/cover/save.js)在数据库中保存完整的HTML表示。该标记通过[`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L74)处理，当启用“使用特色图像”设置时，会[动态注入](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/cover/index.php#L16)特色图像。
- [图像区块](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image)同样通过[save方法](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/image/save.js)将其HTML表示保存至数据库。该标记通过[`render_callback`](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L363)处理，当满足特定条件时，会[为标记添加额外属性](https://github.com/WordPress/gutenberg/blob/22741661998834e69db74ad863705ee2ce97b446/packages/block-library/src/image/index.php#L18)。
如果在动态区块中使用[内部区块](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/)，您需要通过`<InnerBlocks.Content/>`在`save`回调函数中保存`InnerBlocks`。
## 扩展资源
- [静态区块 vs 动态区块：差异解析](https://developer.wordpress.org/news/2023/02/27/static-vs-dynamic-blocks-whats-the-difference/) | 开发者博客
- [区块弃用机制详解](https://developer.wordpress.org/news/2023/03/10/block-deprecation-a-tutorial/) | 开发者博客
# 区块的静态与动态渲染
区块的前端标记既可以在请求时由服务器端动态生成（动态区块），也可以在区块编辑器的保存过程中静态生成（静态区块）。本文将深入探讨这两种实现方式。
<div class="callout callout-tip">
<a href="https://developer.wordpress.org/news/2023/02/27/static-vs-dynamic-blocks-whats-the-difference/">《静态区块与动态区块：差异解析》</a>这篇技术文章为本主题提供了绝佳的入门指引。
</div>
## 静态渲染
采用"静态渲染"的区块在保存时就会生成固定不变的前端输出并存储至数据库。这类区块完全依赖其 `save` 函数来定义其 [HTML 标记结构](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/)，除非在区块编辑器中进行手动修改，否则这些标记将始终保持不变。
若某个区块未采用动态渲染方式——即不通过 PHP 在页面加载时实时生成内容——则会被归类为"静态区块"。
下图直观展示了静态区块内容如何保存至数据库，并在前端被检索并渲染为 HTML 的过程。
![静态渲染区块示意图](https://developer.wordpress.org/files/2024/01/static-rendering.png)
### 如何为区块定义静态渲染
通过[在客户端注册区块](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-javascript-client-side)时可定义的 `save` 函数，可以指定区块的 HTML 结构。每当在编辑器中保存区块时，该 HTML 结构就会被存入数据库，并最终用于前端展示。
WordPress 中的区块会被封装在特殊的注释标签内，这些标签作为唯一的[区块定界符](https://developer.wordpress.org/block-editor/getting-started/fundamentals/markup-representation-block/)存在。但最终渲染时，只会呈现静态区块 `save` 函数中定义的 HTML 内容（不包含这些定界符）。
<details><summary><strong>查看预格式化区块中的静态渲染示例</strong></summary>
<br/>
以下是 <a href="https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/preformatted">预格式化</a> 核心区块的 <a href="https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/preformatted/save.js"><code>save</code> 函数</a>示例：
```js
import { RichText, useBlockProps } from '@wordpress/block-editor';
export default function save( { attributes } ) {
const { content } = attributes;
return (
<pre { ...useBlockProps.save() }>
<RichText.Content value={ content } />
</pre>
);
}
```
当 `attributes.content` 的值为 `"这是一段预格式化文本"` 时，该函数会生成如下区块标记表示：
```html
<!-- wp:preformatted -->
<pre class="wp-block-preformatted">这是一段预格式化文本</pre>
<!-- /wp:preformatted -->
```
在前端，该区块将返回以下标记。请注意定界符已不复存在。
```html
<pre class="wp-block-preformatted">这是一段预格式化文本</pre>
```
</details>
<br/>
我们将在下一节探讨的动态区块，虽然也能通过 `save` 函数指定初始 HTML 结构（类似于静态区块），但它们主要依赖服务器端渲染来生成内容。如果因故无法进行动态渲染（比如区块插件被停用），系统将转而使用数据库中保存的 HTML 结构来在前端显示该区块。
要了解具体运作机制，请参阅[构建你的第一个区块](/docs/getting-started/tutorial.md)教程。特别是[添加静态渲染](/docs/getting-started/tutorial.md#adding-static-rendering)章节，生动演示了区块如何同时具备保存 HTML 结构和动态渲染能力。
<div class="callout callout-info">
WordPress 提供了诸如 <a href="https://developer.wordpress.org/reference/functions/render_block/"><code>render_block</code></a> 和 <a href="https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-dynamic-blocks/"><code>render_callback</code></a> 等机制，用于在区块最终呈现到前端之前修改其保存的 HTML。这些工具赋予开发者动态定制区块输出的能力，以满足复杂交互场景的需求。
</div>
更多采用静态渲染的 WordPress 区块示例（即其输出在保存时即固定，不依赖服务器端处理）包括：
- [分隔符区块](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/separator/save.js)
- [间距区块](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/spacer/save.js)
- [按钮区块](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/button/save.js)
## 动态渲染
具备“动态渲染”功能的区块旨在前端请求时实时生成其内容和结构。与在数据库中保存固定HTML结构的静态区块不同，“动态区块”依赖服务器端处理来动态构建输出，这使其具有高度灵活性，非常适合需要频繁更新或依赖外部数据的内容。
下图展示了动态区块的表示形式如何在数据库中保存，然后在前端检索并动态渲染为HTML。
![动态渲染区块示意图](https://developer.wordpress.org/files/2024/01/dynamic-rendering.png)
动态区块的常见应用场景包括：
1. **内容需在文章未更新时自动变化的区块**：例如[最新文章](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/latest-posts)区块，每当有新文章发布时会自动更新。
2. **标记更新需立即在前端显示的区块**：若通过添加新类、HTML元素或任何方式更新区块结构，使用动态区块可确保这些更改立即应用到全站所有该区块实例。若无动态区块，类似更新可能触发区块编辑器中的[验证错误](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation)。
### 如何为区块定义动态渲染
区块可通过两种主要方式定义动态渲染：
1. 使用可传递给[`register_block_type()`](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#registration-of-the-block-with-php-server-side)函数的`render_callback`参数。这对于[纯PHP区块](/docs/getting-started/fundamentals/registration-of-a-block.md#php-only-blocks-with-auto-registration)是必需的。
2. 使用通常命名为`render.php`的独立PHP文件。该文件路径应在`block.json`文件中通过[`render`](https://developer.wordpress.org/block-editor/getting-started/fundamentals/block-json/#files-for-the-blocks-behavior-output-or-style)属性定义。
这两种方法都会接收以下数据：
- `$attributes`：区块的属性数组。
- `$content`：数据库中存储的区块标记（如有）。
- `$block`：表示已渲染区块的[WP_Block](https://developer.wordpress.org/reference/classes/wp_block/)类实例（[区块元数据](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)）。
<details><summary><strong>查看站点标题区块中的动态渲染示例</strong></summary>
<br/>
[站点标题](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/site-title)区块使用以下[`render_callback`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/index.php)：
```php
function render_block_core_site_title( $attributes ) {
$site_title = get_bloginfo( 'name' );
if ( ! $site_title ) {
return;
}
$tag_name = 'h1';
$classes = empty( $attributes['textAlign'] ) ? '' : "has-text-align-{$attributes['textAlign']}";
if ( isset( $attributes['style']['elements']['link']['color']['text'] ) ) {
$classes .= ' has-link-color';
}
if ( isset( $attributes['level'] ) ) {
$tag_name = 0 === $attributes['level'] ? 'p' : 'h' . (int) $attributes['level'];
}
if ( $attributes['isLink'] ) {
$aria_current = is_home() || ( is_front_page() && 'page' === get_option( 'show_on_front' ) ) ? ' aria-current="page"' : '';
$link_target = ! empty( $attributes['linkTarget'] ) ? $attributes['linkTarget'] : '_self';
$site_title = sprintf(
'<a href="%1$s" target="%2$s" rel="home"%3$s>%4$s</a>',
esc_url( home_url() ),
esc_attr( $link_target ),
$aria_current,
esc_html( $site_title )
);
}
$wrapper_attributes = get_block_wrapper_attributes( array( 'class' => trim( $classes ) ) );
return sprintf(
'<%1$s %2$s>%3$s</%1$s>',
$tag_name,
$wrapper_attributes,
// 如果是链接则已预转义
$attributes['isLink'] ? $site_title : esc_html( $site_title )
);
}
```
但该区块未定义`save`函数，从其[`index.js`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/site-title/index.js)文件可见，这意味着区块在数据库中的标记表示如下：
```html
<!-- wp:site-title /-->
```
在前端，`render_callback`会根据请求区块时服务器的具体值动态渲染区块标记。这些值包括当前站点标题、URL、链接目标等。
```
<h1 class="wp-block-site-title"><a href="https://www.wp.org" target="_self" rel="home">我的WordPress网站</a></h1>
```
</details>
<br/>

139
docs/getting-started/glossary.md Normal file
View File

@@ -0,0 +1,139 @@
## 工具栏
一组按钮控件。在区块环境中，通常指选中区块上方显示的区块控制工具栏。
# 术语表
## 属性来源
描述区块属性结构的对象。其键名可根据需要自由命名以描述区块类型的状态。每个键对应的值是一个函数，描述从已保存文章内容中提取属性值的策略。处理时会根据属性来源定义的键创建新对象，其中每个值都是属性来源函数的执行结果。
## 属性
表征文章内容中区块当前状态的对象。加载已保存文章时，该对象由对应区块类型的属性来源决定。在编辑过程中，这些值会随着用户修改区块而产生变化，并在序列化区块时被使用。
## 区块
用于描述标记单元的抽象术语，这些单元组合后构成网页的内容或布局。该概念将WordPress中通过短代码、自定义HTML和嵌入发现实现的功能整合为统一的API和用户体验。
## 区块样式
通过样式表或区块标记本身实现的CSS样式。例如，附加在区块标记上的类即被视为区块样式。
对比<a href="#global-styles">全局样式</a>。与全局样式相对，区块样式有时也被称作<a href="#local-styles">局部样式</a>。
了解更多关于[区块样式](/docs/explanations/architecture/styles.md#block-styles)的内容。
## 区块支持
供区块声明支持功能的API。通过声明对某项功能的支持，该API会为区块添加额外的<a href="#attributes">属性</a>，并为大多数现有区块支持功能提供匹配的UI控件。
参阅<a href="https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/">区块支持参考文档</a>深入了解该API。
## 区块主题
采用区块优先方式构建的主题，支持全站编辑功能。区块主题的核心是其区块模板和区块模板部件。截至目前，区块主题模板是由区块标记组成的HTML文件，对应标准WordPress模板层级中的模板。
## 区块分类
这些并非WordPress的分类法，而是在区块库中用于内部排序区块的机制。
## 区块~插入器~库
选择可用区块的主要界面，通过区块上的加号图标按钮或编辑器界面左上角的按钮触发。
## 区块名称
区块类型的唯一标识符，由插件特定命名空间和描述区块用途的简短标签组成。例如：<code>core/image</code>
## 区块模板
预定义区块排列方式的模板，可能包含预定义属性或占位内容。您可以为文章类型提供模板，为用户创建新内容时提供起点，或在自定义区块中通过<code>InnerBlocks</code>组件使用模板。本质上，模板是由区块标记组成的HTML文件，对应标准WordPress模板层级中的模板（如索引页、单篇文章页或归档页）。这有助于控制未通过页面编辑器或文章编辑器修改的网站前端默认样式。更多信息请参阅<a href="../../developers/block-api/block-templates/">模板文档</a>。
## 区块模板部件
在区块模板基础上构建，这些部件帮助设置可复用项目（如页脚或页眉）的结构，这些结构在WordPress站点中十分常见。它们主要构成站点结构，绝不能与文章内容编辑器混用。通过全站编辑和基于区块的主题，用户可以创建自定义模板部件，将其保存至站点数据库，并在整个站点中重复使用。模板部件在区块体系中相当于主题模板部件，通常由主题首先定义，具有特定语义（可在不同主题间互换，如页眉），且只能在站点编辑器环境中（“模板”内）插入。
## 区块类型
与构成特定文章的区块不同，区块类型描述了该类区块应有的行为蓝图。因此，虽然一篇文章中可能包含多个图片区块，但每个图片区块都遵循统一的图片区块类型定义。
## 经典区块
将 TinyMCE 编辑器作为区块嵌入的区块类型。TinyMCE 是旧版核心编辑器的基础。在区块编辑器之前创建的旧内容将被加载到单个经典区块中。
## 动态区块
这类区块的内容可能发生变化，且在保存文章时无法确定具体内容，而是在文章显示于网站前端时实时计算生成。这类区块在其 JavaScript 实现中可能保存备用内容或不保存任何内容，转而依赖 PHP 区块实现在运行时进行渲染。
## 全站编辑
指一系列功能的集合，最终允许用户以区块为起点编辑整个网站。该功能集涵盖从区块模式到全局样式，从模板到区块设计工具（及更多）的所有内容。首次发布于 WordPress 5.9。
## 全局样式
由 WordPress 生成并作为嵌入式样式表排入网站前端的 CSS 样式。该样式表 ID 为 `global-styles-inline-css`。其内容来源于 WordPress 默认的 `theme.json`、主题的 `theme.json` 以及用户通过网站编辑器中全局样式侧边栏提供的样式。
详见[theme.json 参考文档](/docs/reference-guides/theme-json-reference/README.md)、[操作指南](/docs/how-to-guides/themes/global-settings-and-styles.md)以及[区块编辑器样式介绍](/docs/explanations/architecture/styles.md)。
对比<a href="#block-styles">区块样式</a>。
## 检查器
已弃用术语。参见<a href="#settings-sidebar">设置侧边栏</a>。
## 本地样式
参见<a href="#block-styles">区块样式</a>。
## 导航区块
允许编辑网站导航菜单结构和设计的区块。
## 模式
模式是预定义的区块布局，可作为初始内容插入，每次插入后都需要用户进行修改。一旦插入，它们将以本地保存形式存在，不具备全局性。
## 文章设置
包含文章元数据字段的侧边栏区域，包括发布时间安排、可见性、分类项和特色图片。
## 查询区块
复制经典 WP_Query 功能并支持通过附加功能进行进一步自定义的区块。
## 可复用区块
保存后可作为可复用内容片段共享的区块。
## 富文本
支持富内容编辑的通用组件，包括粗体、斜体、超链接等功能。
## 序列化
将区块属性对象转换为 HTML 标记的过程，每次编辑区块时都会执行此操作。
## 设置侧边栏
右侧包含文档和区块设置的面板。可通过设置齿轮图标切换侧边栏显示。选中区块时显示区块设置，否则显示文档设置。
## 网站编辑器
允许直接编辑各种模板、模板部件、样式选项等并可在其间导航的完整操作体验。
## 静态区块
这类区块的内容在保存文章时即可确定。静态区块的 HTML 标记将直接保存在文章内容中。
## 模板编辑模式
精简的直接编辑体验，允许编辑/更改/创建文章/页面使用的模板。
## 主题区块
通过传统模板标签实现所有功能的区块（例如：文章作者区块）。完整列表可在[此处](https://github.com/WordPress/gutenberg/issues/22724)查看。
## TinyMCE
<a href="https://www.tinymce.com/">TinyMCE</a> 是一款基于 JavaScript 的网页所见即所得编辑器。

54
docs/getting-started/quick-start-guide.md Normal file
View File

@@ -0,0 +1,54 @@
# 快速入门指南
本指南旨在通过实践操作演示WordPress区块开发的基本原理。按照以下步骤，您将在几分钟内创建一个使用现代JavaScript（ESNext和JSX）的自定义区块插件。该示例区块将显示版权符号（©）和当前年份，是任何网站页脚的完美补充。您可以通过以下短视频演示观看这些步骤的实际操作。
<iframe width="960" height="540" src="https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog" title="WordPress区块开发：快速入门指南视频" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="true"></iframe>
## 搭建区块插件
首先确保您的计算机已安装Node.js和`npm`。如果尚未安装，请查阅[Node.js开发环境](https://developer.wordpress.org/block-editor/getting-started/devenv/nodejs-development/)指南。
接下来，使用[`@wordpress/create-block`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)包和[`@wordpress/create-block-tutorial-template`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block-tutorial-template/)模板来搭建完整的“版权日期区块”插件。
<div class="callout callout-info">
<p>您可以使用<code>create-block</code>在任意位置搭建区块，然后在生成的插件文件夹内使用<a href="https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/"><code>wp-env</code></a>。这将创建一个已安装并激活新区块插件的本地WordPress开发环境。</p>
<p>如果您已有自己的<a href="https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment">本地WordPress开发环境</a>，请通过终端导航至<code>plugins/</code>文件夹。</p>
</div>
选择要创建插件的文件夹，然后在该文件夹的终端中执行以下命令：
```sh
npx @wordpress/create-block copyright-date-block --template @wordpress/create-block-tutorial-template
```
提供的`slug`参数（`copyright-date-block`）定义了搭建插件的文件夹名称和内部区块名称。
导航至本地WordPress安装的插件页面，激活“版权日期区块”插件。随后该示例区块将在编辑器中可用。
## 基本使用
激活插件后，您可以探索区块的工作方式。使用以下命令进入新创建的插件文件夹并启动开发过程：
```sh
cd copyright-date-block && npm start
```
当`create-block`搭建区块时，它会安装`wp-scripts`并将最常用的脚本添加到区块的`package.json`文件中。请参阅[wp-scripts入门](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/)文章了解该包的介绍。
`npm start`命令将启动开发服务器并监视区块代码的更改，在修改时重新构建区块。
完成更改后，运行`npm run build`命令。这将优化区块代码并使其达到生产就绪状态。
## 查看实际效果
您可以使用任何本地WordPress开发环境测试新区块，但搭建的插件包含`wp-env`配置。您的计算机必须已安装并运行[Docker](https://www.docker.com/products/docker-desktop)，如果满足条件，请运行`npx wp-env start`命令。
脚本运行完成后，您可以通过以下地址访问本地环境：<code>http://localhost:8888</code>。使用用户名`admin`和密码`password`登录WordPress仪表板。插件将已安装并激活。打开编辑器或站点编辑器，像插入任何其他区块一样插入版权日期区块。
访问[入门指南](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)了解更多关于`wp-env`的信息。
## 附加资源
- [create-block入门指南](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/)
- [wp-scripts入门指南](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-scripts/)
- [wp-env入门指南](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/)

1013
docs/getting-started/tutorial.md Normal file
View File

File diff suppressed because it is too large Load Diff