Memublikasikan Block Library

Plugin yang menyediakan library definisi blok adalah cara yang tepat untuk membagikan blok yang dapat digunakan kembali dengan komunitas Blockly. Untuk membuat library blok Anda sesederhana dan seefektif mungkin, kami telah mengembangkan panduan ini.

Panduan

Buat pengguna mudah menginstal semua blok Anda, dan buat pengguna dapat menginstal hanya blok atau bagian blok tertentu yang mereka pilih.
- Memudahkan penginstalan semuanya: Anda dapat melakukannya dengan menyediakan fungsi yang menginstal setiap bagian yang diperlukan oleh satu definisi blok (seperti pengubah, ekstensi, mixin, kolom, dll.). Anda juga dapat menyediakan fungsi yang akan menginstal semua blok yang ditawarkan oleh plugin Anda sekaligus.
- Memungkinkan Anda memilih bagian tertentu: Anda harus mengekspor semua bagian definisi blok secara terpisah, sehingga pengguna dapat mengimpor bagian yang dibutuhkan untuk membuat blok kustomnya sendiri yang serupa.
Hindari penggunaan efek samping di plugin Anda.
- Blok, kolom, ekstensi, dan bagian lainnya tidak boleh diinstal sebagai efek samping dari pemuatan plugin Anda. Pengguna harus mempertahankan kontrol atas hal-hal yang diinstal dan kapan. Hal ini memungkinkan pengguna mengimpor bagian yang mereka butuhkan tanpa khawatir bagian yang tidak mereka inginkan akan diinstal.

Gunakan registry kolom JSON, bukan membuat instance kolom baru secara langsung.

Tidak Direkomendasikan - Membuat instance kolom baru secara langsung:

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

Direkomendasikan - Registry kolom JSON:

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

Penggunaan registry kolom memudahkan pengguna untuk mengganti implementasi kolom yang digunakan di blok Anda tanpa harus mengubah definisi blok.

Jangan membuat asumsi tentang aplikasi yang telah diinstal pengguna.
- Jika plugin Anda memerlukan kolom kustom atau plugin lain, daftarkan kolom tersebut sendiri dalam fungsi install yang Anda berikan.
- Dalam waktu dekat, Blockly akan menyediakan alat yang memungkinkan Anda mendaftarkan item yang sudah terdaftar tanpa error. Sebelum itu, sebaiknya Anda memeriksa apa yang telah terdaftar sebelum mendaftarkan ekstensi, pengubah, mixin, atau kolom sendiri.
- Jelaskan tentang prasyarat atau dependensi yang diperlukan oleh definisi plugin atau blok Anda.
Pertimbangkan untuk menyediakan fungsi generator untuk setiap blok yang Anda berikan.
- Menyediakan fungsi generator yang siap pakai akan memudahkan pengguna menggunakan blok Anda tanpa harus memahami struktur dan desainnya. Jika mereka harus menulis fungsi generator mereka sendiri, hal ini dapat menyebabkan pekerjaan yang berlebihan dilakukan oleh setiap pengguna.
- JavaScript adalah bahasa yang paling umum digunakan di Blockly. Jadi, jika Anda hanya memilih satu bahasa untuk disediakan, sebaiknya gunakan JavaScript, kecuali jika blok Anda dibuat untuk bahasa tertentu seperti penerapan library Python.
- Pertimbangkan untuk memposting masalah 'bantuan ingin' untuk bahasa yang tidak dapat Anda implementasikan fungsi generatornya, dan terima permintaan pull untuk bahasa tersebut jika pengguna berkontribusi padanya.
- Jika Anda menyediakan fungsi instal untuk blok Anda, Anda dapat menerima parameter generators opsional. Jika pengguna meneruskan instance generator yang Anda dukung, Anda dapat otomatis menginstal fungsi generator kode blok dan melakukan pekerjaan terkait seperti menambahkan kata yang direservasi:
```
  // 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});
```

Masukan

Jika Anda memiliki pertanyaan tentang cara terbaik untuk mengikuti panduan ini di plugin, beri tahu kami di forum. Kami ingin melihat library blok Anda dan memberikan masukan tentang library tersebut.

Perhatikan bahwa tidak semua plugin pihak pertama yang memberikan definisi blok saat ini mengikuti panduan ini, tetapi plugin baru akan melakukannya dan kami berencana untuk memigrasikan plugin yang ada.