Questa pagina descrive le best practice per chiamare funzioni e accedere alle proprietà nel nucleo di Blockly. Questi principi si applicano alla creazione di plug-in per Blockly e all'integrazione di Blockly in un'applicazione autonoma.
Visibilità
Utilizziamo i modificatori di accesso TypeScript per contrassegnare la visibilità nella libreria di base come public, private o protected.
Alcune proprietà potrebbero essere annotate con @internal nei commenti del
TsDoc.
Tutte le proprietà public e protected sono documentate nella sezione Riferimenti del sito web di Blockly. Puoi anche controllare la visibilità leggendo il codice.
pubblica
Gli elementi contrassegnati da public fanno parte della nostra API pubblica. Qualsiasi proprietà in un modulo
che non ha un modificatore di visibilità è considerata pubblica.
Cerchiamo di non modificare la nostra API pubblica di frequente o senza un buon motivo e senza preavviso. L'eccezione: potremmo rendere pubblica una nuova API in una release e modificarla nella release successiva in risposta ai feedback iniziali. Dopodiché puoi considerare stabile una funzione o una proprietà pubblica.
Le funzioni pubbliche possono essere chiamate da qualsiasi posizione e sostituite nei sottoclassi, purché la firma non cambi.
protetto
Le funzioni e le proprietà protette possono essere accessibili solo dalla classe di definizione o da una sottoclasse.
Le sottoclassi possono sostituire funzioni e proprietà protette senza modificare le firme dei tipi.
Ad esempio, un visualizzatore personalizzato che estende la classe di visualizzatore di base può accedere alle sue proprietà protette.
In ogni caso, devi assicurarti di capire come la funzione o la proprietà viene utilizzata nel resto del codice.
privato
A questi valori è possibile accedere solo tramite codice nello stesso file della definizione. L'accesso diretto a queste proprietà potrebbe comportare un comportamento non definito.
Le sottoclassi non sono autorizzate a sostituire funzioni e 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 relativo modulo. Queste funzioni sono essenzialmente variabili locali e non possono essere utilizzate al di fuori del loro modulo di definizione. Dovrebbero essere considerate equivalenti alle proprietà private.
interno
Le funzioni e le proprietà interne sono destinate a essere utilizzate all'interno della biblioteca di base, ma non esternamente. Sono contrassegnati con l'annotazione @internal
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 del core e sostituirle nelle classi di base del core, a condizione che la firma non cambi. Non devono essere accessibili dall'esterno della libreria di base.
ritirato
Non utilizzare gli elementi contrassegnati da @deprecated. La maggior parte dei ritiri include indicazioni sul codice preferito, in un avviso della console o in TSDoc.
Ove possibile, le funzioni ritirate registreranno un avviso che include la data di eliminazione prevista e un consiglio per una funzione sostitutiva da chiamare.
Domande frequenti
Di seguito sono riportate alcune domande comuni che il team di Blockly ha riscontrato.
Che cosa succede se la funzione che voglio utilizzare non è pubblica?
Invia una richiesta di funzionalità su Blockly di base. Includi una descrizione del tuo caso d'uso e una dichiarazione su cosa vorresti che rendessimo pubblico.
Utilizzeremo la funzionalità per chiedere di discutere se renderla pubblica o se esistono altri modi per ottenere le stesse informazioni.
Se decidiamo di renderla pubblica, tu o il team di Blockly apporterete la modifica appropriata e la funzionalità verrà pubblicata nella prossima release di Blockly.
Se scegli di utilizzare un membro non pubblico in un plug-in, ti consigliamo di contrassegnare il plug-in come beta e di includere le informazioni nel tuo README.
Che ne dici del monkey patching?
Leggi informazioni sul monkey patching.
Il monkey patching non è sicuro, perché le patch potrebbero smettere di funzionare senza preavviso a causa dell'utilizzo di componenti non pubblici dell'API Blockly. La correzione di un plug-in è particolarmente pericolosa, perché il codice potrebbe interagire male con qualsiasi altro plug-in che esegue il monkey patching dello stesso codice. Per questo motivo, sconsigliamo vivamente di utilizzare il monkey patching nelle applicazioni e nei plug-in di terze parti e non lo accetteremo nei plug-in proprietari.
Posso eseguire l'override delle funzioni pubbliche?
Quando viene creata una sottoclasse: sì. In caso contrario: no, si tratta di monkey patching.
Posso eseguire l'override delle funzioni protette?
Quando viene creata una sottoclasse: sì. In caso contrario: no, si tratta di monkey patching.
Posso ignorare le funzioni interne o private?
No, è monkey patching.
Quando posso accedere direttamente alle proprietà? Quando devo utilizzare un getter o un setter?
Se pubblichiamo un getter o un setter, utilizzalo anziché accedere direttamente alla proprietà. Se la proprietà non è pubblica, utilizza sempre i getter e i setters.
Cosa succede se una proprietà non ha un'annotazione?
Per impostazione predefinita è pubblico, ma scrivici se vuoi che implementiamo una coppia di metodi getter/setter.
Cosa succede se una funzione non ha un'annotazione?
È pubblico per impostazione predefinita.
Cosa devo fare se non ho ancora le idee chiare?
Fai una domanda sul forum e ti risponderemo entro qualche giorno.