Introdução
Esta página descreve as práticas recomendadas para chamar funções e acessar no núcleo do Blockly. Esses princípios se aplicam à criação de plug-ins para Blockly ou integração do Blockly com um aplicativo independente.
Criação de subclasses e extensão
O Blockly tem vários paradigmas para adicionar funcionalidades, incluindo:
- Subclasses (por exemplo, criação de um novo renderizador)
- Mixins (por exemplo, adição de uma extensão de bloqueio ou mutador)
- Definições de bloqueio (por exemplo, definições de bloqueio de procedimento)
Para os fins deste documento, todos os três casos são equivalentes a a subclassificação.
Como injetar subclasses
É possível substituir determinadas classes com o método Blockly.inject. Esses
as subclasses precisam estender a classe de base ou implementar as
interface gráfica do usuário.
É possível transmitir a subclasse no método de injeção.
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
Ou você pode registrar sua classe usando Blockly.registry e usar o
para injetar a classe. Isso é útil se você armazena
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 | Interface/classe 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 TypeScript.
para marcar a visibilidade na biblioteca principal como public, private ou protected.
Algumas propriedades podem receber a anotação @internal na
Comentários do TsDoc.
Todas as propriedades public e protected estão documentadas na
Seção Referências do site do Blockly. Você também pode
verificar a visibilidade lendo o código.
público
Tudo o que estiver marcado com public faz parte da nossa API pública. Qualquer propriedade em um módulo
que não tem um modificador de visibilidade é considerado público.
Tentamos não mudar nossa API pública com frequência ou sem um bom motivo. aviso. Exceção: podemos tornar uma nova API pública em uma versão e modificá-lo na próxima versão em resposta ao feedback antecipado. Depois disso, você pode uma função pública ou propriedade estável.
As funções públicas podem ser chamadas de qualquer lugar e substituídas em subclasses como desde que a assinatura não mude.
protegia
As funções e propriedades protegidas só podem ser acessadas pela classe ou uma subclasse.
As subclasses têm permissão para substituir funções e propriedades protegidas, sem alteração de assinaturas de tipo.
Por exemplo, um renderizador personalizado que estende a classe de renderizador base pode acessar das propriedades protegidas.
Em cada caso, você deve entender como a função ou propriedade está usada no restante do código.
privado
Eles só podem ser acessados por código no mesmo arquivo da definição. Diretamente acessar essas propriedades pode resultar em um comportamento indefinido.
As subclasses não têm permissão para substituir funções e propriedades particulares.
As propriedades particulares estão sujeitas a alterações sem aviso prévio, pois não estão considerada parte da API pública do Blockly.
Algumas funções no Blockly não têm anotações de visibilidade porque são não exportados do módulo. Essas funções são essencialmente variáveis locais e não pode ser usado fora do módulo de definição. Elas devem ser consideradas equivalentes às propriedades privadas.
interno
As funções e propriedades internas destinam-se ao uso no sistema
biblioteca, mas não externamente. Eles são designados com o TsDoc @internal
uma anotação.
As propriedades internas estão sujeitas a alterações sem aviso prévio, pois não estão considerada parte da API pública do Blockly.
As propriedades internas podem ser acessadas de qualquer lugar do principal e substituídas em subclasses no núcleo, desde que a assinatura não mude. Elas não podem ser acessados de fora da biblioteca principal.
descontinuado
Tudo o que estiver marcado como @deprecated não deve ser usado. A maioria das descontinuações inclui
instruções sobre o código preferido, seja em um aviso do console ou no TSDoc.
Sempre que possível, as funções descontinuadas registrarão um aviso que inclui o 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?
Enviar uma solicitação de recurso no Blockly de base. Inclua uma descrição do seu caso de uso e uma declaração do que que você quer tornar públicas.
Usaremos o recurso para solicitar a definição do conteúdo como público ou se há outras formas de obter as mesmas informações.
Se decidirmos torná-la pública, você ou a equipe do Blockly alteração apropriada, 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, marque o seu
plug-in 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 ao uso de partes não públicas da API Blockly. Aplicar o patch em um plug-in é especialmente perigoso, porque seu código pode interagir mal com qualquer outro plug-in que aplica monkeypatch o mesmo código. Por isso, nós altamente não recomendam o monkeypatching em aplicativos e plug-ins de terceiros, e não a aceitarão em plug-ins primários.
Posso substituir funções públicas?
Ao criar subclasses: sim. Caso contrário: não, trata-se de monkeypatch.
Posso substituir funções protegidas?
Ao criar subclasses: sim. Caso contrário: não, trata-se de monkeypatch.
Posso substituir funções internas ou privadas?
Não, isso é monkeypatch.
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 diretamente acessar a propriedade. Se a propriedade não for pública, definitivamente use getters e setters.
E se uma propriedade não tiver uma anotação?
Por padrão, é público, mas envie-nos um comentário caso queiramos colocar um getter/setter para você.
E se uma função não tiver uma anotação?
É público por padrão.
E se eu ainda não tiver certeza?
Faça uma pergunta no fórum e entraremos em contato, geralmente em até um dia útil.