Halaman ini menjelaskan praktik terbaik untuk memanggil fungsi dan mengakses properti di Blockly inti. Prinsip-prinsip ini berlaku untuk membuat plugin untuk Blockly dan untuk mengintegrasikan Blockly ke dalam aplikasi mandiri.
Visibilitas
Kita 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 di bagian Referensi di situs Blockly. Anda
juga dapat memeriksa visibilitas dengan membaca kode.
publik
Semua yang ditandai public adalah bagian dari API publik kami. Setiap properti dalam modul
yang tidak memiliki pengubah visibilitas dianggap publik.
Kami mencoba untuk tidak sering mengubah API publik atau tanpa alasan dan peringatan yang baik. Pengecualian: kami dapat membuat API baru bersifat publik dalam satu rilis dan mengubahnya dalam rilis berikutnya sebagai respons terhadap masukan awal. Setelah itu, Anda dapat menganggap fungsi atau properti publik stabil.
Fungsi publik dapat dipanggil dari mana saja, dan diganti di subclass selama tanda tangan tidak berubah.
dilindungi
Fungsi dan properti yang dilindungi hanya dapat diakses oleh class penentu atau subclass.
Subclass diizinkan untuk mengganti fungsi dan properti yang dilindungi, tanpa mengubah tanda tangan jenis.
Misalnya, perender kustom yang memperluas class perender dasar dapat mengakses propertinya yang dilindungi.
Dalam setiap kasus, Anda harus memastikan bahwa Anda memahami cara fungsi atau properti digunakan di kode lainnya.
pribadi
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 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.
internal
Fungsi dan properti internal dimaksudkan untuk digunakan dalam library
inti, tetapi tidak secara eksternal. Class ini 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 dalam core selama tanda tangan tidak berubah. Library ini tidak boleh diakses dari luar library inti.
tidak digunakan lagi
Apa pun yang ditandai @deprecated tidak boleh digunakan. Sebagian besar penghentian penggunaan menyertakan
petunjuk tentang kode yang lebih disukai, baik dalam peringatan konsol maupun TSDoc.
Jika memungkinkan, fungsi yang tidak digunakan lagi akan mencatat peringatan yang menyertakan tanggal penghapusan yang diinginkan dan rekomendasi untuk fungsi pengganti yang akan dipanggil.
FAQ
Berikut adalah beberapa pertanyaan umum yang dihadapi tim Blockly.
Bagaimana jika fungsi yang ingin saya gunakan tidak bersifat publik?
Ajukan permintaan fitur di Blockly inti. Sertakan deskripsi kasus penggunaan Anda dan pernyataan tentang hal yang ingin Anda publikasikan.
Kami akan menggunakan fitur ini untuk meminta untuk membahas apakah akan menjadikannya publik, atau apakah ada cara lain bagi Anda untuk mendapatkan informasi yang sama.
Jika kami memutuskan untuk memublikasikannya, Anda atau tim Blockly akan membuat perubahan yang sesuai, dan perubahan tersebut akan ditayangkan dalam rilis Blockly berikutnya.
Jika Anda memilih untuk menggunakan anggota non-publik dalam plugin, pertimbangkan untuk menandai plugin sebagai beta dan sertakan informasinya dalam README.
Bagaimana dengan monkeypatching?
Baca tentang monkeypatching.
Monkeypatching tidak aman, karena patch dapat berhenti berfungsi tanpa pemberitahuan karena menggunakan bagian Blockly API yang tidak bersifat publik. Patching dalam plugin sangat berbahaya, karena kode Anda mungkin berinteraksi dengan buruk dengan plugin lain yang melakukan monkeypatch pada kode yang sama. Oleh karena itu, kami sangat menyarankan agar tidak melakukan monkeypatching di aplikasi dan plugin pihak ketiga, dan tidak akan menerimanya di plugin pihak pertama.
Dapatkah saya mengganti fungsi publik?
Saat membuat subclass: ya. Jika tidak: tidak, itu adalah monkeypatching.
Dapatkah saya mengganti fungsi yang dilindungi?
Saat membuat subclass: ya. Jika tidak: tidak, itu adalah monkeypatching.
Dapatkah saya mengganti fungsi internal atau pribadi?
Tidak, itu adalah monkeypatching.
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 langsung mengakses properti. Jika properti tidak bersifat publik, pastikan untuk menggunakan pengambil dan penyetel.
Bagaimana jika properti tidak memiliki anotasi?
Secara default, ini bersifat publik, tetapi harap beri tahu kami jika kami ingin memasang pasangan pengambil/penyemat untuk Anda.
Bagaimana jika fungsi tidak memiliki anotasi?
Secara default, setelan ini bersifat publik.
Bagaimana jika saya masih tidak yakin?
Ajukan pertanyaan di forum dan kami akan menghubungi Anda dalam beberapa hari.