Pubblicare librerie di blocchi

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

Linee guida

• Rendi facile per gli utenti installare tutti i tuoi blocchi e possibile per loro installare solo determinati blocchi o parti di blocchi.
  • Semplifica l'installazione di tutto: puoi farlo fornendo un funzione che installa ogni elemento richiesto da una singola definizione di blocco (come mutatori, estensioni, mix, campi e così via). Puoi anche forniscono una funzione che installerà tutti i blocchi offerti dal contemporaneamente.
  • Consentite di scegliere parti specifiche: dovete esportare tutti i la definizione di un blocco separatamente, in modo che sia possibile di importare solo i pezzi di cui ha bisogno per creare il proprio un blocco personalizzato simile.
• Evita di utilizzare effetti collaterali nel plug-in.
  • Blocchi, campi, estensioni e altri componenti non devono essere installati come effetto collaterale del caricamento del plug-in. Gli utenti devono mantenere il controllo quali elementi sono installati e quando. Ciò consente agli utenti di importare pezzi di cui hanno bisogno senza preoccuparsi di altri pezzi installato.

• Utilizza il registry dei campi JSON anziché creare direttamente nuovi campi.

  • Opzione non consigliata. Creare direttamente un'istanza per un nuovo campo:

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

  • Consigliato: registry dei campi JSON:

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

  • L'utilizzo del registry dei campi consente a un utente di sostituire più facilmente l'implementazione del campo utilizzato nel blocco senza dover modificare la definizione del blocco.

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

  • Se il tuo plug-in richiede un campo personalizzato o un altro plug-in, registra autonomamente questi campi nella funzione install fornita.
  • A breve, Blockly fornirà strumenti che ti consentono di registrarti articoli già registrati senza errori. Fino ad allora, potresti voler controlla cosa è già stato registrato prima di registrare un'estensione, un mutatore, un mix o una possibilità.
  • Descrivi chiaramente tutti i prerequisiti o le dipendenze richiesti le definizioni dei plug-in o dei blocchi.

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

  • Fornire funzioni di generatore che funzionano immediatamente semplifica per gli utenti l'utilizzo dei blocchi senza dover comprendere la loro struttura e il loro design. Se devono scrivere il proprio generatore funzioni, questo può portare a un lavoro ridondante da parte di ciascun utente.
  • JavaScript è il linguaggio più usato in Blockly, quindi se solo scegliere una lingua da fornire, consigliamo JavaScript, a meno che i blocchi sono create per un linguaggio specifico, come l'implementazione di una libreria Python.
  • Valuta la possibilità di pubblicare problemi "help wanted" per le lingue per le quali non riesci a implementare le funzioni di generatore e accetta le richieste pull per queste lingue se un utente le fornisce.

  • Se fornisci una funzione di installazione per il blocco, puoi accettare un parametro generators facoltativo. Se un utente passa a un'istanza del generatore supportati, puoi installare automaticamente il generatore di codici a blocchi e svolgere le attività correlate, come l'aggiunta di parole riservate:

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.common.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, non esitare a contattarci nel forum. Ci piacerebbe vedere le tue raccolte di blocchi e fornirti un feedback.

Tieni presente che, al momento, non tutti i plug-in proprietari che forniscono definizioni di blocchi seguire queste linee guida, ma i nuovi plug-in seguiranno e prevediamo di migrare quelli esistenti o plug-in.