Publicar bibliotecas de blocos

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

Diretrizes

• Facilite a instalação dos seus blocos para os usuários e facilite possível para os usuários instalarem apenas alguns blocos ou partes de blocos que eles escolherem.
  • Facilite a instalação de tudo: para isso, forneça uma função que instale cada parte que uma única definição de bloco exige, como modificadores, extensões, mixins, campos etc. Você também pode uma função que vai instalar todos os blocos oferecidos pelo plug-in de uma só vez.
  • Permitir a escolha de partes específicas: exporte todas as partes de uma definição de bloco separadamente para que o usuário possa importar apenas as partes necessárias para criar um bloco personalizado semelhante.
• Evite usar efeitos colaterais no plug-in.
  • Blocos, campos, extensões e outras partes não podem ser instalados como um efeito colateral do carregamento do plug-in. Os usuários devem manter o controle quais itens são instalados e quando. Isso permite que os usuários importem as peças necessárias sem se preocupar com as que não serão instaladas.

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

  • Não recomendado: 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');
        }
      }
    

  • O uso do registro de campo facilita a substituição da implementação do campo usado no bloco sem precisar mudar a definição dele.

• 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 vai oferecer ferramentas que permitem registrar itens já registrados sem erros. Até lá, talvez seja melhor verifique o que já foi registrado antes de registrar uma extensão, mutator, mixin ou campo.
  • Esclareça os pré-requisitos ou as dependências exigidas pelo suas definições de plug-in ou bloco.

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

  • Com funções de gerador prontas para uso, fica mais fácil para que os usuários usem seus bloqueios sem ter que entender estrutura e design. Se eles tiverem que escrever as próprias funções de gerador, isso poderá levar a um trabalho redundante 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 do Python.
  • Considere postar "Preciso de ajuda" problemas em idiomas para os quais você está incapaz de implementar funções de gerador e aceitar solicitações de envio para se um usuário contribuir com eles.

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

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

Feedback

Se você tiver dúvidas sobre como seguir melhor essas diretrizes no seu plug-in, entre em contato no fórum. Queremos conferir suas bibliotecas de blocos e dar feedback sobre elas.

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