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, consulta Plug-in.
Per una breve introduzione alla creazione di un plug-in, consulta il nostro talk Come creare un plug-in (2021).
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 di Blockly e pubblicati nell'ambito@blockly su npm. Sono progettati per essere utilizzati in un'ampia gamma di applicazioni Blockly, 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ù complesse, più sperimentali o avere come target un ambito più ristretto di applicazioni Blockly. Un campo per la modifica di un oggetto specifico definito dallo schema del database è meglio come plug-in di terze parti.
Criteri proprietari
I plug-in proprietari devono soddisfare i seguenti requisiti:
- Funzionano su tutte le principali piattaforme, a meno che non venga concessa un'esenzione dal team di Blockly.
- Chrome, Firefox, Safari, Edge
- Avere un autore che sia disposto a gestire i bug per il primo anno.
- Non eseguire il monkey patching di Blockly.
- Avere un'API ben definita e documentata.
- Non chiamare funzioni private o del pacchetto dal nucleo di Blockly, a meno che non ti venga concessa un'esenzione dal team di Blockly.
- È consentita l'override delle funzioni del pacchetto in una sottoclasse definita.
- Se vuoi un'esenzione, chiedila aprendo un problema su blockly-samples.
- Sono disponibili 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 funzionalità.
Scopri come scrivere una richiesta di funzionalità
Oltre alle informazioni di base sulla richiesta di funzionalità, un suggerimento per i plug-in deve includere:
- L'API che il plug-in espone.
- API che devono essere aggiunte o modificate nel nucleo di Blockly per supportare il plug-in.
- Screenshot, GIF o mockup se il plug-in include funzionalità dell'interfaccia utente.
- Una spiegazione del motivo per cui deve essere un plug-in proprietario anziché di terne parti.
Il team di Blockly esamina i suggerimenti man mano che vengono inviati e chiude il problema o concorda sul fatto che si tratti di un buon plug-in proprietario.
Discussione
Successivamente, un plug-in passa alla fase di discussione. Questa fase include:
- Chiarimento della funzionalità desiderata.
- Chiarimenti sull'API del plug-in.
- Pianificazione dell'implementazione.
- Pianificazione dei test.
- Discussione sulle modifiche all'API nel nucleo di Blockly.
- Suddividi 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.
In genere, questa discussione avviene nel problema di GitHub. Più piccolo è l'ambito del plug-in, più rapida può essere la fase di discussione. I plug-in più grandi potrebbero attirare l'attenzione della community e opinioni forti sulla soluzione giusta. Se accade nel tuo caso, congratulazioni. Hai trovato qualcosa che interessa alle persone.
L'obiettivo è che alla fine della fase di discussione siano state prese tutte le decisioni di progettazione principali e 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 deve 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 indica che l'API è pronta per essere implementata.
Implementazione
I passaggi di implementazione includono:
- Esegui
npx @blockly/create-packageper configurare il plug-in e la relativa directory da un modello. Scopri di più. - Implementazione della logica di base per il plug-in.
- Implementazione di un'interfaccia utente, se necessario.
- Test del plug-in utilizzando Mocha.
- Documentazione del 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 per i contributi.
L'implementazione può essere eseguita da più collaboratori in parallelo. Puoi implementare un plug-in in collaborazione sul tuo fork o tramite richieste di pull contro questo repository. Se vuoi collaborare a un plug-in in questo repository, chiedi al team di Blockly di creare un branch di funzionalità per te.
I plug-in devono essere aggiunti al
gh-pages/index.md
file nel ramo master di blockly-samples. In questo modo, verranno visualizzati sul nostro sito dei plug-in. I plug-in di proprietà devono fare riferimento alla loro pagina di test. Anche i plug-in di terze parti possono essere aggiunti
a questa pagina e possono puntare a un link scelto dal proprietario, ad esempio una
demo ospitata o la pagina npm.
Pubblicazione
Infine, 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 i plug-in che sono stati 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. Questo può accadere se un plug-in si basa su una modifica non ancora pubblicata
in Blockly. Core Blockly viene pubblicato
nella settimana finale di ogni trimestre (una volta ogni tre mesi).