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.
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.
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.
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.
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.