Menambahkan kolom plugin ke Block Factory

Alat Developer Blockly memungkinkan Anda membuat blok kustom menggunakan blok. Selain kolom yang disertakan dengan Blockly inti, kolom ini juga memiliki dukungan untuk kolom yang dipublikasikan sebagai plugin. Jika Anda telah membuat kolom kustom, Anda dapat menambahkan dukungan untuk kolom tersebut ke Block Factory dengan mengikuti panduan ini. Kolom kustom harus dipublikasikan di npm sebelum Anda dapat menambahkan dukungan untuknya. Anda juga harus berkomitmen untuk memperbarui kolom agar tetap mengikuti perubahan di Blockly. Jika tidak, kami mungkin perlu menghapusnya dari Block Factory pada masa mendatang.

Pengembangan di Block Factory

Kode sumber Block Factory terletak di repositori blockly-samples di direktori examples/developer-tools.

Untuk mengirimkan perubahan pada Alat Developer di blockly-samples, Anda harus mengikuti langkah-langkah umum untuk mengembangkan di blockly-samples. Namun, tidak seperti saat bekerja dengan plugin, Anda harus menjalankan npm install dari direktori examples/developer-tools secara langsung, bukan di tingkat root blockly-samples.

Menginstal plugin

Agar Pabrik Blok menampilkan kolom kustom Anda di pratinjau, kolom kustom tersebut harus diinstal. Tambahkan kolom Anda sebagai dependensi npm developer-tools. Kemudian, daftarkan atau lakukan pekerjaan penyiapan lain yang diperlukan di developer-tools/src/blocks/index.ts.

Membuat blok untuk kolom

Karena Block Factory menggunakan blok untuk membuat blok kustom, Anda memerlukan blok yang merepresentasikan kolom kustom Anda.

Buat definisi blok

Anda perlu mendesain blok untuk kolom; jika ingin mendapatkan meta, Anda bahkan dapat mendesainnya menggunakan Block Factory. Blok harus memungkinkan pengguna mengonfigurasi penyiapan yang diperlukan oleh kolom Anda, seperti nilai default dan nama. Tambahkan definisi blok ini ke developer-tools/src/blocks/fields.ts, lalu impor di developer-tools/src/blocks/index.ts.

Menambahkan blok ke toolbox

Selanjutnya, Anda perlu menambahkan blok ini ke definisi toolbox agar dapat diakses oleh pengguna. Definisi toolbox terletak di developer-tools/src/toolbox.ts. Blok Anda harus ditambahkan ke kategori "Kolom".

Pembuat Kode

Block Factory berfungsi dengan menggunakan sistem Pembuat Kode yang sudah Anda kenal dari Blockly. Setiap blok memiliki generator kode blok untuk setiap jenis output yang dihasilkan oleh Block Factory, dan blok induk merakit kode untuk blok turunan ke dalam output yang benar. Untuk menambahkan dukungan untuk kolom kustom, Anda harus menambahkan fungsi generator kode blok untuk setiap class Code Generator.

Buat file untuk blok kolom Anda di direktori output-generators/fields. Anda akan menambahkan generator kode blok untuk setiap Generator berikut ke file ini. Impor file ini di file blocks/index.ts agar fungsi pembuat kode blok dimuat ke dalam aplikasi.

Definisi JavaScript

javascriptDefinitionGenerator membuat kode yang akan disertakan dalam definisi JavaScript untuk blok yang menyertakan kolom kustom Anda. Biasanya, ini berarti generator kode blok harus menampilkan baris kode yang terlihat seperti .appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName'). Perhatikan bahwa baris kode ini tidak menyertakan titik koma, karena input yang berisi beberapa kolom akan memiliki beberapa panggilan ke appendField yang dirangkai bersama. Argumen dalam konstruktor diambil dari nilai yang ditetapkan pengguna di blok kolom. Berikut adalah contoh pembuat kode blok ini untuk 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})`;
};

Blok sudut yang ditarik pengguna dari kategori "Kolom" pada kotak alat Block Factory memiliki dua kolom:

• FIELDNAME: pengguna dapat menetapkan nama kolom di blok kustom mereka
• ANGLE: pengguna dapat menyetel nilai sudut default

