Pubblica librerie a blocchi

I plug-in che forniscono librerie di definizioni di blocchi sono un ottimo modo per condividere i tuoi blocchi riutilizzabili con la community di Blockly. Per rendere la tua libreria a blocchi il più versatile e utile possibile, abbiamo sviluppato queste linee guida.

Linee guida

• Rendi semplice l'installazione di tutti i tuoi blocchi e rendi possibile per gli utenti installare solo determinati blocchi o blocchi di loro scelta.
  • Semplifica l'installazione di tutto: puoi farlo fornendo una funzione che installa ogni parte richiesta da una singola definizione di blocco (come mutatori, estensioni, mixin, campi e così via). Puoi anche fornire una funzione che installerà contemporaneamente tutti i blocchi offerti dal tuo plug-in.
  • Possibilità di scegliere parti specifiche: devi esportare separatamente tutti i pezzi di una definizione di blocco, in modo che l'utente possa importare solo i pezzi di cui ha bisogno per creare un proprio blocco personalizzato simile.
• Evita di utilizzare effetti collaterali nel plug-in.
  • Blocchi, campi, estensioni e altri elementi non devono essere installati come effetto collaterale del caricamento del plug-in. Gli utenti devono mantenere il controllo su quali elementi vengono installati e quando. Ciò consente agli utenti di importare i pezzi di cui hanno bisogno senza preoccuparsi che non vengano installati.

• Utilizza il registro di campi JSON invece di creare direttamente un'istanza di nuovi campi.

  • Non consigliato: crea direttamente l'istanza di un nuovo campo:

      const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(new Blockly.FieldNumber(123), 'NAME');
        }
      }
    

  • Opzione consigliata - Registro di campi JSON:

      export const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(Blockly.fieldRegistry.fromJson({
                  name: 'field_number',
                  value: 123,
                }), 'NAME');
        }
      }
    

  • L'utilizzo del registro di campo semplifica la sostituzione dell'implementazione del campo utilizzato nel blocco per un utente senza dover modificare la definizione del blocco.

• Non dare ipotesi su ciò che l'utente ha già installato.

  • Se il plug-in richiede un campo personalizzato o un altro plug-in, registra questi campi nella funzione install fornita.
  • A breve, Blockly fornirà strumenti che ti consentiranno di registrare articoli già registrati senza errori. Fino ad allora, ti consigliamo di controllare cosa è già stato registrato prima di registrare autonomamente un'estensione, un mutatore, un mixin o un campo.
  • Descrivi chiaramente tutti i prerequisiti o le dipendenze richiesti dal plug-in o dalle definizioni dei blocchi.

• Valuta la possibilità di fornire funzioni generatore per ciascuno dei blocchi che fornisci.

  • Fornire funzioni del generatore che funzionino immediatamente, consente agli utenti di utilizzare più facilmente i tuoi blocchi senza doverne comprendere la struttura e il design. Se gli utenti devono scrivere le proprie funzioni di generatore, questo può portare a un lavoro ridondante da parte di ogni utente.
  • JavaScript è il linguaggio più usato in Blockly, quindi se scegli un solo linguaggio da fornire, ti consigliamo JavaScript, a meno che i tuoi blocchi non siano creati per un linguaggio specifico, come l'implementazione di una libreria Python.
  • Potresti pubblicare problemi specifici per le lingue per cui non sei in grado di implementare funzioni del generatore e accettare richieste di pull a questo riguardo se un utente le fornisce.

  • Se fornisci una funzione di installazione per il blocco, puoi accettare un parametro generators facoltativo. Se un utente passa un'istanza del generatore supportata da te, puoi installare automaticamente la funzione generatore di blocchi di codice ed eseguire le operazioni correlate, ad esempio l'aggiunta di parole riservate:

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.defineBlocks({my_custom_block: myCustomBlock});
        if (generators.javascript) {
          generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
          generators.javascript.addReservedWords('specialReservedWord');
        }
      }
    
      // How a user may install your block
      import {javascriptGenerator} from 'blockly/javascript';
      import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
      // installs the block definition and the javascript block-code generator
      installMyCustomBlock({javascript: javascriptGenerator});
    

Feedback

Se hai domande su come seguire al meglio queste linee guida nel tuo plug-in, faccelo sapere nel forum. Ci piacerebbe vedere le tue librerie a blocchi e ricevere feedback in merito.

Tieni presente che al momento non tutti i plug-in proprietari che forniscono definizioni di blocco seguono queste linee guida, ma per i nuovi plug-in verrà eseguita la migrazione dei plug-in esistenti.