使用 Blockly API

简介

本页面介绍了调用函数和访问函数的最佳做法。 属性。这些原则适用于 Blockly 或将 Blockly 集成到独立应用中。

子类化和扩展

Blockly 具有多种添加功能的范式，包括：

• 子类（例如，创建新的渲染程序）
• Mixins（例如，添加区块扩展元素或赋值函数）
• 块定义（例如过程块定义）

在本文档中，所有三种情况均等同于 子类化。

注入子类

我们支持通过 Blockly.inject 方法替换某些类。这些 子类必须扩展基类，或实现其对应的 界面。

您可以将子类传入注入方法。

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

或者，您也可以使用 Blockly.registry 注册类并使用 来注入类的注册表名称。如果你存储自己的注射数据 转换为纯 JSON 格式。

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

可以替换以下类：

注册名称	接口/基类
blockDragger	Blockly.IBlockDragger
connectionChecker	Blockly.IConnectionChecker
connectionPreviewer	Blockly.IConnectionPreviewer
flyoutsVerticalToolbox	Blockly.IFlyout
flyoutsHorizontalToolbox	Blockly.IFlyout
metricsManager	Blockly.IMetricsManager
renderer	Blockly.blockRendering.Renderer
toolbox	Blockly.IToolbox

如需详细了解如何使用接口，请参阅接口部分 文档部分。

注意 ：已注册类上的所有受保护方法和公共方法都可以被替换。 不过，不应替换非注册类上的受保护方法。

公开范围

我们使用 TypeScript 访问修饰符。 将核心库中的可见性标记为 public、private 或 protected。 一些属性的@internal TsDoc 注释。

所有 public 和 protected 属性均记录在 Blockly 网站的参考文档部分。您还可以 通过阅读代码检查公开范围

注意 ：虽然 JavaScript 不会强制执行这些可见性注解，但 应避免访问除 public 之外的任何内容。Blockly 团队 可保证非公开属性和功能在各版本发布之间的稳定性。

公开

任何带 public 标记的内容都是公共 API 的一部分。模块中的任何属性 没有可见性修饰符会被视为公开。

我们会尽量不要频繁或无正当理由更改我们的公共 API， 警告。例外情况：我们可能会在一个版本中将新 API 设为公开， 根据早期反馈，在下一版本中对其进行修改。之后，您可以 将公共函数或属性视为稳定。

公共函数可从任何位置调用，并可在子类中替换，如下所示 只要签名不更改。

受保护

受保护的函数和属性只能由定义类或 子类。

子类可以覆盖受保护的函数和属性， 更改类型签名。

例如，扩展了基础渲染程序类的自定义渲染程序可以访问 及其受保护的属性

无论是哪种情况，您都应该确保自己了解函数或属性的 使用该方法。

不公开

这些变量只能通过定义所在文件中的代码访问。直接 访问这些属性可能会导致未定义的行为。

子类不得覆盖私有函数和属性。

私有资源可能会在不经警告的情况下发生更改，因为它们不是 被视为 Blockly 公共 API 的一部分。

Blockly 中的某些函数没有可见性注解，因为它们 不会从其模块中导出这些函数本质上是局部变量 且不能在其定义模块之外使用。他们应该考虑 等同于私有属性。

注意 ：以前，Blockly 使用下划线表示私有属性： example_。根据当前的 Google 风格指南，我们不再执行此操作 ，并且可能会更改旧代码。在 Blockly 中调用方法之前，请确保 它出现在参考文档中或在 代码。在极少数情况下，私有函数被广泛使用，以至于 公共函数，因此您可能会看到以下划线结尾的公共函数。

内部

内部函数和属性应在核心内使用 而不是外部调用。它们使用 TsDoc @internal 进行标识 注解。

内部属性可能会在无警告的情况下随时发生更改，因为它们不是 被视为 Blockly 公共 API 的一部分。

可以从核心内的任何位置访问内部属性，并在 子类，但前提是签名不会更改。不得以 从核心库外部访问的 API。

已弃用

不得使用任何标记为 @deprecated 的内容。大多数弃用包括 。

在可能的情况下，已弃用的函数将记录一条警告，其中包括 预期删除日期，以及要调用的替换函数的建议。

常见问题解答

如果我想使用的函数不是公共函数，该怎么办？

提交功能请求 。添加您的用例说明以及 您希望我们公开。

我们将使用该功能请求与您讨论是将其公开，还是 看看是否还有其他方法可以获得同样的信息。

如果我们决定将其公开，您或 Blockly 团队将负责 进行适当的更改，并会在下一个 Blockly 版本中生效。

如果您选择在插件中使用非公开成员，请考虑将您的 作为 Beta 版插件，并将相关信息添加到 README 中。

那 monkeypatch 呢？

详细了解 monkeypatching。

Monkeypatching 不安全，因为补丁可能会由于以下原因而停止运行 使用 Blockly API 的非公开部分。在插件中打补丁 尤其危险，因为你的代码与其他 用于为相同代码添加 monkeypatch 的插件。因此，我们强烈 建议不要在应用和第三方插件中进行 monkeypatch 操作，以及 不会在第一方插件中接受该属性。

我可以替换公共函数吗？

当进行子类化时：yes。否则：不，那是 monkeypatching。

我可以覆盖受保护的函数吗？

当进行子类化时：yes。否则：不，那是 monkeypatching。

我可以替换内部函数或私有函数吗？

不是，那只是打猴子

何时可以直接访问媒体资源？何时应使用 getter 或 setter？

如果我们发布了一个 getter 或一个 setter，请使用该方法， 访问媒体资源。如果属性未公开，则务必使用 getter 和 setter 方法。

注意 ：在插件中一致地使用 getter 和 setter 使我们能够灵活地 在不破坏已发布代码的情况下在核心 Blockly 中做出更改。

如果属性没有注释，该怎么办？

默认情况下，这些信息是公开的。不过，如果我们想要 getter/setter 对。

如果函数没有注解，该怎么办？

此标签页默认为公开状态。

如果我还是不确定，该怎么办？

在论坛上提问 我们通常会在一个工作日内回复您。