Menggunakan Blockly API

Pengantar

Halaman ini menjelaskan praktik terbaik untuk memanggil fungsi dan mengakses properti di Blockly inti. Prinsip-prinsip ini berlaku untuk pembuatan plugin untuk Blockly atau untuk mengintegrasikan Blockly ke dalam aplikasi mandiri.

Subclassing dan perluasan

Blockly memiliki beberapa paradigma untuk menambahkan fungsi, termasuk:

• Subclass (misalnya, membuat perender baru)
• Mixin (misalnya, menambahkan ekstensi blok atau mutator)
• Definisi blok (misalnya, 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. Subclass ini harus memperluas class dasar, atau mengimplementasikan antarmuka yang sesuai.

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 memasukkan class tersebut. Hal ini berguna jika Anda menyimpan opsi 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 penggunaan antarmuka, baca bagian antarmuka dalam dokumentasi.

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 dapat dianotasi dengan @internal di komentar TsDoc.

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

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

publik

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

Kami mencoba untuk tidak sering mengubah API publik kami atau tanpa alasan dan peringatan yang baik. Pengecualian: kami dapat membuat API baru menjadi publik dalam satu rilis dan memodifikasinya dalam rilis berikutnya sebagai respons terhadap masukan awal. Setelah itu, Anda dapat menganggap fungsi publik atau properti sebagai stabil.

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

dilindungi

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

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

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

Dalam setiap kasus, pastikan Anda memahami cara fungsi atau properti digunakan dalam kode lainnya.

private

Ini hanya dapat diakses oleh kode dalam file yang sama dengan definisi. Mengakses properti ini secara langsung dapat menyebabkan perilaku yang tidak ditentukan.

Subclass tidak diizinkan untuk mengganti fungsi dan properti pribadi.

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

Beberapa fungsi di Blockly tidak memiliki anotasi visibilitas karena tidak diekspor dari modulnya. Fungsi ini pada dasarnya adalah variabel lokal dan tidak dapat digunakan di luar modul penentunya. Properti tersebut harus dianggap 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 metode tersebut muncul di dokumentasi referensi atau tidak ditandai sebagai pribadi dalam kode. 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 dalam library inti, tetapi tidak untuk eksternal. Class tersebut ditetapkan dengan anotasi @internal TsDoc.

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

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

tidak digunakan lagi

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

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

FAQ

Bagaimana jika fungsi yang ingin saya gunakan tidak bersifat publik?

Ajukan permintaan fitur pada inti Blockly. Sertakan deskripsi kasus penggunaan dan pernyataan tentang apa yang Anda ingin kami sampaikan kepada publik.

Kami akan menggunakan fitur ini untuk mengajukan permintaan terkait apakah perlu menyetelnya ke publik, atau apakah ada cara lain bagi Anda untuk mendapatkan informasi yang sama.

Jika kami memutuskan untuk menjadikannya publik, Anda atau tim Blockly akan membuat perubahan yang sesuai, dan akan ditayangkan di rilis Blockly berikutnya.

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

Bagaimana dengan penambalan monyet?

Baca tentang Monkeypatching.

Monkeypatching tidak aman karena patch dapat berhenti berfungsi tanpa pemberitahuan akibat penggunaan bagian non-publik dari Blockly API. Patch di plugin sangat berbahaya karena kode Anda dapat berinteraksi secara buruk dengan plugin lain yang melakukan Monkeypatch pada kode yang sama. Karena alasan ini, kami sangat menyarankan agar Monkeypatching dalam aplikasi dan plugin pihak ketiga, serta tidak akan menerimanya dalam plugin pihak pertama.

Dapatkah saya mengganti fungsi publik?

Saat membuat subclass: ya. Jika tidak, itu adalah Monkeypatching.

Dapatkah saya mengganti fungsi yang dilindungi?

Saat membuat subclass: ya. Jika tidak, itu adalah Monkeypatching.

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 kami memublikasikan pengambil atau penyetel, gunakan pengambil atau penyetel tersebut, bukan mengakses properti secara langsung. Jika properti tidak bersifat publik, gunakan pengambil dan penyetel.

Catatan: Penggunaan pengambil dan penyetel yang konsisten dalam plugin memberi kami fleksibilitas untuk membuat perubahan pada Blockly inti tanpa merusak kode yang dipublikasikan.

Bagaimana jika properti tidak memiliki anotasi?

Secara default, setelan ini bersifat publik, tetapi hubungi kami jika kami ingin menerapkan pasangan pengambil/penyetel untuk Anda.

Bagaimana jika suatu fungsi tidak memiliki anotasi?

Bersifat publik secara default.

Bagaimana jika saya masih tidak yakin?

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