Введение
На этой странице описаны лучшие практики вызова функций и доступа к свойствам в ядре Blockly. Эти принципы применимы к созданию плагинов для Blockly или к интеграции Blockly в автономное приложение.
Создание подклассов и расширение
Blockly имеет несколько парадигм для добавления функциональности, в том числе:
- Подклассы (например, создание нового средства визуализации)
- Миксины (например, добавление расширения блока или мутатора)
- Определения блоков (например, определения блоков процедур)
Для целей этого документа все три случая эквивалентны созданию подклассов.
Внедрение подклассов
Мы поддерживаем замену определенных классов с помощью метода 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 | Блокли.IBlockDragger |
connectionChecker | Блокли.IConnectionChecker |
connectionPreviewer | Блокли.IConnectionPreviewer |
flyoutsVerticalToolbox | Блокли.IFlyout |
flyoutsHorizontalToolbox | Блокли.IFlyout |
metricsManager | Блокли.IMetricsManager |
renderer | Blockly.blockRendering.Renderer |
toolbox | Блокли.IToolbox |
Для получения дополнительной информации об использовании интерфейсов обратитесь к разделу «Интерфейсы» документации.
Видимость
Мы используем модификаторы доступа 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.
Если вы решите использовать в плагине закрытого участника, рассмотрите возможность пометить свой плагин как бета-версию и включить эту информацию в свой README .
А как насчет патчинга обезьян?
Прочтите о манкипаттинге .
Monkeypatching небезопасен, поскольку патчи могут перестать работать без предварительного уведомления из-за использования закрытых частей Blockly API. Внесение исправлений в плагин особенно опасно, поскольку ваш код может плохо взаимодействовать с любым другим плагином, который исправляет тот же код. По этой причине мы настоятельно не рекомендуем использовать обезьяний патч в приложениях и сторонних плагинах и не принимаем его в сторонних плагинах.
Могу ли я переопределить публичные функции?
При создании подклассов: да. В противном случае: нет, это обезьяний патч.
Могу ли я переопределить защищенные функции?
При создании подклассов: да. В противном случае: нет, это обезьяний патч.
Могу ли я переопределить внутренние или частные функции?
Нет, это обезьяний патч.
Когда я могу получить прямой доступ к свойствам? Когда мне следует использовать геттер или сеттер?
Если мы публикуем геттер или сеттер, используйте его вместо прямого доступа к свойству. Если свойство не является общедоступным, обязательно используйте геттеры и сеттеры.
Что делать, если у свойства нет аннотации?
По умолчанию он общедоступен, но, пожалуйста, напишите нам, если мы захотим добавить для вас пару геттер/сеттер.
Что делать, если у функции нет аннотации?
По умолчанию это общедоступно.
Что, если я все еще не уверен?
Задайте вопрос на форуме , и мы ответим вам, как правило, в течение рабочего дня.