所有针对区块的专用插件也必须遵守整体插件指南。这些额外的指南是专为针对区块的插件所独有的。

向区块目录提交插件的指南

区块目录的目标是为 WordPress 用户提供一个安全的地方，以便查找和安装新的区块。

用户期望

  • 用户可以在其 WordPress 管理后台和 WordPress.org 上找到一个地方，下载和安装已经针对重大安全问题进行过预先审核的区块。
  • 用户可以一次一个地通过管理后台一键安装区块。
  • 区块在安装并激活后会出现于他们的区块库中。
  • 区块将无缝且立即工作，没有侵入性广告或推销。

开发者期望

  • 开发者在针对区块目录编写区块时，将拥有一套具体的要求和指南可供遵循。
  • 遵循这些指南将有助于确保他们开发的区块可以无缝地安装在编辑器中。
  • 提交到区块目录的区块受到比一般 WordPress 插件更严格的技术和政策规则约束。
  • 不符合区块目录指南的包含区块的插件仍然可以提交到插件目录。

定义

出于区块目录的目的，我们区分两种类型的插件：

  1. 仅用于分发区块的插件。
  2. 所有其他插件，包括捆绑许多独立区块的插件、除其他功能外还包含区块的插件以及没有任何区块的插件。

这些指南专门适用于第一种类型的插件，称为区块插件。如果插件属于第二种类型，则进一步的指南和限制不适用。所有插件，无论是仅针对区块的还是不是，都必须遵守详细插件指南。

区块插件与区块目录

区块目录仅包含区块插件，即只包含单个、独立的顶级区块和最少支持代码的插件。区块插件具有以下特征：

  1. 一种特定类型的 WordPress 插件，具有相同的结构，包括 readme.txt 文件。
  2. 仅包含区块（通常是一个顶级区块）。
  3. 包含最少的服务器端（即 PHP）代码。
  4. 自包含，除了帖子编辑器外没有 UI。

除了适用于所有 WordPress 插件的指南外，提交到区块目录的区块插件还必须遵守以下指南：

指南

1. 区块插件是用于区块编辑器的。

区块插件必须包含一个区块和最少量的其他支持代码。它不能包含编辑器之外的任何 UX，例如 WordPress 选项或 wp-admin 菜单。服务器端代码应保持在最低限度。

仅扩展或为其他已存在的区块提供样式的插件目前不符合纳入区块目录的资格。目前，它们不受区块编辑器的无缝安装流程支持。只有注册新区块的区块插件目前得到支持。

2. 区块插件是独立的区块。

区块插件旨在作为单一用途、独立、单独的区块，而不是许多区块的捆绑包或汇编。在大多数情况下，区块插件应仅包含一个顶级区块。区块目录将不包括可以合理地拆分为独立区块的区块集合。

如果存在明确的必要父/子或容器/内容依赖关系，区块插件可以包含多个区块；例如，包含列表项区块的列表区块。

3. 插件和区块名称应反映区块的目的。

插件标题和区块标题应以帮助用户轻松理解其目的的方式描述区块的功能。在大多数情况下，插件标题和区块标题应相同或非常相似。一些好的插件和区块名称示例包括：

Rainbow Block
Sepia Image Grid
Business Hours Block

请避免使用与区块本身无关或无法轻松与核心区块区分开的插件和区块标题。一些无用的插件和区块名称示例包括：

PluginCo Inc Block
Widget
Image Block

针对插件标题的相同商标限制也适用于区块标题和名称。这意味着除非由 Facerange 的法律代表开发，否则区块不能命名为“Facerange Block”。

3a. 区块名称应该是唯一的且命名空间正确。

区块名称（即 registerBlockType() 的 name 参数和 block.json 中的 name）必须是区块唯一的。与标题一样，请尊重商标和其他项目的常用名称，以免与其冲突。

区块名称的命名空间前缀应反映插件作者或插件 slug。例如：

name: "my-rainbow-block-plugin/rainbow"，或
name: "john-doe/rainbow"，或
name: "pluginco/rainbow"。

命名空间不能是保留的，例如 core 或 wordpress。

4. 区块插件必须包含 block.json 文件。

区块注册 RFC 概述了 block.json 文件的格式：https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md

区块插件必须包含有效的 block.json 文件。除了 RFC 中规定的要求外，block.json 还必须包含以下属性：

  • name
  • title
  • 至少一个：script、editorScript
  • 至少一个：style、editorStyle

5. 区块插件必须独立工作。

区块插件必须能够独立运行，无需依赖任何其他 WordPress 插件或主题等外部依赖项。

区块插件可以使用另一个 WordPress 插件或主题中的代码或钩子，前提是即使未安装该插件或主题，区块插件仍然可用。例如，食谱区块插件被允许应用滑块插件中实现的过滤器以改善其图像显示，只要食谱区块插件在无需滑块插件的情况下仍然可用。

6. 区块插件应无缝工作。

区块插件旨在从编辑器安装时能够无缝且即时地工作。这意味着它们不应使用户承担额外的步骤或先决条件，例如安装另一个插件或主题、注册账户、登录或手动连接到外部服务。

不允许对使用区块插件进行任何形式的支付。虽然允许在插件的 readme 中使用捐赠链接功能，或从完整的插件列表链接，但区块插件本身必须免费使用。需要付费服务或包含推销和高级功能的区块插件仍然被允许在主 WordPress 插件目录中，前提是遵守其指南。

区块插件可以在必要时使用外部/云 API，前提是可以无缝完成而无需登录或激活密钥。

它们不应依赖外部 API 或云服务来执行可以在本地执行的功能。

7. 服务器端代码应保持在最低限度。

由于区块插件是 WordPress 插件，它们必然包含用于元数据和初始化的 PHP 代码。应尽可能避免包含额外的 PHP 代码或服务器端库。WordPress REST API 应是访问 WordPress 的首选接口，而非自定义服务器端代码。

REST API 存在限制，在某些情况下，使用服务器端 PHP 是实现功能的唯一高效方式。在这些情况下，可以包含 PHP 代码，但前提是代码编写清晰、尽可能少用且文档完善。

8. 不得包含广告或推广通知。

区块插件不得包含显示警报、仪表板通知或与区块目的无关的类似干扰性消息的代码。