Memublikasikan library blok

Plugin yang menyediakan library definisi blok adalah cara yang bagus untuk membagikan blok yang dapat digunakan kembali kepada 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 mungkin menginstal hanya blok atau bagian blok tertentu yang mereka pilih.
  • Permudah penginstalan semuanya: Anda dapat melakukannya dengan menyediakan 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.
  • Memungkinkan pemilihan 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.
• 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 untuk mengimpor yang mereka butuhkan tanpa khawatir bahwa bagian yang tidak mereka butuhkan 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 bidang 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 bidang khusus atau plugin lainnya, daftarkan bidang tersebut kolom sendiri dalam fungsi install yang disediakan.
  • Dalam waktu dekat, Blockly akan menyediakan alat yang memungkinkan Anda mendaftar item yang sudah terdaftar tanpa kesalahan. Sebelum itu, sebaiknya Anda memeriksa apa yang telah terdaftar sebelum mendaftarkan ekstensi, pengubah, mixin, atau kolom sendiri.
  • Jelaskan tentang prasyarat atau dependensi apa pun yang diperlukan oleh definisi plugin atau blok Anda.

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

  • Menyediakan fungsi generator yang dapat langsung digunakan akan memudahkan bagi pengguna untuk menggunakan blok Anda tanpa harus memahami struktur dan desain. Jika mereka harus menulis generatornya sendiri fungsi ini, hal ini dapat menyebabkan pekerjaan redundan 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.
  • Pertimbangkan untuk memposting masalah 'bantuan diperlukan' untuk bahasa yang tidak dapat Anda terapkan fungsi generatornya, dan terima permintaan pull untuk bahasa tersebut jika pengguna memberikan kontribusi.

  • Jika Anda menyediakan fungsi instal untuk blok Anda, Anda dapat menerima parameter generators opsional. Jika pengguna meneruskan instance generator yang Anda dukung, Anda dapat secara otomatis menginstal generator {i>block-code<i} fungsi dan melakukan pekerjaan terkait seperti menambahkan kata yang dicadangkan:

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.common.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 mengikuti panduan ini di plugin Anda, beri tahu kami di forum! Kami ingin melihat blok library Anda dan menyediakan {i>feedback<i} kepada mereka.

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.