Aggiungi un campo plug-in a Block Factory

Gli strumenti per sviluppatori di Blockly ti consentono di creare blocchi personalizzati usando i blocchi. Supporta i campi pubblicati come plug-in oltre a quelli forniti con lo strumento principale Blockly. Se hai creato un campo personalizzato, puoi aggiungerne il supporto alla fabbrica di blocchi seguendo questa guida. Il campo personalizzato deve essere pubblicato su npm prima di poterne aggiungere il supporto. Devi anche impegnarti ad aggiornare il campo per stare al passo con le modifiche in Blockly, altrimenti in futuro potremmo doverlo rimuovere da Blockly.

Sviluppo della fabbrica di blocchi

Il codice sorgente per la fabbrica di blocchi si trova nel repository degli esempi a blocchi nella directory examples/developer-tools.

Per inviare una modifica agli Strumenti per sviluppatori in esempi a blocchi, devi seguire la procedura tipica per lo sviluppo in esempi a blocchi. Tuttavia, a differenza dell'utilizzo dei plug-in, dovrai eseguire npm install direttamente dalla directory examples/developer-tools, anziché al livello principale di blockly-samples.

Installa il plug-in

Per poter mostrare il tuo campo personalizzato nell'anteprima, Block fabbrica deve installare il campo personalizzato. Aggiungi il tuo campo come dipendenza npm degli strumenti per sviluppatori. Quindi, registralo o esegui qualsiasi altra operazione di configurazione necessaria in developer-tools/src/blocks/index.ts.

Crea un blocco per il campo

Poiché la fabbrica di blocchi utilizza i blocchi per creare blocchi personalizzati, è necessario un blocco che rappresenti il campo personalizzato.

Creare la definizione del blocco

Devi progettare il blocco per il campo; se vuoi ottenere un meta, puoi anche progettarlo utilizzando Block Factory. Il blocco deve consentire all'utente di configurare l'impostazione richiesta dal campo, ad esempio i valori predefiniti e un nome. Aggiungi questa definizione del blocco a developer-tools/src/blocks/fields.ts e importala in developer-tools/src/blocks/index.ts.

Aggiungi blocco agli strumenti

Successivamente, devi aggiungere questo blocco alla definizione di toolbox per renderlo accessibile agli utenti. La definizione di toolbox si trova in developer-tools/src/toolbox.ts. Il blocco dovrebbe essere aggiunto alla categoria "Campi".

Generatori di codice

La fabbrica di blocchi utilizza il sistema di generazione di codice che conosci già da Blockly. Ogni blocco ha un generatore di codici a blocchi per ogni tipo di output generato dalla fabbrica di blocchi e i blocchi principali assemblano il codice per i blocchi figlio nell'output corretto. Per aggiungere il supporto di un campo personalizzato, devi aggiungere funzioni di generazione di codice a blocchi per ciascuna delle classi del generatore di codice.

Crea un file per il blocco di campo nella directory output-generators/fields. Aggiungerai a questo file i generatori di codici a blocchi per ciascuno dei seguenti generatori. Importa questo file nel file blocks/index.ts in modo che le funzioni del generatore di codici a blocchi vengano caricate nell'applicazione.

Definizione di JavaScript

L'elemento javascriptDefinitionGenerator crea il codice che sarà incluso nella definizione JavaScript per un blocco che include il campo personalizzato. Di solito, questo significa che il generatore di codici a blocchi deve restituire una riga di codice simile a .appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName'). Tieni presente che questa riga di codice non include un punto e virgola, perché un input che contiene più campi avrà diverse chiamate a appendField concatenate. Gli argomenti nel costruttore vengono estratti dai valori impostati dall'utente nel blocco di campo. Ecco un esempio di questo generatore di codici a blocchi per FieldAngle:

javascriptDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JavascriptDefinitionGenerator,
): string {
  const name = generator.quote_(block.getFieldValue('FIELDNAME'));
  const angle = block.getFieldValue('ANGLE');
  return `.appendField(new FieldAngle(${angle}), ${name})`;
};

Il blocco angolare che l'utente ha trascinato dalla categoria "Campi" della casella degli strumenti Fabbrica di blocchi ha due campi:

• FIELDNAME: l'utente può impostare il nome del campo nel proprio blocco personalizzato
• ANGLE: l'utente può impostare il valore predefinito dell'angolo

In questo generatore di codici a blocchi, otteniamo il valore di angolo predefinito e lo passiamo come unico argomento al costruttore FieldAngle. Il nome del campo viene sempre passato come secondo argomento a appendField.

