Опубликовать библиотеки блоков

Плагины, предоставляющие библиотеки определений блоков, — отличный способ поделиться своими повторно используемыми блоками с сообществом 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.common.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});
    

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

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

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