插件

简介

插件是一段独立的代码,用于向 Blockly 中添加功能。插件可以添加字段、定义主题、创建渲染程序等等。

插件的目标用户是通过 npm 查找和使用插件的开发者。如需详细了解如何构建插件,您还可以观看 2021 年“如何构建插件”讲座2021 年插件概览讲座

第一方与第三方

blockly-samples 代码库中定义的插件是第一方插件,这意味着这些插件受 Blockly 团队支持,并在 npm 上发布在 @blockly 范围内。

优秀的第一方插件:

  • 都有明显的使用场景
  • 是通用的
  • 稳定
  • 易于使用

第三方插件是独立维护和发布的。第三方插件可能更复杂、更实验性或更具针对性。

例如,用于设置电机速度的字段可以在许多机器人项目中使用。另一方面,用于修改由数据库架构定义的特定对象的字段更适合用作第三方插件。

第一方条件

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

  • 适用于所有主要平台,除非 Blockly 团队获得豁免。
    • Chrome、Firefox、Safari、Edge
  • 有一名愿意在第一年处理 bug 的作者。
  • 不会对 Blockly 执行 monkeypatch。
  • 具有明确定义并记录在案的 API。
  • 除非 Blockly 团队授予了豁免,否则不会从 Blockly 核心调用私有函数或软件包函数。
    • 允许覆盖您定义的子类上的软件包函数。
    • 如需豁免,请针对禁播样本向我们提出问题。
  • 包含测试。

查找插件

  • 在 GitHub 页面上探索第一方插件的实时演示
  • 在 npm 上:搜索 @blockly,查看 Blockly 团队发布的插件列表。
  • 在 GitHub 上:查看 blockly-samples 代码库中的插件目录。每个插件都有一个 README 文件,用于说明其行为和预期用途。

安装插件

  1. 使用上述任一资源找到您要安装的插件,并找到 README。
  2. 按照 README 文件中的所有安装说明进行操作。一般来说,您需要从 npm 安装插件,例如

    npm install @blockly/block-plus-minus --save
    

    并将其导入您的代码中,例如

    import Blockly from 'blockly';
    import '@blockly/block-plus-minus';
    
  3. 某些插件可能需要执行额外的步骤,例如初始化或注册插件。这些步骤将在 README 中列出。

插件版本

blockly-samples 中的插件遵循语义化版本控制,因此所有重大更改都将采用新的主要版本。如 semver 规范中所述,任何依赖于 monkey 修补核心的新插件的主要版本都是 0,这表示初始开发版本。

大多数插件将主 blockly 软件包作为 PeerDependency(而非依赖项)包含在内。这是因为我们希望您已在自己的应用中自行安装了 Blockly(如果不使用 Blockly 插件,那就没有意义),这样您就可以自行管理 Blockly 的版本了。不过,许多插件都是为使用最新版本的 Blockly 中的新 API 而开发的,因此您需要了解版本要求。插件的 package.json 会告诉您与该插件兼容的 Blockly 最低版本是什么。如果插件经过更新,需要新版本的 Blockly(例如,利用全新的 API),则会增加插件的主要版本,因为我们认为这是破坏性更改。

将插件添加到 package.json 时,默认是在版本前面添加脱字符号,例如

"@blockly/block-plus-minus": "^2.0.15"

此命令可让 npm 安装所列版本不低于所列版本的任何次要版本,因此可以使用 2.0.202.1.0 版本,但不能安装 3.0.1 等新的主要版本。当您更新到 Blockly 的新版本时,建议您检查是否有任何插件也能更新到新的主要版本。

在不使用 npm 的情况下安装插件

虽然我们通常建议使用 npm 来轻松接收更新,但您也可以在不使用 npm 的情况下使用插件。

您可以使用 unpkg 来包含插件文件,而无需克隆这些文件,例如

<script src="https://unpkg.com/@blockly/block-plus-minus"></script>

或者,您也可以克隆 blockly-samples 代码库并在本地添加这些文件,具体方式与克隆 Blockly 时类似。不过,我们建议您尽可能使用软件包管理器,因为它有助于您及时了解插件中的最新功能和 bug 修复。

如果使用此方法,您仍然需要执行插件的 README 文件中列出的任何初始化或注册步骤。