Nota: per qualsiasi posizione tu debba racchiudere il valore di un campo tra virgolette, ad esempio quando passi il nome del campo a appendField, devi utilizzare generator.quote_ anziché aggregare manualmente il valore.

Definizione JSON

jsonDefinitionGenerator è simile, ma restituisce la parte della definizione del blocco JSON che corrisponde al tuo campo. In genere, questo codice è un oggetto JSON che include:

• type: corrisponde al nome del tuo campo nel registry dei campi Blockly
• name: l'utente può impostare il nome del campo nel proprio blocco personalizzato
• Qualsiasi altra proprietà personalizzata richiesta dal metodo di inizializzazione JSON del tuo campo.

Ecco di nuovo un esempio da FieldAngle:

jsonDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JsonDefinitionGenerator,
): string {
  const code = {
    type: 'field_angle',
    name: block.getFieldValue('FIELDNAME'),
    angle: block.getFieldValue('ANGLE'),
  };
  return JSON.stringify(code);
};

Nota: i generatori di codice a blocchi restituiscono sempre le stringhe, quindi devi stringere l'oggetto prima di restituirlo.

Intestazioni del codice

Il generatore di intestazioni di codice crea l'output delle intestazioni di codice mostrato in Block fabbrica. Questo output può essere alternato tra importazioni esmodule e tag di script, a seconda di come l'utente vuole caricare il codice, quindi in realtà sono presenti due diverse istanze del generatore: una per ogni caso. Devi aggiungere un generatore di codice a blocchi per ognuno di essi. Ecco un esempio per FieldAngle:

importHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `import {registerFieldAngle, FieldAngle} from '@blockly/field-angle';`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

scriptHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `<script src="https://unpkg.com/@blockly/field-angle"></script>`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

Questi generatori utilizzano un metodo chiamato addHeaderLine che consente di specificare una riga di codice da chiamare prima che il campo venga utilizzato nel codice. In genere, questo include operazioni come l'importazione del campo o il suo caricamento tramite un tag di script e forse la chiamata di una funzione che registrerà il campo nel registro dei campi di Blockly.

Suggerimento: se il pacchetto viene pubblicato su npm, dovrebbe essere automaticamente disponibile su unpkg, una posizione comoda da cui possono essere caricati i tag di script.

Per questi due generatori di codici a blocchi, l'intero codice deve essere aggiunto tramite chiamate a addHeaderLine. Questa funzione assicura che ogni riga di intestazione venga visualizzata una sola volta, anche se il blocco di campi personalizzati viene utilizzato più volte in un blocco personalizzato. Il generatore di codici a blocchi dovrebbe restituire la stringa vuota.

Stub del generatore

Infine, abbiamo il generatore che crea lo stub del generatore per il campo. In questo generatore di codice a blocchi, scriverai un codice che genera codice che aiuta l'utente a scrivere codice che genera codice. Sei ancora confuso? È più facile di quanto sembri.

Lo stub del generatore per un blocco personalizzato include una variabile predefinita che rappresenta ogni campo del blocco. Poi c'è un TODO che l'utente deve completare per assemblare tutte queste variabili nella stringa di codice finale che il blocco personalizzato restituirà. Ciò significa che in genere tutto il generatore di codice a blocchi deve restituire la riga che crea questa variabile personalizzata. Supponiamo che l'utente stia creando un blocco personalizzato che aggiungerà raggi di luce alla tela. Aggiungi un campo angolo al blocco e gli nomina "SUN_DIRECTION". Lostub del generatore per questo blocco includerà la riga const angle_sun_direction = block.getFieldValue("SUN_DIRECTION");. Questa è la riga di codice che il generatore di codice a blocchi deve restituire per il campo angolare:

generatorStubGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: GeneratorStubGenerator,
): string {
  const name = block.getFieldValue('FIELDNAME');
  const fieldVar = generator.createVariableName('angle', name);
  return `const ${fieldVar} = block.getFieldValue(${generator.quote_(
    name,
  )});\n`;
};

Per ottenere un nome standardizzato per la variabile, puoi chiamare generator.createVariableName e passare il tipo di campo (ad esempio angle, number e così via) insieme al nome del campo da parte dell'utente.

Testa

Dopo aver scritto tutti questi pezzi, dovresti essere in grado di avviare la fabbrica di blocchi eseguendo npm start nella directory blockly-samples/examples/developer-tools. Dovresti essere in grado di trascinare il blocco dalla categoria del campo, aggiungerlo a un input su un blocco e osservare la modifica dell'output. Verifica che l'anteprima del blocco sia corretta e che il codice per ogni sezione di output sia corretto.