Esta página descreve 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 e à integração do Blockly em um aplicativo independente.
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
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úblico
Tudo o que está 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. A exceção: podemos tornar uma nova API pública em uma versão e modificá-la na próxima versão em resposta ao feedback inicial. Depois disso, você pode considerar 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.
protegida
As funções e propriedades protegidas só podem ser acessadas pela classe de definição ou por uma subclasse.
As subclasses podem 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, é necessário entender como a função ou propriedade é usada no restante do código.
privado
Eles só podem ser acessados por código no mesmo arquivo da definição. O acesso direto a essas propriedades pode resultar em um comportamento indefinido.
As subclasses não podem substituir funções e propriedades privadas.
As propriedades privadas estão sujeitas a mudanças sem aviso, já que 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. Essas funções são essencialmente variáveis locais e não podem ser usadas fora do módulo de definição. Elas precisam ser consideradas equivalentes a propriedades particulares.
interno
As funções e propriedades internas são destinadas a serem usadas na biblioteca
principal, mas não externamente. Elas são designadas com a anotação
@internal do TsDoc.
As propriedades internas estão sujeitas a mudanças sem aviso, já que não são consideradas parte da API pública do Blockly.
As propriedades internas podem ser acessadas de qualquer lugar no núcleo e substituídas em subclasses no núcleo, desde que a assinatura não mude. Eles não podem ser acessados de fora da biblioteca principal.
descontinuado
Não use nada marcado como @deprecated. A maioria das descontinuações inclui
instruções sobre o código preferido, em um aviso do console ou no TSDoc.
Sempre que possível, as funções descontinuadas vão registrar um aviso que inclui a data de exclusão pretendida e uma recomendação para chamar uma função de substituição.
Perguntas frequentes
Confira a seguir algumas perguntas comuns que a equipe do Blockly já recebeu.
E se a função que eu quero usar não for pública?
Envie uma solicitação de recurso no Blockly principal. Inclua uma descrição do seu caso de uso e uma declaração do que você quer que seja divulgado.
Vamos usar o recurso para discutir se ele será disponibilizado publicamente ou se há outras maneiras de você receber as mesmas informações.
Se decidirmos tornar o conteúdo público, você ou a equipe do Blockly vai fazer a mudança adequada, e ela será ativada na próxima versão do Blockly.
Se você optar por usar um membro não público em um plug-in, considere marcar o
plug-in como Beta e incluir as informações no README.
E o monkeypatching?
Leia mais sobre monkeypatching.
O monkeypatching não é seguro, porque os patches podem parar de funcionar sem aviso devido ao uso de partes não públicas da API Blockly. Fazer o patching em um plug-in é especialmente perigoso, porque o código pode interagir mal com qualquer outro plug-in que faça monkeypatch do mesmo código. Por esse motivo, recomendamos que você não use monkeypatching em aplicativos e plug-ins de terceiros e não o aceite em plug-ins próprios.
Posso substituir funções públicas?
Ao criar subclasses: sim. Caso contrário, não, isso é monkeypatching.
Posso substituir funções protegidas?
Ao criar subclasses: sim. Caso contrário, não, isso é monkeypatching.
Posso substituir funções internas ou privadas?
Não, isso é monkeypatching.
Quando posso acessar as propriedades diretamente? Quando devo usar um getter ou um setter?
Se publicarmos um getter ou setter, use-o em vez de acessar diretamente a propriedade. 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 entre em contato se quisermos colocar um par de 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ê em alguns dias.