Questo documento spiega come creare un nuovo plug-in. Sebbene la procedura descritta sia per la creazione di plug-in proprietari, puoi utilizzarla come linea guida per la creazione di plug-in di terze parti.
Per una panoramica dei plug-in, vedi Plug-in.
Per una rapida introduzione alla creazione di un plug-in, guarda il nostro How to Build a Plugin talk (2021).
Dati proprietari e di terze parti
L'utente target di un plug-in è uno sviluppatore che lo trova e lo utilizza tramite npm.
I plug-in proprietari sono supportati dal team Blockly e pubblicati nell'ambito
@blockly su npm. Sono progettati per essere utilizzabili in un'ampia gamma di applicazioni Blockly e sono stabili e facili da usare. Sono archiviati in
blockly-samples. Un campo per
impostare la velocità del motore potrebbe essere utilizzato in molti progetti di robotica ed è un buon
candidato per un plug-in proprietario.
I plug-in di terze parti vengono gestiti e pubblicati in modo indipendente. Potrebbero essere più complessi, più sperimentali o indirizzati a una gamma più ristretta di applicazioni Blockly. Un campo per la modifica di un oggetto specifico definito dallo schema del database è più adatto come plug-in di terze parti.
Criteri proprietari
I plug-in proprietari devono soddisfare i seguenti requisiti:
- Funzionare su tutte le principali piattaforme, a meno che non venga concessa un'esenzione dal team di Blockly.
- Chrome, Firefox, Safari, Edge
- Avere un autore disposto a gestire i bug per il primo anno.
- Non eseguire il monkeypatching di Blockly.
- Avere un'API chiaramente definita e documentata.
- Non chiamare funzioni private o di pacchetto dal core di Blockly, a meno che non sia stata concessa
un'esenzione dal team di Blockly.
- È consentito eseguire l'override delle funzioni del pacchetto in una sottoclasse definita.
- Se vuoi un'esenzione, chiedicelo in un problema su blockly-samples.
- Si possono inserire test.
Il processo
I plug-in passano attraverso quattro fasi: suggerimento, discussione, implementazione e pubblicazione.
Suggerimento
Un plug-in inizia come suggerimento. Puoi suggerire un plug-in creando un nuovo problema con il modello Richiesta di funzionalità. Per maggiori informazioni, scopri come scrivere una richiesta di funzionalità.
Oltre alle informazioni di base sulla richiesta di funzionalità, un suggerimento per un plug-in deve includere:
- L'API che il plug-in esporrebbe.
- API che devono essere aggiunte o modificate in Blockly di base per supportare il plug-in.
- Screenshot, GIF o mock-up se il plug-in include funzionalità dell'interfaccia utente.
- Una spiegazione del motivo per cui dovrebbe essere un plug-in proprietario anziché un plug-in di terze parti.
Il team di Blockly esamina i suggerimenti man mano che arrivano e chiude il problema o concorda che si tratterebbe di un buon plug-in proprietario.
Discussione
Poi, un plug-in entra nella fase di discussione. Questa fase include:
- Chiarimento della funzionalità desiderata.
- Chiarimento dell'API del plug-in.
- Pianificazione dell'implementazione.
- Pianificazione dei test.
- Discussione delle modifiche all'API in Blockly di base.
- Suddividere i plug-in di grandi dimensioni in passaggi di implementazione.
- Denominazione dei plug-in, in base alle nostre convenzioni di denominazione.
- Conferma che tutti i criteri proprietari verranno soddisfatti.
Questa discussione si svolge in genere sul problema di GitHub. Più è piccolo l'ambito del plug-in, più velocemente può avvenire la fase di discussione. I plugin più grandi potrebbero attirare l'attenzione della community e opinioni forti sulla soluzione giusta. Se questo accade con il tuo problema, congratulazioni. Hai trovato qualcosa che interessa alle persone.
L'obiettivo è che al termine della fase di discussione siano state prese tutte le decisioni di progettazione principali e che sia disponibile un elenco chiaro dei passaggi di implementazione. Entrambi devono essere documentati nei commenti relativi al problema.
Durante la discussione potremmo decidere che un plug-in debba essere di terze parti
e non essere pubblicato nell'ambito di @blockly. In questo caso, ti spiegheremo
il motivo e chiuderemo il problema.
Al termine della discussione, un membro del team di Blockly annota che è pronta per essere implementata.
Implementazione
I passaggi per l'implementazione includono:
- Esegui
npx @blockly/create-packageper configurare il plug-in e la relativa directory da un modello. Scopri di più… - Implementazione della logica principale del plug-in.
- Implementazione di una UI, se necessario.
- Test del plug-in, utilizzando Mocha.
- Documentare il plug-in, incluso
README.
Se un plug-in suggerito è stato approvato per l'implementazione e vuoi lavorarci, commenta il problema e chiedi se è ancora aperto ai contributi.
L'implementazione può essere eseguita in parallelo da più collaboratori. Puoi implementare un plug-in in modo collaborativo nel tuo fork o tramite richieste di pull in questo repository. Se vuoi collaborare a un plug-in in questo repository, chiedi al team di Blockly di creare un ramo di funzionalità per te.
I plug-in devono essere aggiunti al file
gh-pages/index.md
nel ramo master di blockly-samples. In questo modo, verranno visualizzati
sul nostro sito dei plug-in. I plug-in
proprietari devono rimandare alla pagina di test. A questa pagina possono essere aggiunti anche plug-in di terze parti, che possono rimandare a un link a scelta del proprietario, ad esempio una demo ospitata o la pagina npm.
Pubblicazione
Infine, la pubblicazione. Il team di Blockly utilizza Lerna per gestire il controllo delle versioni e la pubblicazione di tutti i plug-in.
Ogni giovedì vengono pubblicati tutti i plug-in modificati dall'ultima release. Se hai bisogno che una modifica venga pubblicata prima, indicalo nella pull request.
Il sito dei plug-in viene aggiornato anche ogni volta che vengono pubblicati plug-in.
I plug-in non pronti per la pubblicazione devono essere contrassegnati con private nel
package.json. Ciò può accadere se un plug-in si basa su una modifica non ancora pubblicata
nel core di Blockly. Core Blockly viene pubblicato
nell'ultima settimana di ogni trimestre (una volta ogni tre mesi).