Como usar as APIs do Blockly

Introdução

Nesta página, descrevemos as práticas recomendadas para chamar funções e acessar propriedades no núcleo do Blockly. Esses princípios se aplicam à criação de plug-ins para o Blockly ou à integração do Blockly a um aplicativo independente.

Criação de subclasses e extensão

O Blockly tem vários paradigmas para adicionar funcionalidades, incluindo:

• Subclasses (por exemplo, criar um novo renderizador)
• Mixins (por exemplo, adicionar uma extensão de bloqueio ou um mutador)
• Definições de bloco (por exemplo, definições de bloco de procedimento)

Para os fins deste documento, os três casos são equivalentes à criação de subclasses.

Como injetar subclasses

Oferecemos suporte à substituição de determinadas classes pelo método Blockly.inject. Essas subclasses precisam estender a classe de base ou implementar a interface correspondente.

É possível passar a subclasse para o método de injeção.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

Também é possível registrar a classe usando Blockly.registry e usar o nome do registro para injetar a classe. Isso é útil se você armazenar as opções de injeção como JSON puro.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

As seguintes classes podem ser substituídas:

Nome do registro	Classe de interface/base
blockDragger	Blockly.IBlockDragger
connectionChecker	Blockly.IConnectionChecker
connectionPreviewer	Blockly.IConnectionPreviewer
flyoutsVerticalToolbox	Blockly.IFlyout
flyoutsHorizontalToolbox	Blockly.IFlyout
metricsManager	Blockly.IMetricsManager
renderer	Blockly.blockRendering.Renderer
toolbox	Blockly.IToolbox

Para mais informações sobre o uso de interfaces, consulte a seção de interfaces da documentação.

Observação: todos os métodos protegidos e públicos em classes registradas podem ser substituídos. No entanto, os métodos protegidos em classes não registradas não podem ser substituídos.

Visibilidade

Usamos modificadores de acesso do TypeScript para marcar a visibilidade na biblioteca principal como public, private ou protected. Algumas propriedades podem ser anotadas com @internal nos comentários do TsDoc.

Todas as propriedades public e protected estão documentadas na seção Referências do site do Blockly. Também é possível verificar a visibilidade lendo o código.

Cuidado: embora o JavaScript não imponha essas anotações de visibilidade, evite acessar qualquer item que não seja public. A equipe do Blockly não garante a estabilidade de propriedades e funções não públicas entre as versões.

pública

Tudo o que for marcado como public faz parte da nossa API pública. Qualquer propriedade em um módulo que não tenha um modificador de visibilidade é considerada pública.

Tentamos não mudar nossa API pública com frequência ou sem um bom motivo e aviso. Exceção: podemos tornar uma nova API pública em uma versão e modificá-la na próxima em resposta ao feedback antecipado. Depois disso, considere uma função ou propriedade pública estável.

As funções públicas podem ser chamadas de qualquer lugar e substituídas em subclasses, desde que a assinatura não mude.

protegido

As funções e propriedades protegidas só podem ser acessadas pela classe ou subclasse definida.

As subclasses têm permissão para substituir funções e propriedades protegidas, sem mudar as assinaturas de tipo.

Por exemplo, um renderizador personalizado que estende a classe de renderizador base pode acessar as propriedades protegidas.

Em cada caso, você precisa entender como a função ou propriedade é usada no restante do código.

particular

Elas só podem ser acessadas por código no mesmo arquivo da definição. O acesso direto a essas propriedades pode resultar em comportamento indefinido.

As subclasses não têm permissão para substituir funções e propriedades privadas.

As propriedades particulares estão sujeitas a mudanças sem aviso prévio, porque não são consideradas parte da API pública do Blockly.

Algumas funções no Blockly não têm anotações de visibilidade porque não são exportadas do módulo delas. Essas funções são essencialmente variáveis locais e não podem ser usadas fora do módulo definido. Elas precisam ser consideradas equivalentes às propriedades particulares.

Observação: anteriormente, o Blockly usava um sublinhado para denotar propriedades particulares: example_. Para manter o Guia de estilo atual do Google, não fazemos mais isso no novo código e é possível que o código antigo seja alterado. Antes de chamar um método no Blockly, verifique se ele aparece na documentação de referência ou não está marcado como particular no código. Em casos raros, as funções privadas foram usadas tão amplamente que se tornaram públicas. Por isso, é possível que você encontre funções públicas que terminam em um sublinhado.

interno

As funções e propriedades internas destinam-se ao uso dentro da biblioteca principal, mas não externamente. Eles são designados com a anotação @internal do TsDoc.

As propriedades internas estão sujeitas a mudanças sem aviso prévio, porque não são consideradas parte da API pública do Blockly.

As propriedades internas podem ser acessadas de qualquer lugar dentro do núcleo e substituídas nas subclasses dele, desde que a assinatura não mude. Eles não podem ser acessados de fora da biblioteca principal.

descontinuado

Itens marcados como @deprecated não podem ser usados. A maioria das descontinuações inclui instruções no código preferencial, seja em um aviso do console ou no TSDoc.

Sempre que possível, as funções descontinuadas registrarão um aviso que inclui a data de exclusão pretendida e uma recomendação para uma função de substituição a ser chamada.

Perguntas frequentes

E se a função que eu quero usar não for pública?

Envie uma solicitação de recurso no Blockly do núcleo. Inclua uma descrição do seu caso de uso e uma declaração do que você quer que seja público.

Vamos usar o recurso para fazer uma solicitação para decidir se ele será público ou se há outras maneiras de receber as mesmas informações.

Se decidirmos torná-lo público, você ou a equipe do Blockly farão a alteração apropriada, e ela será publicada na próxima versão do Blockly.

Se você optar por usar um membro não público em um plug-in, marque-o como Beta e inclua as informações no seu README.

E quanto ao monkeypatch?

Leia mais sobre monkeypatch.

O Monkeypatch não é seguro, porque os patches podem parar de funcionar sem aviso prévio devido ao uso de partes não públicas da API Blockly. Aplicar um patch em um plug-in é especialmente perigoso, porque seu código pode interagir mal com qualquer outro plug-in que executa patches de monkey o mesmo código. Por esse motivo, é altamente recomendável (não aceitar) o monkeypatch em aplicativos e plug-ins de terceiros. Ele não é aceito em plug-ins primários.

Posso substituir funções públicas?

Ao criar subclasses: sim. Caso contrário: não, é monkeypatch.

Posso substituir funções protegidas?

Ao criar subclasses: sim. Caso contrário: não, é monkeypatch.

Posso substituir funções internas ou privadas?

Não, isso é monkeypatch.

Quando posso acessar propriedades diretamente? Quando devo usar um getter ou um setter?

Se publicarmos um getter ou um setter, use-o em vez de acessar a propriedade diretamente. Se a propriedade não for pública, use getters e setters.

Observação: o uso consistente de getters e setters em plug-ins oferece flexibilidade para fazer mudanças no Blockly principais sem corromper o código publicado.

E se uma propriedade não tiver uma anotação?

Por padrão, ele é público, mas insira uma linha caso queiramos implementar um par getter/setter para você.

E se uma função não tiver uma anotação?

Ela é pública por padrão.

E se eu ainda não tiver certeza?

Faça uma pergunta no fórum e entraremos em contato com você, geralmente em um dia útil.