На этой странице описываются лучшие практики вызова функций и доступа к свойствам в ядре Blockly. Эти принципы применяются к созданию плагинов для Blockly и к интеграции Blockly в отдельное приложение.
Видимость
Мы используем модификаторы доступа TypeScript для обозначения видимости в основной библиотеке как public , private или protected . Некоторые свойства могут быть аннотированы @internal в их комментариях TsDoc .
Все public и protected свойства задокументированы в разделе «Ссылки» веб-сайта Blockly. Вы также можете проверить видимость, прочитав код.
публичный
Все, что отмечено public является частью нашего публичного API. Любое свойство в модуле, не имеющее модификатора видимости, считается публичным.
Мы стараемся не менять наш публичный API часто или без веской причины и предупреждения. Исключение: мы можем сделать новый API публичным в одном выпуске и изменить его в следующем выпуске в ответ на ранние отзывы. После этого вы можете считать публичную функцию или свойство стабильными.
Публичные функции можно вызывать откуда угодно и переопределять в подклассах, пока не изменится сигнатура.
защищенный
Доступ к защищенным функциям и свойствам может получить только определяющий класс или подкласс.
Подклассам разрешено переопределять защищенные функции и свойства без изменения сигнатур типов.
Например, пользовательский рендерер, расширяющий базовый класс рендерера, может получить доступ к его защищенным свойствам.
В каждом случае вы должны убедиться, что понимаете, как функция или свойство используется в остальной части кода.
частный
Доступ к ним возможен только через код в том же файле, что и определение. Прямой доступ к этим свойствам может привести к неопределенному поведению.
Подклассам не разрешается переопределять частные функции и свойства.
Частные свойства могут быть изменены без предупреждения, поскольку они не считаются частью публичного API Blockly.
Некоторые функции в Blockly не имеют аннотаций видимости, поскольку они не экспортируются из своего модуля. Эти функции по сути являются локальными переменными и не могут использоваться вне их определяющего модуля. Их следует считать эквивалентными частным свойствам.
внутренний
Внутренние функции и свойства предназначены для использования внутри основной библиотеки, но не снаружи. Они обозначены аннотацией TsDoc @internal .
Внутренние свойства могут быть изменены без предупреждения, поскольку они не считаются частью публичного API Blockly.
Внутренние свойства могут быть доступны из любого места в пределах ядра и переопределяться в подклассах в ядре, пока сигнатура не изменится. К ним нельзя обращаться извне библиотеки ядра.
устаревший
Все, что отмечено @deprecated не должно использоваться. Большинство устаревших версий содержат указания по предпочтительному коду, либо в предупреждении консоли, либо в TSDoc.
По возможности устаревшие функции будут регистрировать предупреждение, включающее предполагаемую дату удаления и рекомендацию по вызову заменяющей функции.
Часто задаваемые вопросы
Ниже приведены некоторые распространенные вопросы, с которыми столкнулась команда Blockly.
Что делать, если функция, которую я хочу использовать, не является общедоступной?
Подайте запрос на функцию в ядре Blockly. Включите описание вашего варианта использования и заявление о том, что вы хотели бы, чтобы мы сделали общедоступным.
Мы воспользуемся этой функцией, чтобы обсудить, следует ли сделать ее общедоступной или существуют ли другие способы получения вами той же информации.
Если мы решим сделать его общедоступным, вы или команда Blockly внесете соответствующие изменения, и они будут опубликованы в следующем выпуске Blockly.
Если вы решили использовать непубличный элемент в плагине, рассмотрите возможность отметить ваш плагин как бета-версию и включить информацию об этом в README .
А как насчет манкипатчинга?
Почитайте о MonkeyPatching .
Monkeypatching небезопасен, поскольку патчи могут перестать работать без предупреждения из-за использования непубличных частей Blockly API. Патчинг в плагине особенно опасен, поскольку ваш код может плохо взаимодействовать с любым другим плагином, который monkeypatching того же кода. По этой причине мы настоятельно рекомендуем не использовать monkeypatching в приложениях и сторонних плагинах и не будем принимать его в собственных плагинах.
Могу ли я переопределить публичные функции?
При подклассификации: да. В противном случае: нет, это monkeypatching.
Могу ли я переопределить защищенные функции?
При подклассификации: да. В противном случае: нет, это monkeypatching.
Могу ли я переопределить внутренние или частные функции?
Нет, это манкпатчинг.
Когда я могу получить доступ к свойствам напрямую? Когда мне следует использовать геттер или сеттер?
Если мы публикуем геттер или сеттер, пожалуйста, используйте его вместо прямого доступа к свойству. Если свойство не является публичным, обязательно используйте геттеры и сеттеры.
Что делать, если у свойства нет аннотации?
По умолчанию он публичный, но, пожалуйста, напишите нам, если мы захотим создать для вас пару getter/setter.
Что делать, если у функции нет аннотации?
По умолчанию он общедоступный.
Что делать, если я все еще не уверен?
Задайте вопрос на форуме , и мы ответим вам в течение нескольких дней.