Menggunakan Blockly API

Pengantar

Halaman ini menjelaskan praktik terbaik untuk memanggil fungsi dan mengakses dan properti di core Blockly. Prinsip ini berlaku untuk membuat plugin untuk Blockly atau untuk mengintegrasikan Blockly ke dalam aplikasi mandiri.

Membuat subclass dan memperluas

Blockly memiliki beberapa paradigma untuk menambahkan fungsi, termasuk:

• Subclass (misalnya, membuat perender baru)
• Mixin (misalnya, menambahkan ekstensi atau mutator blok)
• Definisi blok (mis. definisi blok prosedur)

Untuk tujuan dokumen ini, ketiga kasus tersebut setara dengan pembuatan subclass.

Memasukkan subclass

Kami mendukung penggantian class tertentu melalui metode Blockly.inject. Ini harus memperluas class dasar, atau menerapkan class yang dalam antarmuka berbasis web yang sederhana.

Anda dapat meneruskan subclass ke metode injeksi.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

Atau Anda dapat mendaftarkan class menggunakan Blockly.registry dan menggunakan nama registry untuk menginjeksikan class. Hal ini berguna jika Anda menyimpan injeksi sebagai JSON murni.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

Class berikut dapat diganti:

Nama Pendaftaran	Antarmuka/Class Dasar
blockDragger	Blockly.IBlockDragger
connectionChecker	Blockly.IConnectionChecker
connectionPreviewer	Blockly.IConnectionPreviewer
flyoutsVerticalToolbox	Blockly.IFlyout
flyoutsHorizontalToolbox	Blockly.IFlyout
metricsManager	Blockly.IMetricsManager
renderer	Blockly.blockRendering.Renderer
toolbox	Blockly.IToolbox

Untuk mengetahui informasi selengkapnya tentang cara menggunakan antarmuka, lihat bagian antarmuka dokumentasi tersebut.

Catatan: Semua metode yang dilindungi dan publik pada class terdaftar dapat diganti. Namun, metode yang dilindungi pada class yang tidak terdaftar tidak boleh diganti.

Visibilitas

Kami menggunakan pengubah akses TypeScript untuk menandai visibilitas di library inti sebagai public, private, atau protected. Beberapa properti mungkin dianotasi dengan @internal dalam Komentar TsDoc.

Semua properti public dan protected didokumentasikan dalam Bagian Referensi di situs Blockly. Anda juga dapat memeriksa visibilitas dengan membaca kodenya.

Perhatian: Meskipun JavaScript tidak menerapkan anotasi visibilitas ini, Anda harus menghindari akses apa pun yang bukan public. Tim Blockly tidak menjamin stabilitas properti dan fungsi non-publik di antara rilis.

publik

Apa pun yang ditandai sebagai public adalah bagian dari API publik kami. Semua properti dalam modul yang tidak memiliki pengubah visibilitas dianggap publik.

Kami mencoba untuk tidak sering mengubah API publik kami atau tanpa alasan yang tepat dan peringatan. Pengecualian: kami dapat membuat API baru menjadi publik dalam satu rilis dan mengubahnya di rilis berikutnya sebagai tanggapan atas masukan awal. Setelah itu Anda mungkin mempertimbangkan kestabilan fungsi atau properti publik.

Fungsi publik dapat dipanggil dari mana saja, dan diganti dalam subclass sesuai selama tanda tangan tidak berubah.

dilindungi

Fungsi dan properti yang dilindungi hanya dapat diakses oleh class penentuan atau subclass.

Subclass diizinkan untuk mengganti fungsi dan properti yang dilindungi, tanpa mengubah tanda tangan tipe perubahan.

Misalnya, perender kustom yang memperluas class perender dasar dapat mengakses properti yang dilindunginya.

Dalam setiap kasus, Anda harus memastikan bahwa Anda memahami bagaimana fungsi atau properti yang digunakan dalam kode lainnya.

pribadi

Ini hanya dapat diakses oleh kode dalam file yang sama dengan definisi. Secara langsung mengakses properti ini dapat menyebabkan perilaku yang tidak terdefinisi.

Subclass tidak diizinkan untuk mengganti fungsi dan properti pribadi.

Properti pribadi dapat berubah tanpa peringatan, karena tidak dianggap sebagai bagian dari API publik Blockly.

Beberapa fungsi di Blockly tidak memiliki anotasi visibilitas karena tidak diekspor dari modul mereka. Fungsi ini pada dasarnya adalah variabel lokal dan tidak dapat digunakan di luar modul definisinya. Mereka harus dipertimbangkan setara dengan properti pribadi.

