Introduzione
In questa pagina vengono descritte le best practice per chiamare le funzioni e accedere nel core di Blockly. Questi principi si applicano alla creazione di plug-in A blocchi o all'integrazione di Blockly in un'applicazione autonoma.
Creazione di sottoclassi ed estensione
Blockly ha diversi paradigmi per l'aggiunta di funzionalità, tra cui:
- Sottoclassi (ad es. creazione di un nuovo renderer)
- Mixin (ad es. aggiunta di un'estensione di blocco o di un mutatore)
- Definizioni dei blocchi (ad es. definizioni dei blocchi delle procedure)
Ai fini del presente documento, tutti e tre i casi equivalgono a la creazione di sottoclassi.
Inserimento di sottoclassi
Supportiamo la sostituzione di alcuni corsi tramite il metodo Blockly.inject. Questi
le sottoclassi devono estendere la classe base o implementare le
a riga di comando.
Puoi passare la sottoclasse al metodo inject.
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
In alternativa, puoi registrare il corso utilizzando Blockly.registry e utilizzare la
del registro di sistema per inserire la classe. È utile se memorizzi l'iniezione
come JSON puro.
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
I seguenti corsi possono essere sostituiti:
| Nome registrazione | Classe interfaccia/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 |
Per ulteriori informazioni sull'uso delle interfacce, consulta la sezione Interfacce della documentazione.
Visibilità
Usiamo i modificatori di accesso TypeScript
per contrassegnare la visibilità nella raccolta principale come public, private o protected.
Alcune proprietà potrebbero essere annotate con @internal nei loro
Commenti di TsDoc.
Tutte le proprietà public e protected sono documentate in
Sezione Riferimenti del sito web di Blockly. Puoi anche
e controllarne la visibilità leggendo il codice.
pubblica
Tutto ciò che è contrassegnato come public fa parte della nostra API pubblica. Qualsiasi proprietà in un modulo
che non dispone di un modificatore di visibilità è considerata pubblica.
Cerchiamo di non modificare la nostra API pubblica frequentemente o senza un valido motivo. avviso. Eccezione: potremmo rendere pubblica una nuova API in una release e nella prossima release in risposta ai primi feedback. Dopodiché puoi considera stabili una funzione o una proprietà pubblica.
Le funzioni pubbliche possono essere chiamate da qualsiasi punto e sostituite nelle sottoclassi come purché la firma non venga modificata.
protetto
Le funzioni e le proprietà protette sono accessibili solo dalla classe che la definisce o una sottoclasse.
Le sottoclassi possono sostituire funzioni e proprietà protette, senza la modifica delle firme dei tipi.
Ad esempio, un renderer personalizzato che estende la classe di renderer di base potrebbe accedere le sue proprietà protette.
In ogni caso, devi assicurarti di comprendere com'è la funzione o la proprietà usato nel resto del codice.
privato
È possibile accedervi solo tramite codice nello stesso file della definizione. Direttamente che accedono a queste proprietà potrebbero avere un comportamento indefinito.
Le sottoclassi non possono eseguire l'override di funzioni e proprietà private.
Le proprietà private sono soggette a modifiche senza avviso, in quanto non lo sono è considerata parte dell'API pubblica di Blockly.
Alcune funzioni in Blockly non hanno annotazioni di visibilità perché sono non esportati dal modulo. Queste funzioni sono essenzialmente variabili locali e non possono essere utilizzati al di fuori del modulo che lo definiscono. Dovrebbero essere prese in considerazione equivalenti alle proprietà private.
interno
Le funzioni e le proprietà interne sono destinate a essere utilizzate all'interno
ma non esternamente. Sono designati con il documento TsDoc @internal
annotazione.
Le proprietà interne sono soggette a modifiche senza preavviso, in quanto non sono è considerata parte dell'API pubblica di Blockly.
È possibile accedere alle proprietà interne da qualsiasi punto del core e sostituirle in solo se la firma non cambia. Non devono essere a cui si accede dall'esterno della libreria di base.
ritirato
Gli elementi contrassegnati con @deprecated non devono essere utilizzati. La maggior parte dei ritiri include
sul codice preferito, in un avviso della console o in un TSDoc.
Se possibile, le funzioni deprecate registrano un avviso che include il parametro data di eliminazione prevista e un suggerimento per la chiamata di una funzione sostitutiva.
Domande frequenti
Cosa succede se la funzione che voglio utilizzare non è pubblica?
Invia una richiesta di funzionalità sul core di Blockly. Includi una descrizione del caso d'uso e una dichiarazione di cosa che desideri rendere pubblici.
Utilizzeremo la funzionalità per chiedere di stabilire se renderla pubblica o se esistono altri modi per ottenere le stesse informazioni.
Se decidiamo di renderlo pubblico, tu o il team di Blockly compirete la modifica appropriata e verrà pubblicato con la prossima release di Blockly.
Se scegli di utilizzare in un plug-in un membro non pubblico, valuta l'opportunità di contrassegnare il tuo
come beta e includi le informazioni nel tuo README.
E l'applicazione delle patch alle scimmie?
Scopri di più su monkeypatching.
L'app scimmia non è sicura perché le patch potrebbero smettere di funzionare senza preavviso a causa di all'utilizzo di parti non pubbliche dell'API Blockly. L'applicazione di patch in un plug-in è particolarmente pericoloso, perché il codice potrebbe interagire male con altri che usa il plug-in monkeypatches per lo stesso codice. Per questo motivo, abbiamo decisamente consigliano di non utilizzare il monkeypatching in applicazioni e plug-in di terze parti. non lo accetterà nei plug-in proprietari.
Posso eseguire l'override delle funzioni pubbliche?
Durante la creazione di sottoclassi: sì. Altrimenti: no, si tratta di monkeypatching.
Posso eseguire l'override delle funzioni protette?
Durante la creazione di sottoclassi: sì. Altrimenti: no, si tratta di monkeypatching.
Posso eseguire l'override delle funzioni interne o private?
No, va bene così.
Quando posso accedere direttamente alle proprietà? Quando dovrei usare un getter o un setter?
Se pubblichiamo un getter o un setter, usalo anziché direttamente che accedono alla proprietà. Se la proprietà non è pubblica, usa i getter. e setter.
Che cosa succede se una proprietà non ha un'annotazione?
Per impostazione predefinita è pubblico, ma inviaci una riga nel caso in cui volessimo inserire un getter/setter.
Cosa succede se una funzione è priva di annotazione?
Per impostazione predefinita è pubblico.
Cosa devo fare se non sono ancora sicuro?
Poni una domanda sul forum e ti ricontatteremo, generalmente entro un giorno lavorativo.