简介
本页介绍了在 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 个工作日内回复您。