Plug-ins

Introdução

Um plug-in é uma parte de código independente que adiciona funcionalidade ao Blockly. Os plug-ins podem adicionar campos, definir temas, criar renderizadores e muito mais.

O usuário de destino de um plug-in é um desenvolvedor que encontra e usa o plug-in por meio do npm. Para mais informações sobre como criar um plug-in, assista à palestra Como criar um plug-in 2021 e Visão geral dos plug-ins 2021 (links em inglês).

Próprios x de terceiros

Os plug-ins definidos no repositório blockly-samples são plug-ins próprios, o que significa que eles têm suporte da equipe do Blockly e são publicados sob o escopo @blockly no npm.

Ótimos plug-ins próprios:

• têm casos de uso óbvios
• são de uso geral
• sejam estáveis
• sejam fáceis de usar

Plug-ins de terceiros são mantidos e publicados de maneira independente. Os plug-ins de terceiros podem ser mais complexos, experimentais ou mais direcionados.

Por exemplo, um campo para definir a velocidade do motor pode ser usado em muitos projetos de robótica. Por outro lado, um campo para editar um objeto específico definido pelo esquema do banco de dados é melhor como um plug-in de terceiros.

Critérios próprios

Plug-ins próprios precisam atender a estes requisitos:

• Funciona em todas as principais plataformas, a menos que a equipe do Blockly conceda uma isenção.
  • Chrome, Firefox, Safari, Edge
• Tem um autor disposto a lidar com bugs pelo primeiro ano.
• Não usa o monkeypatch Blockly.
• Tem uma API claramente definida e documentada.
• Não chama funções privadas ou de pacote do núcleo do Blockly, a menos que a equipe do Blockly conceda uma isenção.
  • É permitido substituir funções de pacote em uma subclasse definida por você.
  • Se quiser uma isenção, fale com nossa equipe sobre um problema de amostragens em blocos.
• Tem testes.

Tudo pronto para criar um plug-in? Siga este guia sobre como adicionar um plug-in para blockly-samples.

Como encontrar plug-ins

• Nas páginas do GitHub (em inglês), confira demonstrações ao vivo de plug-ins próprios.
• No npm: pesquise por @blockly para ver uma lista dos plug-ins publicados pela equipe do Blockly.
• No GitHub (link em inglês), consulte o diretório de plug-ins (link em inglês) no repositório blockly-samples. Cada plug-in tem um README que descreve o comportamento e o uso pretendido.

Instalar plug-ins

1. Encontre o plug-in que você quer instalar usando um dos recursos acima e localize o README.

2. Siga as instruções de instalação no README. Em geral, você precisará instalar o plug-in a partir do npm, por exemplo,

   npm install @blockly/block-plus-minus --save
   

   e importe-o em seu código, por exemplo,

   import Blockly from 'blockly';
   import '@blockly/block-plus-minus';
   

3. Alguns plug-ins podem exigir outras etapas, como inicialização ou registro do plug-in. Essas etapas serão listadas no README.

Versões do plug-in

Os plug-ins em blockly-samples seguem o controle de versões semântico. Portanto, todas as alterações interruptivas serão feitas em uma nova versão principal. Todos os novos plug-ins que dependem do núcleo de patching do Monkey terão uma versão principal de 0 para indicar o desenvolvimento inicial, conforme declarado na especificação semver (em inglês).

A maioria dos plug-ins inclui o pacote blockly principal como uma peerDependency, não como uma dependência. Isso ocorre porque esperamos que você já tenha instalado o Blockly no seu próprio aplicativo (não faria sentido usar um plug-in sem usar também o Blockly) e para que você possa gerenciar a versão do Blockly por conta própria. No entanto, muitos plug-ins são desenvolvidos para usar novas APIs encontradas na versão mais recente do Blockly. Portanto, você precisa estar ciente dos requisitos da versão. O package.json do plug-in vai informar qual é a versão mínima do Blockly compatível com esse plug-in. Se um plug-in for atualizado para precisar de uma versão mais recente do Blockly, por exemplo, para aproveitar uma nova API, a versão principal do plug-in será aumentada, porque consideramos essa uma alteração interruptiva.

Quando você adiciona o plug-in ao package.json, o padrão é incluir um circunflexo antes da versão, como

"@blockly/block-plus-minus": "^2.0.15"

Isso permitirá que o npm instale qualquer versão secundária ou superior à versão listada. Portanto, a versão 2.0.20 ou 2.1.0 pode funcionar, mas não uma nova versão principal, como 3.0.1. Quando você atualiza para uma nova versão do Blockly, é uma boa ideia verificar se algum dos seus plug-ins também pode ser atualizado para uma nova versão principal.

Como instalar plug-ins sem npm

Embora geralmente seja recomendado usar o NPM para receber atualizações com facilidade, é possível usar plug-ins sem NPM.

Você pode usar o unpkg para incluir os arquivos do plug-in sem cloná-los, por exemplo,

<script src="https://unpkg.com/@blockly/block-plus-minus"></script>

Ou você pode clonar o repositório blockly-samples e incluir os arquivos localmente, da mesma forma que faria se tivesse clonado o Blockly. No entanto, recomendamos que você use um gerenciador de pacotes, se possível, já que ele o ajudará a ficar por dentro dos recursos e correções de bugs mais recentes do plug-in.

Com esse método, você ainda vai precisar realizar as etapas de inicialização ou registro listadas no README do plug-in.