Catatan: Sebelumnya, Blockly menggunakan garis bawah untuk menunjukkan properti pribadi: example_. Sesuai dengan panduan gaya Google saat ini, kami tidak lagi melakukannya dalam kode baru, dan dapat mengubah kode lama. Sebelum memanggil metode di Blockly, pastikan bahwa dokumen itu muncul dalam dokumentasi referensi atau tidak ditandai sebagai pribadi dalam pada kode sumber. Dalam kasus yang jarang terjadi, fungsi pribadi digunakan secara luas sehingga menjadi publik, sehingga Anda mungkin melihat fungsi publik yang diakhiri dengan garis bawah.

internal

Fungsi dan properti internal dimaksudkan untuk digunakan di dalam inti {i>library<i}, tetapi tidak secara eksternal. Tugas tersebut ditetapkan dengan TsDoc @internal anotasi.

Properti internal dapat berubah tanpa peringatan, karena tidak dianggap sebagai bagian dari API publik Blockly.

Properti internal dapat diakses dari mana saja di dalam inti, dan diganti dalam subclass di inti selama tanda tangan tidak berubah. Mereka tidak boleh berupa diakses dari luar library inti.

tidak digunakan lagi

Apa pun yang ditandai @deprecated tidak boleh digunakan. Sebagian besar penghentian penggunaan mencakup petunjuk pada kode yang diinginkan, baik dalam peringatan konsol atau TSDoc.

Jika memungkinkan, fungsi yang tidak digunakan lagi akan mencatat peringatan yang menyertakan tanggal penghapusan yang diinginkan dan rekomendasi fungsi pengganti yang akan dipanggil.

FAQ

Bagaimana jika fungsi yang ingin saya gunakan tidak publik?

Ajukan permintaan fitur pada inti Blockly. Sertakan deskripsi kasus penggunaan Anda dan pernyataan tentang apa Anda ingin kami memublikasikannya.

Kami akan menggunakan fitur ini untuk meminta diskusi apakah akan menjadikannya publik, atau apakah ada cara lain bagi Anda untuk mendapatkan informasi yang sama.

Jika kami memutuskan untuk membuatnya publik, Anda atau tim Blockly akan yang sesuai, dan akan dipublikasikan dalam rilis Blockly berikutnya.

Jika Anda memilih menggunakan anggota non-publik di plugin, pertimbangkan untuk menandai plugin sebagai beta dan menyertakan informasi dalam README Anda.

Bagaimana dengan patching monyet?

Baca tentang Monkeypatching.

Monkeypatching tidak aman, karena patch dapat berhenti berfungsi tanpa pemberitahuan karena hingga menggunakan potongan non-publik dari Blockly API. Patching dalam plugin sangat berbahaya, karena kode Anda mungkin berinteraksi secara buruk dengan plugin yang men-patch kode yang sama. Karena alasan ini, kami sangat merekomendasikan agar tidak melakukan Monkeypatching dalam aplikasi dan plugin pihak ketiga, serta tidak akan menerimanya di plugin pihak pertama.

Dapatkah saya mengganti fungsi publik?

Saat membuat subclass: ya. Jika tidak: tidak, itu adalah patching monyet.

Dapatkah saya mengganti fungsi yang dilindungi?

Saat membuat subclass: ya. Jika tidak: tidak, itu adalah patching monyet.

Dapatkah saya mengganti fungsi internal atau pribadi?

Tidak, itu tambal sulam.

Kapan saya dapat mengakses properti secara langsung? Kapan saya harus menggunakan pengambil atau penyetel?

Jika kita menerbitkan pengambil atau penyetel, gunakan itu alih-alih langsung yang mengakses properti. Jika properti tidak bersifat publik, sebaiknya gunakan pengambil dan penyetel.

Catatan: Dengan penggunaan pengambil dan penyetel yang konsisten di plugin, kami memiliki fleksibilitas untuk membuat perubahan di Blockly inti tanpa merusak kode yang dipublikasikan.

Bagaimana jika properti tidak memiliki anotasi?

Secara {i>default<i} ini publik, namun silakan hubungi kami jika kami ingin menempatkan pasangan pengambil/penyetel yang sesuai untuk Anda.

Bagaimana jika fungsi tidak memiliki anotasi?

Semuanya bersifat publik secara default.

Bagaimana jika saya masih tidak yakin?

Ajukan pertanyaan di forum dan kami akan menghubungi Anda, biasanya dalam satu hari kerja.