Dalam generator kode blok ini, kita mendapatkan nilai sudut default dan meneruskannya sebagai satu-satunya argumen ke konstruktor FieldAngle. Nama kolom selalu diteruskan sebagai argumen kedua ke appendField.

Catatan: Untuk setiap tempat yang memerlukan tanda kutip di sekitar nilai kolom, seperti saat meneruskan nama kolom ke appendField, Anda harus menggunakan generator.quote_, bukan membungkusnya secara manual dengan tanda kutip.

Definisi JSON

jsonDefinitionGenerator serupa, tetapi ini menampilkan bagian dari definisi blok JSON yang sesuai dengan kolom Anda. Biasanya, kode ini adalah objek JSON yang mencakup:

• type: sesuai dengan nama kolom Anda di pendaftaran kolom Blockly
• name: pengguna dapat menetapkan nama kolom di blok kustom mereka
• properti kustom lain yang diperlukan oleh metode inisialisasi json kolom Anda.

Berikut contoh dari FieldAngle lagi:

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);
};

Catatan: Generator kode blok selalu menampilkan string, jadi ubah objek menjadi string sebelum menampilkannya.

Header kode

Code Header Generator membuat output Header Kode yang ditampilkan di Block Factory. Output ini dapat dialihkan antara impor esmodule dan tag skrip, bergantung pada cara pengguna ingin memuat kode, sehingga sebenarnya ada dua instance generator yang berbeda: satu untuk setiap kasus. Anda perlu menambahkan generator kode blok untuk masing-masingnya. Berikut contoh untuk 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 '';
};

Generator ini memiliki metode yang disebut addHeaderLine yang memungkinkan Anda menentukan baris kode yang harus dipanggil sebelum kolom Anda digunakan dalam kode. Biasanya, hal ini mencakup pekerjaan seperti mengimpor kolom atau memuatnya melalui tag skrip, dan mungkin memanggil fungsi yang akan mendaftarkan kolom dengan pendaftaran kolom Blockly.

Tips: Jika paket Anda dipublikasikan di npm, paket tersebut akan otomatis tersedia di unpkg, yang merupakan tempat yang nyaman untuk memuat tag skrip.

Untuk dua generator kode blok ini, semua kode harus ditambahkan melalui panggilan ke addHeaderLine. Fungsi ini akan memastikan setiap baris header hanya ditampilkan sekali, meskipun blok kolom kustom Anda digunakan beberapa kali dalam satu blok kustom. Generator kode blok harus menampilkan string kosong.

Stub generator

Terakhir, kita memiliki generator yang membuat stub generator untuk kolom. Di generator kode blok ini, Anda akan menulis kode yang menghasilkan kode yang membantu pengguna menulis kode yang menghasilkan kode. Masih bingung? Caranya lebih mudah dari yang Anda kira.

Stub generator untuk blok kustom mencakup variabel siap pakai yang merepresentasikan setiap kolom di blok. Kemudian, ada TODO yang harus diselesaikan pengguna untuk mengumpulkan semua variabel ini ke dalam string kode akhir yang akan ditampilkan oleh blok kustom mereka. Artinya, biasanya semua generator kode blok Anda hanya perlu menampilkan baris yang membuat variabel kustom ini. Katakan bahwa pengguna sedang membuat blok kustom yang akan menambahkan sinar matahari ke kanvasnya. Mereka menambahkan kolom sudut ke blok dan menamainya "SUN_DIRECTION". Stub generator untuk blok ini akan menyertakan baris const angle_sun_direction = block.getFieldValue("SUN_DIRECTION");. Itulah baris kode yang perlu ditampilkan oleh generator kode blok untuk kolom sudut:

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`;
};

Untuk mendapatkan nama standar untuk variabel, Anda dapat memanggil generator.createVariableName dan meneruskan jenis kolom (seperti angle, number, dll.) beserta nama kolom yang diberikan pengguna.

Melakukan pengujian

Setelah menulis semua bagian ini, Anda akan dapat memulai Block Factory dengan menjalankan npm start di direktori blockly-samples/examples/developer-tools. Anda dapat menarik blok dari kategori kolom, menambahkannya ke input pada blok, dan melihat perubahan output. Periksa apakah pratinjau blok terlihat benar, dan apakah kode untuk setiap bagian output sudah benar.