Pubblica librerie a 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 una funzione che installi ogni elemento richiesto da una singola definizione di blocco (ad esempio mutatori, estensioni, mixin, campi e così via). Puoi anche fornire una funzione che installi contemporaneamente tutti i blocchi offerti dal tuo plug-in.
- Consenti la scelta di parti specifiche: devi esportare separatamente tutti i pezzi di una definizione di blocco, in modo che un utente possa importare solo quelli necessari per creare il proprio 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 su quali elementi installare e quando. In questo modo, gli utenti possono importare i componenti di cui hanno bisogno senza preoccuparsi che vengano installati componenti non necessari.

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

Non consigliato: creazione diretta 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 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 consentiranno di registrare gli elementi già registrati senza errori. Fino ad allora, ti consigliamo di controllare ciò che è già stato registrato prima di registrare personalmente un'estensione, un mutatore, un mixin o un campo.
- Indica chiaramente eventuali prerequisiti o dipendenze richiesti dalle definizioni del plug-in o del blocco.
Valuta la possibilità di fornire funzioni generatore per ciascuno dei blocchi che fornisci.
- Fornire funzioni di generazione pronte all'uso semplifica l'utilizzo dei blocchi senza doverne comprenderne la struttura e il design. Se devono scrivere le proprie funzioni di generatore, questo potrebbe comportare un lavoro ridondante da parte di ogni utente.
- JavaScript è il linguaggio più usato in Blockly, quindi se ne scegli uno solo, ti consigliamo JavaScript, a meno che i blocchi non siano creati per un linguaggio specifico, come l'implementazione di una libreria Python.
- Potresti pubblicare problemi di richiesta di aiuto per le lingue per le quali non riesci a implementare le funzioni del generatore e accettare le richieste di pull 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 di generatore supportata, puoi installare automaticamente la funzione di generatore di codice blocco ed eseguire attività 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, comunicacelo 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 dei blocchiseguono queste linee guida, ma i nuovi plug-in lo faranno e prevediamo di eseguire la migrazione di quelliesistenti.