Плагины

Плагин — это самостоятельный фрагмент кода, который добавляет функциональность Blockly. Например, он может добавлять пользовательское поле, определять новую тему или предоставлять пользовательский рендерер. Плагины обычно упаковываются и распространяются через npm.

Для краткого введения в плагины ознакомьтесь с нашим докладом «Обзор плагинов» (2021) .

Если вы хотите создать свой собственный плагин, см. раздел Добавить плагин .

Собственные и сторонние плагины

Плагины первой стороны поддерживаются командой Blockly и публикуются под @blockly scope на npm. Они разработаны для использования в широком спектре приложений Blockly.

Плагины сторонних разработчиков поддерживаются и публикуются независимо. Они могут быть более сложными, более экспериментальными или нацеленными на более узкий круг приложений Blockly.

Найти плагин

  • Посетите Blockly Plugins & Demos , где представлены живые демонстрации плагинов собственной разработки.

  • Найдите в npm keyword:blockly-plugin . Плагины с областью действия @blockly публикуются командой Blockly. Для более широких результатов выполните поиск по keyword:blockly или blockly .

  • См. каталог blockly-samples/plugins на GitHub, который является репозиторием для плагинов первой стороны. У каждого плагина есть файл README, описывающий его поведение и предполагаемое использование.

Установить плагин

Мы рекомендуем устанавливать плагины с помощью менеджера пакетов, например npm или yarn. Это упрощает получение обновлений.

  • Установить плагин с помощью менеджера пакетов

    нпм 

    npm install @blockly/field-angle

    пряжа 

    yarn add @blockly/field-angle

  • Установить плагин без менеджера пакетов

    распаковать 

    <script src="https://unpkg.com/@blockly/field-angle"></script>

    Вы также можете клонировать репозиторий GitHub, содержащий плагин. Для плагинов первой стороны это blockly-samples .

Проверьте файл README плагина, чтобы узнать, есть ли там дополнительные инструкции по установке.

Использовать плагин

Каждый плагин отличается, поэтому см. README плагина для получения информации о том, как использовать этот плагин. Следующий пример показывает, как использовать плагин @blockly/field-angle :

  1. Импортируйте код из плагина. Как это сделать, зависит от того, как вы установили плагин.

    нпм или пряжа 

    import Blockly from 'blockly';
import {registerFieldAngle} from '@blockly/field-angle';

    распаковать

    Вам не нужно использовать оператор import .

    Клонированный репозиторий 

    import {registerFieldAngle} from 'path/to/plugin';

  2. Инициализируйте плагин по мере необходимости. Плагины, которые предоставляют пользовательские поля, часто требуют регистрации поля:

    registerFieldAngle();

  3. Используйте плагин.

    Blockly.common.defineBlocksWithJsonArray([
  {
    type: "my_angle_block",
    message0: "%1 degrees",
    args0: [
      {
        // Use @blockly/field-angle.
        type: "field_angle",
        name: "FIELDNAME",
        value: 45,
      },
    ],
    output: null,
    style: 'math_blocks'
  },
]);

    Поле для выбора угла из 360-градусной шкалы.

Версии плагина

Плагины в blockly-samples используют семантическое управление версиями , которое требует критических изменений для использования новой основной версии. Любой новый плагин, который патчит ядро, будет иметь основную версию 0, что означает начальную разработку .

Большинство плагинов включают пакет blockly как peerDependency , а не как dependency . Это связано с тем, что мы предполагаем, что вы уже установили Blockly. (Не имеет смысла использовать плагин без Blockly.) Это позволяет вам управлять версией Blockly самостоятельно, но также требует проверки package.json плагина, чтобы определить минимальную версию Blockly, которую он требует. Если плагин обновляется для того, чтобы ему требовалась более новая версия Blockly, это считается критическим изменением, и его основная версия будет увеличена.

При добавлении плагина в package.json вашего приложения по умолчанию перед версией ставится знак вставки:

"dependencies": {
  "@blockly/field-angle": "^5.0.12"
}

Это позволит npm установить любую второстепенную версию, которая находится на уровне или выше указанной версии, поэтому версия 5.0.20 или 5.1.0 работает, но новая основная версия, такая как 6.0.1 не работает. При обновлении до новой версии Blockly, хорошей идеей будет проверить, можно ли обновить какой-либо из ваших плагинов до новой основной версии.