简介
本页介绍了在 Blockly 核心中调用函数和访问属性的最佳实践。这些原则适用于为 Blockly 创建插件或将 Blockly 集成到独立应用中。
子类化和扩展
Blockly 有多种添加功能的范例，包括：
- 子类（例如，创建新的渲染程序）
- 混搭内容（例如添加块扩展或赋值器）
- 块定义（例如过程块定义）
在本文档中，所有三种情况都相当于子类化。
注入子类
我们支持通过 Blockly.inject 方法替换某些类。这些子类必须扩展基类或实现其对应的接口。
您可以将子类传入 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。某些属性可能会在其 TsDoc 注释中带有 @internal 注解。
所有 public 和 protected 属性都记录在 Blockly 网站的参考文档部分。您还可以通过阅读代码来检查可见性。
公开
带有 public 标记的任何内容都是我们的公共 API 的一部分。模块中没有任何可见性修饰符的属性均被视为公开属性。
我们尽量避免在没有充分理由和警告的情况下频繁更改我们的公共 API。例外情况：我们可能会在一个版本中公开一个新的 API，并根据早期的反馈在下一个版本中对其进行修改。之后，您可以考虑将公共函数或属性设为稳定版。
公共函数可以从任何位置调用，并且只要签名不更改，就会在子类中对其进行替换。
受保护
受保护的函数和属性只能由定义类或子类访问。
子类可以在不更改类型签名的情况下替换受保护的函数和属性。
例如，扩展基础渲染程序类的自定义渲染程序可以访问其受保护的属性。
无论是哪种情况，您都应该确保自己了解函数或属性在代码其余部分的使用方式。
private
这些类型只能由定义所在文件中的代码访问。直接访问这些属性可能会导致出现未定义的行为。
不允许子类覆盖私有函数和属性。
私有属性可能会发生更改，恕不另行通知，因为它们不属于 Blockly 公共 API。
Blockly 中的某些函数没有可见性注解，因为它们不是从其模块中导出的。这些函数本质上是局部变量，无法在其定义模块之外使用。它们应被视为等同于私有属性。
内部
内部函数和属性应在核心库内使用，但不能在外部使用。它们通过 TsDoc @internal 注解指定。
内部属性可能会发生更改，恕不另行通知，因为它们不属于 Blockly 公共 API。
内部属性可以从核心中的任何位置访问，并且可以在核心的子类中被替换（只要签名不会更改）。不得从核心库外部访问这些库。
已弃用
请勿使用任何标记为 @deprecated 的内容。大多数弃用项目都包含控制台警告或 TSDoc 中关于首选代码的说明。
在可能的情况下，已废弃的函数将记录一条警告，其中包括预期的删除日期以及建议调用的替换函数。
常见问题解答
如果我要使用的函数不是公开的，该怎么办？
提交针对 Blockly 核心内容的功能请求。包括您的使用场景的说明以及您希望我们公开的内容。
我们将使用该功能来请求讨论是否将其公开，或者是否有其他方法可以让您获取相同的信息。
如果我们决定将其公开，您或 Blockly 团队将进行适当的更改，并且这些更改将在下一个 Blockly 版本中发布。
如果您选择在插件中使用非公开成员，请考虑将您的插件标记为 Beta 版，并在 README 中添加相关信息。
那 monkeypatch 呢？
详细了解 monkeypatching。
Monkeypatch 操作不安全，因为补丁可能会因使用 Blockly API 的非公开部分而停止工作，恕不另行通知。修补插件尤其危险，因为您的代码与 monkeypatch 使用相同代码的任何其他插件之间的互动效果可能会很差。因此，我们强烈建议不要在应用和第三方插件中使用 monkeypatch，并且不会在第一方插件中使用 monkeypatch。
我可以替换公共函数吗？
创建子类时：是。否则：不会，这是 monkeypatch 操作。
我可以覆盖受保护的函数吗？
创建子类时：是。否则：不会，这是 monkeypatch 操作。
我可以替换内部函数或私有函数吗？
不，这是在打猴子。
何时可以直接访问媒体资源？何时应使用 getter 或 setter？
如果我们发布了 getter 或 setter，请使用该 getter 或 setter，而不要直接访问相应属性。如果属性不公开，请务必使用 getter 和 setter。
如果属性没有注解，该怎么办？
默认情况下，它是公开的，但如果我们想要为您部署 getter/setter 对，请给我们一行。
如果某个函数没有注解，该怎么办？
默认情况下是公开的。
如果我仍然不确定，该怎么办？
在论坛上提问，我们通常会在 1 个工作日内回复您。