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 seus blocos e permita que os usuários possam instalar apenas determinados blocos ou partes de blocos que eles escolherem.
- Facilite a instalação de tudo: você pode fazer isso fornecendo uma função que instala cada parte que uma única definição de bloco exige (como mutadores, extensões, mixins, campos etc.). Você também pode fornecer 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 precisam manter o controle sobre o que é instalado 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 - 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');
    }
  }

O uso do registro de campo facilita a substituição da implementação do campo usado no bloco sem precisar mudar 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 por conta própria na função install fornecida.
- Em breve, o Blockly vai oferecer ferramentas que permitem registrar itens já registrados sem erros. Até lá, verifique o que já foi registrado antes de registrar uma extensão, mutator, mixin ou campo.
- Seja claro sobre os pré-requisitos ou dependências necessários para as definições de plug-in ou bloco.
Considere fornecer funções de gerador para cada um dos blocos que você fornece.
- Fornecer funções de gerador que funcionam prontos para uso facilita a utilização dos blocos pelos usuários sem que eles precisem entender a estrutura e o design. Se eles precisarem 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 problemas de "ajuda" para linguagens em que você não consegue implementar funções de gerador e aceite solicitações de envio para eles caso um usuário contribua.
- 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ível, você poderá instalar automaticamente a função do gerador de código de bloco 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, 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.