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