发布分块库

提供块定义库的插件是与 Blockly 社区分享可重复使用的块的绝佳方式。为了让您的功能块库尽可能多样化且实用，我们制定了以下准则。

指南

• 让用户轻松安装您的所有功能块，并让用户能够仅安装他们选择的特定功能块或功能块部分。
  • 轻松安装所有内容：为此，您可以提供一个函数，用于安装单个块定义所需的每个部分（例如修饰符、扩展程序、混入项、字段等）。您还可以 提供一个函数，用于安装 插件。
  • 支持选择特定部分：您应单独导出代码块定义的所有部分，以便用户仅导入他们需要的部分，以便创建自己的类似自定义代码块。
• 避免在插件中使用附带效应。
  • 块、字段、扩展和其他部分不能作为 加载插件所产生的负面影响用户应始终掌控何时安装哪些内容。这样，用户就可以导入 而无需担心 已安装。

• 使用 JSON 字段注册表，而不是直接实例化新字段。

  • 不推荐 - 直接实例化新字段：

      const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(new Blockly.FieldNumber(123), 'NAME');
        }
      }
    

  • 推荐 - JSON 字段注册表：

      export const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(Blockly.fieldRegistry.fromJson({
                  name: 'field_number',
                  value: 123,
                }), 'NAME');
        }
      }
    

  • 使用字段注册表后，用户可以更轻松地替换块中使用的字段的实现，而无需更改块定义。

• 不要对用户已安装的内容做出假设。

  • 如果您的插件需要自定义字段或其他插件，请注册这些字段 install 函数中自行设置的字段。
  • 不久之后，Blockly 将提供相关工具， 未包含任何错误信息。在此之前，建议您 在注册扩展程序前查看已经注册的扩展程序， mutator、mixin 或 Field 中。
  • 明确应用测试所需的任何前提条件或依赖项 。

• 不妨考虑为您提供的每个代码块都提供生成器函数。

  • 提供开箱即用的生成器函数可让用户更轻松地使用您的块，而无需了解其结构和设计。如果他们必须编写自己的生成器 功能，这可能会导致每位用户都做多余的工作。
  • JavaScript 是 Blockly 中最常用的语言，因此，如果您只选择提供一种语言，我们建议您选择 JavaScript，除非您的块是专为特定语言（例如实现 Python 库）而构建的。
  • 考虑发布“需要帮助”您所用语言的问题 无法实现生成器函数， 这些事件。

  • 如果您为块提供安装函数，则可以接受 可选的 generators 参数。如果用户传递您支持的生成器实例，您可以自动安装块代码生成器函数并执行相关工作，例如添加保留字：

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.common.defineBlocks({my_custom_block: myCustomBlock});
        if (generators.javascript) {
          generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
          generators.javascript.addReservedWords('specialReservedWord');
        }
      }
    
      // How a user may install your block
      import {javascriptGenerator} from 'blockly/javascript';
      import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
      // installs the block definition and the javascript block-code generator
      installMyCustomBlock({javascript: javascriptGenerator});
    

反馈

如果您对如何在插件中最好地遵循这些指南有疑问， 请在论坛中告诉我们！我们希望看到您的块库， 反馈。

请注意，目前并非所有提供块定义的第一方插件 但新插件仍会遵循这些准则 插件。