Memublikasikan Block Library

Plugin yang menyediakan library definisi blok adalah cara yang bagus untuk membagikan blok yang dapat digunakan kembali kepada komunitas Blockly. Untuk menjadikan library block Anda serbaguna dan berguna, kami telah mengembangkan panduan ini.

Panduan

• Buatlah mudah bagi pengguna untuk menginstal semua blok Anda, dan buat memungkinkan bagi pengguna untuk hanya menginstal blok atau bagian dari blok tertentu yang mereka pilih.
  • Permudah penginstalan semuanya: Anda dapat melakukannya dengan menyediakan fungsi yang menginstal setiap bagian yang diperlukan oleh definisi blok tunggal (seperti mutator, ekstensi, mixin, kolom, dll.). Anda juga dapat menyediakan fungsi yang akan menginstal semua blok yang ditawarkan oleh plugin sekaligus.
  • Mungkinkan untuk memilih bagian tertentu: Anda harus mengekspor semua bagian definisi blok secara terpisah, sehingga pengguna dapat mengimpor hanya bagian yang mereka butuhkan untuk membuat blok kustom serupa sendiri.
• Hindari penggunaan efek samping dalam plugin Anda.
  • Blok, kolom, ekstensi, dan bagian lainnya tidak boleh diinstal sebagai efek samping saat memuat plugin Anda. Pengguna harus mempertahankan kontrol atas aplikasi mana yang diinstal dan kapan. Hal ini memungkinkan pengguna untuk mengimpor bagian yang mereka butuhkan tanpa khawatir bagian yang tidak mereka perlukan akan terinstal.

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

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

• Jangan membuat asumsi tentang apa yang telah diinstal pengguna.

  • Jika plugin Anda memerlukan kolom kustom atau plugin lain, daftarkan kolom tersebut sendiri dalam fungsi install yang Anda sediakan.
  • Dalam waktu dekat, Blockly akan menyediakan alat yang memungkinkan Anda mendaftarkan item yang sudah terdaftar tanpa error. Sebelum itu, Anda mungkin perlu memeriksa apa saja yang sudah didaftarkan sebelum mendaftarkan ekstensi, mutator, mixin, atau kolom sendiri.
  • Jelaskan prasyarat atau dependensi yang diperlukan oleh plugin atau definisi blok Anda.

• Pertimbangkan untuk menyediakan fungsi generator untuk setiap blok yang Anda berikan.

  • Menyediakan fungsi generator yang dapat langsung digunakan akan memudahkan pengguna untuk menggunakan blok Anda tanpa harus memahami struktur dan desainnya. Jika mereka harus menulis fungsi generatornya sendiri, hal ini dapat menyebabkan pekerjaan yang berlebihan yang 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 menerapkan library Python.
  • Sebaiknya posting masalah 'bantuan yang diinginkan' untuk bahasa yang fungsi generatornya tidak dapat Anda terapkan, dan terima permintaan pull untuk hal ini jika pengguna berkontribusi.

  • Jika menyediakan fungsi penginstalan untuk blok, 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 dicadangkan:

      // 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 ada pertanyaan tentang cara terbaik untuk mengikuti panduan ini di plugin Anda, beri tahu kami di forum. Kami ingin melihat library blok Anda dan memberikan masukan tentang library tersebut.

Perlu diperhatikan bahwa tidak semua plugin pihak pertama yang menyediakan definisi blok saat ini mengikuti panduan ini, tetapi plugin baru akan dan kami berencana untuk memigrasikan plugin yang sudah ada.