探索区块编辑器手册
如果你正在为区块编辑器进行开发，区块编辑器手册是权威资源。无论你是为客户项目构建自定义区块，还是开发一个全新的区块及其实现插件（或许打算上传到插件目录），甚至如果你计划为Gutenberg项目本身做贡献，你都会发现自己需要反复查阅这本手册。
区块编辑器手册即使对经验丰富的开发者来说也令人望而生畏。如果你是区块开发新手，第一次接触时感到完全不知所措是完全正常的。
手册内容繁多，切入方式也多种多样。无论你是想学习区块开发的基础知识，还是解决一个特别棘手的问题，都可能难以知道从哪里开始或在哪里找到相关信息。
因此，本文旨在帮助你定位自己并协助你浏览手册。阅读本文后，希望你能更快地找到所需内容。
1. 结构概述
手册遵循文档统一理论中概述的结构。该理论根据文档的目的（即学习、解决问题、理解和信息）对文档进行分类。
- 教程 （面向学习） – 手册的入门部分引导你学习区块开发的基础知识。
- 操作指南 （面向问题） – 操作指南部分展示如何解决你可能遇到的特定问题，并提供可重用的示例代码。
- 解释说明 （面向理解） – 解释说明部分为你解释“如何”背后的“为什么”。在这里，你可以通过理解区块编辑器的工作原理和结构来巩固你的实践知识。
- 参考指南 （面向信息） – 参考指南是你查找需要使用的特定API详细信息的地方。
2. 学习区块开发
如果你是区块开发新手，需要学习一些基础知识，你会有很多问题！
从哪里开始？随着进展，下一步该学什么？如何确保你在之前所学的基础上继续构建？特别是，如何知道你没有超出能力范围，试图学习一些尚未具备先决知识的内容？
在深入区块开发之前，你应该了解一些关键事项并掌握一些预备知识：
现在，你可以通过一些基于项目的实践教程开始学习构建区块：
- 你需要设置你的开发环境。
- 设置好开发环境后，可以开始学习创建区块教程，该教程引导你构建一个基本的静态区块（与动态区块相对）。
- 掌握之后，可以前往区块操作指南。该部分逐步介绍构建区块时所需的功能。它引用了gutenberg-examples仓库中的代码，因此最好在本地克隆该仓库。
- 在学习区块操作指南时，请特别关注动态区块页面。理解动态区块和静态区块之间的区别，以及何时使用哪种。
- 在区块项目中经常需要使用WordPress数据，例如获取数据、在数据库中添加新实体（如文章）或编辑该实体。通过使用Gutenberg数据创建你的第一个应用教程来练习所有这些操作。
现在你已经通过一些实践项目上手了，接下来通过以下内容加深理解：
- 熟悉你可以使用的不同包及其位置。仅了解这一点就能在你进行项目并需要从参考指南部分快速找到答案时节省大量时间。
- 你已经涵盖了其中很大一部分，所以完成架构部分的学习，以确保你拥有坚实的理论基础来支撑你的开发工作。
- 区块编辑器是一个视觉媒介，因此你需要学习区块设计的原则和最佳实践。这不仅仅是让区块看起来美观（尽管好的设计确实能建立对网站信息的信任）。更重要的是视觉流程：你的控件如何工作？选项和设置是否易于找到？它们的作用是否清晰？
- 浏览一下术语表，确保你理解手册中使用的术语。
- 常见问题解答希望能回答你可能仍然存在的任何问题。
3. 使用区块
完成所有这些学习后，你将渴望投入并开始构建你的项目。这时，你可以深入研究操作指南和参考指南部分，它们旨在简化路径并减轻你的负担。
操作指南
不可能预见到你可能遇到的每种场景和用例，但这些操作指南是你最可能需要的内容，它们可以为你最常使用的任务提供方法和代码示例：
- 区块控件：区块工具栏和设置侧边栏展示了如何向区块界面添加控件，以便用户与之交互并更改设置。
- 通知展示了如何在编辑器中使用通知来吸引用户注意重要信息。
- 如何在区块编辑器中使用JavaScript。
- 使用Gutenberg数据创建你的第一个应用展示了如何处理WordPress数据。这是上面提到的同一部分，但如果你当时没有时间或不需要立即使用该信息，可能跳过了它。
参考指南
你会发现自己经常查阅区块API参考。你的需求会有所不同，但几乎每个区块开发项目都会涉及这些基础知识：
值得注意的是，如果你使用@wordpress/create-block工具来搭建你的区块项目，该工具将处理注册以及编辑和保存的大部分工作。尽管如此，花时间和精力去理解脚手架工具为你做了什么仍然是值得的。
核心区块参考是你了解Gutenberg自带的区块的指南，每个项目都有一个方便的链接指向Gutenberg仓库中的源代码。当你看到核心开发者如何构建某些区块功能时，你就会知道如何在构建自己的区块时应用这些知识。
Gutenberg是用React构建的，你几乎肯定会在区块项目中使用组件。方便的是，Gutenberg附带了许多预构建的组件，你可以在项目中使用，组件参考详细说明了如何使用每个组件。你还可以使用附带的Storybook工具来交互式地试验组件，以决定在项目中使用哪些组件。
包参考详细介绍了你可以在项目中使用的包。不可能预见到你可能遇到的每种情况，但以下是一些你最有可能安装到项目中并从中导入的包：
- @wordpress/components [源代码]
- @wordpress/block-editor [源代码]
- @wordpress/rich-text [源代码]
- @wordpress/scripts [源代码]
4. 精选高级主题
当你承担更高级的项目时，你将需要更高级的工具。同样，无法预见到每一个需求，但有些事情比其他事情更常见。以下是一些在你区块开发生涯中某个时间点很可能需要的最常见事项：
5. 更多资源
手册应被视为与区块开发相关的所有事项的权威资源。但它并不是唯一的资源，你可能会发现其他一些资源涉及与你当前项目相关的内容，或者它们可能更容易理解。以下是一些推荐资源。
课程
learn.wordpress.org上有一些有用的课程：
- 区块开发入门：构建你的第一个自定义区块
本课程是一个循序渐进的教程，温和地引导你从基本原理到熟练的区块开发者。该课程将手把手地指导你开发一个示例项目。它还将为你打下坚实的基础，帮助你从手册中获得最大收益。 - 将短代码转换为区块
本课程展示了如何完成一个常见的用例，即获取一个基于短代码的遗留插件并将其区块化。这个用例非常普遍，以至于它曾经（几乎完全靠自己）导致了Gutenberg插件的一次回归。 - 使用WordPress数据层
本课程教授在区块编辑器中使用WordPress数据的原理，尽管它主要是对前面提到的手册中“使用Gutenberg数据创建你的第一个应用”教程的重新编排。
博客
如果你正在阅读本文，说明你已经找到了WordPress开发者博客😄。值得定期回来查看其不断增长的技术文章集合——当然，包括大量关于各种用例中区块开发的报道。该博客也是了解WordPress其他发展的绝佳方式。
也许你对开发者博客的文章有想法。如果是这样，为什么不提出这个想法，甚至自己写呢。方法在这里！
6. 贡献
与WordPress一样，Gutenberg是开源软件，欢迎任何人（这意味着你！🫵）为项目做出贡献。从贡献者指南开始，该指南详细介绍了第一步，并可以帮助你选择你想要贡献的方式，无论是通过代码、测试、文档还是其他方式。
手册本身正在不断改进，帮助改进手册是一种极好且有价值的贡献方式。手册内容来源于Gutenberg仓库的docs目录。该仓库有一个用于开发者文档问题的标签，即[Type] Developer Documentation。前往那里，选择一个议题，并开始处理一个PR。
如果你发现了手册的问题，例如错误或信息缺失，或者即使你有一个改进手册的想法，但你自己不想为其创建拉取请求，你可以添加一个议题，并用[Type] Developer Documentation标签标记它。会有人接手，手册会随着时间的推移变得越来越好。
最后…
一旦你涵盖了本文中的所有内容，你将从实践和理论角度对区块开发有扎实的理解。除了上述内容，花些时间简单地浏览手册并探索其内容。最终，你会发现你熟悉了手册的结构，并且能够在你需要时更容易地找到所需信息。