Публикация библиотек блоков

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

Рекомендации

  • Упростите для пользователей установку всех ваших блоков и дайте им возможность устанавливать только определенные блоки или части блоков по их выбору.
    • Упростите установку всего: вы можете сделать это, предоставив функцию, которая устанавливает каждую часть, необходимую для определения одного блока (например, мутаторы, расширения, примеси, поля и т. д.). Вы также можете предоставить функцию, которая одновременно установит все блоки, предлагаемые вашим плагином.
    • Предоставьте возможность выбора определенных частей: вам следует экспортировать все части определения блока отдельно, чтобы пользователь мог импортировать только те части, которые ему нужны для создания собственного аналогичного пользовательского блока.
  • Избегайте использования побочных эффектов в вашем плагине.
    • Блоки, поля, расширения и другие элементы не должны устанавливаться как побочный эффект загрузки вашего плагина. Пользователи должны контролировать, какие компоненты и когда устанавливаются. Это позволяет пользователям импортировать те части, которые им нужны, не беспокоясь о том, что те части, которые им не нужны, будут установлены.

  • Используйте реестр полей JSON вместо непосредственного создания экземпляров новых полей.

    • Не рекомендуется — создание экземпляра нового поля напрямую:

        const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(new Blockly.FieldNumber(123), 'NAME');
    }
  }

    • Рекомендуется — реестр полей JSON:

        export const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(Blockly.fieldRegistry.fromJson({
              name: 'field_number',
              value: 123,
            }), 'NAME');
    }
  }

    • Использование реестра полей упрощает пользователю замену реализации поля, используемого в вашем блоке, без необходимости изменять определение блока.

  • Не делайте предположений о том, что пользователь уже установил.

    • Если вашему плагину требуется настраиваемое поле или другой плагин, зарегистрируйте эти поля самостоятельно в предоставленной функции install .
    • Вскоре Blockly предоставит инструменты, которые позволят вам без ошибок регистрировать уже зарегистрированные элементы. А пока вы можете проверить, что уже зарегистрировано, прежде чем самостоятельно регистрировать расширение, мутатор, миксин или поле.
    • Четко обозначьте любые предварительные условия или зависимости, которые требуются для определения вашего плагина или блока.

  • Рассмотрите возможность предоставления функций генератора для каждого из предоставленных вами блоков.

    • Предоставление функций генератора, которые работают «из коробки», упрощает пользователям использование ваших блоков без необходимости разбираться в их структуре и дизайне. Если им придется писать свои собственные функции-генераторы, это может привести к избыточной работе, выполняемой каждым пользователем.
    • JavaScript является наиболее часто используемым языком в Blockly, поэтому, если вы выбираете только один язык, мы рекомендуем JavaScript, если только ваши блоки не созданы для определенного языка, например, для реализации библиотеки Python.
    • Рассмотрите возможность публикации проблем с просьбой о помощи для языков, для которых вы не можете реализовать функции генератора, и принимайте запросы на включение для них, если пользователь их вносит.

    • Если вы предоставляете функцию установки для своего блока, вы можете принять дополнительный параметр generators . Если пользователь передает экземпляр генератора, который вы поддерживаете, вы можете автоматически установить функцию генератора блочного кода и выполнить соответствующую работу, например добавить зарезервированные слова: 

        // Your plugin's install function
  export const installMyCustomBlock(generators = {}) {
    Blockly.defineBlocks({my_custom_block: myCustomBlock});
    if (generators.javascript) {
      generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
      generators.javascript.addReservedWords('specialReservedWord');
    }
  }

  // How a user may install your block
  import {javascriptGenerator} from 'blockly/javascript';
  import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
  // installs the block definition and the javascript block-code generator
  installMyCustomBlock({javascript: javascriptGenerator});

Обратная связь

Если у вас есть вопросы о том, как лучше всего следовать этим рекомендациям в вашем плагине, сообщите нам об этом на форуме! Мы будем рады увидеть ваши библиотеки блоков и оставить отзыв о них.

Обратите внимание, что не все сторонние плагины, предоставляющие определения блоков, в настоящее время следуют этим рекомендациям, но новые плагины будут следовать этим рекомендациям, и мы планируем перенести существующие плагины.