添加插件

本文档介绍了如何创建新插件。虽然其中介绍的流程适用于创建第一方插件，但您也可以将其用作创建第三方插件的指南。

如需大致了解插件，请参阅插件。

如需简要了解如何创建插件，请观看我们的 “如何构建插件”讲座 (2021)。

第一方与第三方

插件的目标用户是通过 npm 查找和使用插件的开发者。

第一方插件由 Blockly 团队提供支持，并在 npm 上以 @blockly 作用域发布。它们可在各种 Blockly 应用中使用，稳定且易于使用。这些文件存储在 blockly-samples 中。用于设置电机速度的字段可用于许多机器人项目，并且非常适合用作第一方插件。

第三方插件由第三方独立维护和发布。这些版本可能更复杂、更具实验性，或者仅适用于更窄范围的 Blockly 应用。用于修改数据库架构定义的特定对象的字段最好作为第三方插件。

第一方条件

第一方插件必须满足以下要求：

  • 适用于所有主要平台，除非获得 Blockly 团队的豁免。
    • Chrome、Firefox、Safari、Edge
  • 有愿意在第一年处理 bug 的作者。
  • 请勿对 Blockly 进行猴子补丁处理。
  • 提供明确定义且记录在案的 API。
  • 请勿调用 Blockly 核心中的私有函数或软件包函数，除非获得 Blockly 团队的豁免。
    • 允许在您定义的子类中替换软件包函数。
    • 如果您想申请豁免，请在 blockly-samples 中提交问题。
  • 包含测试。

授权流程

插件会经历四个阶段：建议、讨论、实现和发布。

建议

插件最初是作为建议提供的。您可以使用功能请求模板创建新问题，以便建议插件。

了解如何编写功能请求

除了基本功能请求信息之外，插件建议还应包含：

  • 插件要公开的 API。
  • 需要在核心 Blockly 中添加或更改的 API，以支持该插件。
  • 如果插件包含界面功能，请提供屏幕截图、GIF 或模拟图。
  • 说明为何应使用第一方插件而非第三方插件。

Blockly 团队会及时审核收到的建议，并关闭问题或同意将其作为一款优秀的第一方插件。

讨论

接下来，插件会进入讨论阶段。此阶段包括：

  • 阐明所需功能。
  • 阐明了插件的 API。
  • 规划实施。
  • 规划测试。
  • 讨论核心 Blockly 中的 API 变更。
  • 将大型插件拆分为实现步骤。
  • 插件命名，遵循我们的命名惯例。
  • 确认将满足所有第一方条件。

此讨论通常在 GitHub 问题中进行。插件范围越小，讨论阶段就越短。较大的插件可能会吸引社区的关注，并对合适的解决方案提出强烈的意见。如果您的问题出现了这种情况，那么恭喜您！您找到了人们关心的内容。

目标是在讨论阶段结束时，已做出所有重大设计决策，并列出明确的实现步骤。您应在问题评论中记录这两项信息。

在讨论过程中，我们可能会决定某个插件应为第三方插件，而不能在 @blockly 范围下发布。在这种情况下，我们会说明原因并关闭问题。

讨论结束后，Blockly 团队成员会注明该功能已准备好实施。

实现

实施步骤包括：

  • 运行 npx @blockly/create-package 以根据模板设置插件及其目录。了解详情...
  • 实现插件的核心逻辑。
  • 如有必要，实现界面。
  • 使用 Mocha 测试插件。
  • 为插件（包括 README）编写文档。

如果建议的插件已获准实现，并且您希望参与该插件的开发，请对相关问题进行评论，并询问该插件是否仍接受贡献。

实现可以由多个贡献者并行完成。您可以在自己的分支上协作实现插件，也可以通过针对此代码库的拉取请求实现插件。如果您想在这份代码库中协作开发插件，请让 Blockly 团队为您创建一个功能分支。

应将插件添加到 blockly-samples 的 master 分支中的 gh-pages/index.md 文件。这样，这些插件就会显示在我们的插件网站上。第一方插件应指向其测试页面。您还可以将第三方插件添加到此页面，并指向其所有者选择的链接，例如托管的演示版或 npm 页面。

发布

最后，发布。Blockly 团队使用 Lerna 来管理所有插件的版本控制和发布。

每周四，我们都会发布自上次发布以来发生任何更改的插件。如果您需要更快发布更改，请在拉取请求中注明。

每当有插件发布时，插件网站也会更新。

未准备好发布的插件应在其 package.json 中标记为 private。如果某个插件依赖于 core Blockly 中尚未发布的更改，就可能会发生这种情况。Core Blockly 会在每个季度的最后一周发布（每三个月发布一次）。