Plug-ins

Um plug-in é um código independente que adiciona funcionalidade ao Blockly. Por exemplo, ele pode adicionar um campo personalizado, definir um novo tema ou fornecer um renderizador personalizado. Os plug-ins geralmente são empacotados e distribuídos pelo npm.

Observação: o objeto BlocklyOptions tem uma propriedade plugins para injetar classes que personalizam o comportamento do Blockly. Embora essas classes possam ser implementadas como plug-ins, isso não é obrigatório, e elas não têm relação entre si.

Para uma introdução rápida aos plug-ins, consulte nossa Palestra de visão geral dos plug-ins (2021).

Se você quiser criar seu próprio plug-in, consulte Adicionar um plug-in.

Plug-ins próprios e de terceiros

Os plug-ins próprios têm suporte da equipe do Blockly e são publicados no escopo @blockly no npm. Eles foram projetados para serem usados em uma ampla variedade de aplicativos do Blockly.

Os plug-ins de terceiros são mantidos e publicados de forma independente. Eles podem ser mais complexos, mais experimentais ou direcionados a um intervalo menor de aplicativos do Blockly.

Encontrar um plug-in

• Acesse Plugins e demonstrações do Blockly, que tem demonstrações ao vivo de plugins próprios.

• Pesquise keyword:blockly-plugin no npm. Os plug-ins com o escopo @blockly são publicados pela equipe do Blockly. Para resultados mais amplos, pesquise keyword:blockly ou blockly.

• Consulte o diretório blockly-samples/plugins no GitHub, que é o repositório de plug-ins próprios. Cada plug-in tem um README que descreve o comportamento e o uso pretendido.

Instalar um plug-in

Recomendamos instalar plug-ins com um gerenciador de pacotes, como npm ou yarn. Isso facilita o recebimento de atualizações.

• Instalar um plug-in com um gerenciador de pacotes

  npm

  npm install @blockly/field-angle
  

  novelo

  yarn add @blockly/field-angle
  

• Instalar um plug-in sem um gerenciador de pacotes

  unpkg

  <script src="https://unpkg.com/@blockly/field-angle"></script>
  

  Você também pode clonar o repositório do GitHub que contém o plug-in. Para plug-ins próprios, é blockly-samples.

Verifique o README do plug-in para saber se há outras instruções de instalação.

Usar um plug-in

Cada plug-in é diferente. Consulte o README do plug-in para saber como usá-lo. O exemplo a seguir mostra como usar o plug-in @blockly/field-angle:

1. Importe o código do plug-in. A maneira de fazer isso depende de como você instalou o plug-in.

   npm ou yarn

   import Blockly from 'blockly';
   import {registerFieldAngle} from '@blockly/field-angle';
   

   unpkg

   Não é necessário usar uma instrução import.

   Repositório clonado

   import {registerFieldAngle} from 'path/to/plugin';
   

2. Inicialize o plug-in conforme necessário. Os plug-ins que fornecem campos personalizados geralmente exigem que você registre o campo:

   registerFieldAngle();
   

3. Use o plug-in.

   Blockly.common.defineBlocksWithJsonArray([
     {
       type: "my_angle_block",
       message0: "%1 degrees",
       args0: [
         {
           // Use @blockly/field-angle.
           type: "field_angle",
           name: "FIELDNAME",
           value: 45,
         },
       ],
       output: null,
       style: 'math_blocks'
     },
   ]);
   

   

Versões do plug-in

Os plug-ins no blockly-samples usam o controle de versões semântico, que exige mudanças interruptivas para usar uma nova versão principal. Qualquer plug-in novo que faça patches monkey no núcleo terá uma versão principal de 0 para indicar o desenvolvimento inicial.

A maioria dos plug-ins inclui o pacote blockly como um peerDependency em vez de um dependency. Isso acontece porque presumimos que você já instalou o Blockly. Não faz sentido usar um plug-in sem usar o Blockly. Isso permite que você gerencie a versão do Blockly, mas também exige que você verifique o package.json do plug-in para determinar a versão mínima do Blockly necessária. Se um plug-in for atualizado para precisar de uma versão mais recente do Blockly, isso será considerado uma mudança interruptiva, e a versão principal dele será incrementada.

Quando você adiciona um plug-in ao package.json do aplicativo, o padrão é incluir um caret antes da versão:

"dependencies": {
  "@blockly/field-angle": "^5.0.12"
}

Isso permite que o npm instale qualquer versão secundária igual ou superior à versão listada. Portanto, a versão 5.0.20 ou 5.1.0 funciona, mas uma nova versão principal, como 6.0.1, não funciona. Ao atualizar para uma nova versão do Blockly, é recomendável verificar se alguns dos seus plug-ins também podem ser atualizados para uma nova versão principal.