Publicar bibliotecas do Block

Os plug-ins que fornecem bibliotecas de definições de bloco são uma ótima maneira de compartilhar seus blocos reutilizáveis com a comunidade do Blockly. Para tornar sua biblioteca de blocos o mais versátil e útil possível, desenvolvemos estas diretrizes.

Diretrizes

• Facilite a instalação de todos os blocos para os usuários e a possibilidade de instalar apenas determinados blocos ou blocos escolhidos.
  • Facilite a instalação de tudo: faça isso fornecendo uma função que instale todas as partes exigidas por uma única definição de bloco (como mutadores, extensões, mixins, campos etc.). Você também pode fornecer uma função que instalará todos os blocos oferecidos pelo plug-in de uma só vez.
  • Possibilitar a escolha de partes específicas: é necessário exportar todas as partes de uma definição de bloco separadamente para que o usuário possa importar apenas as partes necessárias para criar o próprio bloco personalizado semelhante.
• Evite usar efeitos colaterais no seu plug-in.
  • Blocos, campos, extensões e outras partes não podem ser instalados como efeito colateral do carregamento do plug-in. Os usuários devem manter o controle sobre quais coisas são instaladas e quando. Isso permite que os usuários importem as peças de que precisam sem se preocupar que as outras serão instaladas.

• Use o registro de campo JSON em vez de instanciar novos campos diretamente.

  • Não recomendado. Como instanciar um novo campo diretamente:

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

  • Recomendado - Registro de campo JSON:

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

  • Com o registro de campo, fica mais fácil para um usuário substituir a implementação do campo usado no bloco sem precisar alterar a definição do bloco.

• Não faça suposições sobre o que o usuário já instalou.

  • Se o plug-in exigir um campo personalizado ou outro plug-in, registre esses campos na função install fornecida.
  • Em breve, o Blockly fornecerá ferramentas que permitem registrar itens já registrados sem erros. Até lá, verifique o que já foi registrado antes de registrar uma extensão, mutador, mixin ou campo.
  • Esclareça todos os pré-requisitos ou dependências exigidos pelas definições de plug-in ou bloco.

• Considere fornecer funções geradoras para cada um dos blocos fornecidos.

  • Fornecer funções de gerador que funcionam prontamente facilita o uso dos blocos pelos usuários sem precisar entender a estrutura e o design deles. Se eles tiverem que escrever suas próprias funções geradoras, isso pode levar a um trabalho redundante ser feito por cada usuário.
  • O JavaScript é a linguagem mais usada no Blockly. Portanto, se você escolher apenas uma linguagem para fornecer, recomendamos o JavaScript, a menos que seus blocos sejam criados para uma linguagem específica, como a implementação de uma biblioteca Python.
  • Considere postar problemas de "solicitação de ajuda" para idiomas em que você não pode implementar funções do gerador e aceitar solicitações de envio para eles se um usuário contribuir com elas.

  • Se você fornecer uma função de instalação para seu bloco, poderá aceitar um parâmetro generators opcional. Se um usuário transmitir uma instância de gerador compatível, você poderá instalar automaticamente a função geradora de código de bloqueio e fazer trabalhos relacionados, como adicionar palavras reservadas:

      // 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});
    

Feedback

Se você tiver dúvidas sobre como seguir melhor essas diretrizes no seu plug-in, informe-nos no fórum. Adoraríamos ver suas bibliotecas de blocos e enviar feedback sobre elas.

No momento, nem todos os plug-ins próprios que fornecem definições de bloco seguem essas diretrizes, mas os novos plug-ins seguirão e planejamos migrar os plug-ins existentes.