Introduzione
Questa pagina descrive le best practice per chiamare le funzioni e accedere alle proprietà nel blocco principale. Questi principi si applicano alla creazione di plug-in per Blockly o all'integrazione di Blockly in un'applicazione autonoma.
Sottoclasse ed estensione
Blockly ha diversi paradigmi per l'aggiunta di funzionalità, tra cui:
- Sottoclassi (ad es. creazione di un nuovo renderer)
- Mixins (ad es. aggiunta di un'estensione di blocco o di un mutatore)
- Definizioni di blocchi (ad es. definizioni di blocchi di procedure)
Ai fini del presente documento, tutti e tre i casi equivalgono alla sottoclassificazione.
Inserimento di sottoclassi
Supportiamo la sostituzione di determinati corsi con il metodo Blockly.inject. Queste sottoclassi devono estendere la classe base o implementare l'interfaccia corrispondente.
Puoi passare la sottoclasse al metodo inject.
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
In alternativa, puoi registrare la classe utilizzando Blockly.registry e usare il nome del registro per inserirla. È utile se memorizzi le opzioni di
iniezione come JSON puro.
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
Le seguenti classi possono essere sostituite:
| Nome registrazione | Interfaccia/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 |
Per ulteriori informazioni sull'utilizzo delle interfacce, consulta la sezione relativa alle interfacce della documentazione.
Visibilità
Utilizziamo i modificatori di accesso di TypeScript
per contrassegnare la visibilità nella libreria di base come public, private o protected.
Per alcune proprietà potrebbe essere possibile aggiungere @internal nei commenti TsDoc.
Tutte le proprietà public e protected sono documentate nella sezione
Riferimenti del sito web di Blockly. Puoi anche verificare
la visibilità leggendo il codice.
pubblica
Tutti gli elementi contrassegnati come public fanno 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 di frequente o senza validi motivi e avvisi. Eccezione: potremmo rendere pubblica una nuova API in una release e modificarla nella prossima release in risposta ai primi feedback. In seguito, puoi considerare una funzione pubblica o una proprietà stabile.
Le funzioni pubbliche possono essere chiamate da qualsiasi luogo e sostituite nelle sottoclassi purché la firma non cambi.
protetto
Solo la classe che lo definisce o una sottoclasse può accedere alle funzioni e alle proprietà protette.
Le sottoclassi possono eseguire l'override delle funzioni e delle proprietà protette, senza modificare le firme dei tipi.
Ad esempio, un renderer personalizzato che estende la classe del renderer di base potrebbe accedere alle sue proprietà protette.
In ogni caso, devi assicurarti di capire come viene utilizzata la funzione o la proprietà nel resto del codice.
private
È possibile accedervi solo tramite il codice nello stesso file della definizione. L'accesso diretto a queste proprietà potrebbe comportare un comportamento indefinito.
Le sottoclassi non possono eseguire l'override delle funzioni e delle proprietà private.
Le proprietà private sono soggette a modifiche senza preavviso, in quanto non sono considerate parte dell'API pubblica di Blockly.
Alcune funzioni in Blockly non hanno annotazioni di visibilità perché non vengono esportate dal loro modulo. Queste funzioni sono essenzialmente variabili locali e non possono essere utilizzate al di fuori del modulo che lo definisce. Dovrebbero essere considerati equivalenti alle proprietà private.
interno
Le funzioni e le proprietà interne sono destinate a essere utilizzate all'interno della libreria di base, ma non esternamente. Sono designati con l'annotazione @internal
nel TsDoc.
Le proprietà interne sono soggette a modifiche senza preavviso, in quanto non sono considerate parte dell'API pubblica di Blockly.
È possibile accedere alle proprietà interne da qualsiasi punto all'interno del core, ed eseguirne l'override nelle sottoclassi del core finché la firma non cambia. Non deve essere accessibile dall'esterno della libreria di base.
ritirato
Gli elementi contrassegnati con @deprecated non devono essere utilizzati. La maggior parte dei ritiri include indicazioni
sul codice preferito, in un avviso della console o in un documento TSDoc.
Se possibile, le funzioni deprecate registrano un avviso che include la data di eliminazione prevista e un suggerimento per una funzione sostitutiva da chiamare.
Domande frequenti
Che cosa succede se la funzione che voglio utilizzare non è pubblica?
Invia una richiesta di funzionalità sul canale Blockly principale. Includi una descrizione del tuo caso d'uso e una dichiarazione di ciò che vuoi rendere pubblico.
Useremo la funzionalità per chiedere se renderla pubblica o se esistono altri modi per ottenere le stesse informazioni.
Se decidiamo di renderlo pubblico, tu o il team di Blockly apporterete la modifica appropriata, che verrà pubblicata nella prossima release di Blockly.
Se scegli di utilizzare un membro non pubblico in un plug-in, valuta la possibilità di contrassegnarlo come beta e includere le informazioni in README.
Cosa succede alle monkeypatching?
Leggi informazioni su monkeypatching.
Monkeypatching non è sicuro perché le patch potrebbero smettere di funzionare senza preavviso a causa dell'utilizzo di parti non pubbliche dell'API Blockly. L'applicazione di patch in un plug-in è particolarmente pericolosa, perché il codice potrebbe interagire male con qualsiasi altro plug-in che applica lo stesso codice. Per questo motivo, sconsigliamo vivamente il monkeypatching in applicazioni e plug-in di terze parti e non lo accetteremo nei plug-in proprietari.
Posso ignorare le funzioni pubbliche?
Per la sottoclasse: sì. Altrimenti: no, si tratta di monkeypatching.
Posso eseguire l'override delle funzioni protette?
Per la sottoclasse: sì. Altrimenti: no, si tratta di monkeypatching.
Posso eseguire l'override delle funzioni interne o private?
No, è scimmietta.
Quando posso accedere direttamente alle proprietà? Quando dovrei usare un getter o un setter?
Se pubblichiamo un getter o un setter, utilizzalo anziché accedere direttamente alla proprietà. Se la proprietà non è pubblica, utilizza getter e setter.
Che cosa succede se una proprietà non ha un'annotazione?
Per impostazione predefinita è pubblico, ma scrivici nel caso in cui vogliamo creare una coppia getter/setter.
Che cosa succede se una funzione non ha un'annotazione?
È pubblico per impostazione predefinita.
Che cosa posso fare se ho ancora dubbi?
Poni una domanda sul forum e ti ricontatteremo, in genere entro un giorno lavorativo.