หน้านี้อธิบายแนวทางปฏิบัติแนะนำสำหรับการเรียกใช้ฟังก์ชันและการเข้าถึงพร็อพเพอร์ตี้ใน Blockly หลัก หลักการเหล่านี้มีผลบังคับใช้กับการสร้างปลั๊กอินสําหรับ Blockly และการผสานรวม Blockly เข้ากับแอปพลิเคชันแบบสแตนด์อโลน
ระดับการแชร์
เราใช้ตัวแก้ไขการเข้าถึง TypeScript เพื่อทําเครื่องหมายระดับการเข้าถึงในไลบรารีหลักเป็น public, private หรือ protected
พร็อพเพอร์ตี้บางรายการอาจมีคำอธิบายประกอบด้วย @internal ในความคิดเห็น TsDoc
พร็อพเพอร์ตี้ public และ protected ทั้งหมดมีเอกสารประกอบอยู่ในส่วนข้อมูลอ้างอิงของเว็บไซต์ Blockly นอกจากนี้ คุณยังตรวจสอบระดับการแชร์ได้โดยอ่านโค้ด
สาธารณะ
ทุกอย่างที่มีเครื่องหมาย public เป็นส่วนหนึ่งของ API สาธารณะ ระบบจะถือว่าพร็อพเพอร์ตี้ในโมดูลที่ไม่มีตัวแก้ไขระดับการเข้าถึงเป็นแบบสาธารณะ
เราพยายามไม่เปลี่ยนแปลง API สาธารณะบ่อยครั้งหรือเปลี่ยนแปลงโดยไม่มีเหตุผลอันควรและคำเตือน ข้อยกเว้น: เราอาจทำให้ API ใหม่เป็นแบบสาธารณะในรุ่นหนึ่งและแก้ไขในรุ่นถัดไปตามความคิดเห็นที่ได้รับในช่วงแรก หลังจากนั้น คุณอาจพิจารณาว่าฟังก์ชันหรือพร็อพเพอร์ตี้สาธารณะมีเสถียรแล้ว
เรียกฟังก์ชันสาธารณะได้จากทุกที่ และสามารถลบล้างในคลาสย่อยได้ตราบใดที่ลายเซ็นไม่เปลี่ยนแปลง
มีการป้องกัน
ฟังก์ชันและพร็อพเพอร์ตี้ที่ได้รับการปกป้องจะเข้าถึงได้เฉพาะคลาสที่กําหนดหรือคลาสย่อยเท่านั้น
คลาสย่อยได้รับอนุญาตให้ลบล้างฟังก์ชันและพร็อพเพอร์ตี้ที่ได้รับการป้องกันได้โดยไม่ต้องเปลี่ยนลายเซ็นประเภท
เช่น โปรแกรมแสดงผลที่กําหนดเองซึ่งขยายคลาสโปรแกรมแสดงผลพื้นฐานอาจเข้าถึงพร็อพเพอร์ตี้ที่ได้รับการป้องกันของคลาสนั้นได้
ในแต่ละกรณี คุณควรตรวจสอบว่าเข้าใจวิธีใช้ฟังก์ชันหรือพร็อพเพอร์ตี้ในโค้ดที่เหลือ
ส่วนตัว
โค้ดในไฟล์เดียวกับคําจํากัดความเท่านั้นที่จะเข้าถึงได้ การเข้าถึงพร็อพเพอร์ตี้เหล่านี้โดยตรงอาจทําให้ลักษณะการทํางานไม่ชัดเจน
คลาสย่อยไม่ได้รับอนุญาตให้ลบล้างฟังก์ชันและพร็อพเพอร์ตี้ส่วนตัว
พร็อพเพอร์ตี้ส่วนตัวอาจมีการเปลี่ยนแปลงโดยไม่ได้รับคำเตือน เนื่องจากไม่ถือว่าเป็นส่วนหนึ่งของ API สาธารณะของ Blockly
ฟังก์ชันบางอย่างใน Blockly ไม่มีคำอธิบายประกอบระดับการเข้าถึงเนื่องจากไม่ได้ส่งออกจากโมดูล ฟังก์ชันเหล่านี้เป็นตัวแปรภายในโดยพื้นฐาน และจะใช้นอกโมดูลที่กําหนดไม่ได้ ที่พักเหล่านี้ควรถือว่าเทียบเท่ากับที่พักส่วนบุคคล
ภายใน
ฟังก์ชันและพร็อพเพอร์ตี้ภายในมีไว้เพื่อใช้ในไลบรารีหลักเท่านั้น ไม่ใช่ภายนอก โดยมีการระบุด้วย@internal
คำอธิบายประกอบ TsDoc
พร็อพเพอร์ตี้ภายในอาจมีการเปลี่ยนแปลงได้โดยไม่ต้องแจ้งเตือน เนื่องจากไม่ถือว่าเป็นส่วนหนึ่งของ API สาธารณะของ Blockly
พร็อพเพอร์ตี้ภายในเข้าถึงได้จากทุกที่ภายในโค้ดหลัก และสามารถลบล้างได้ในคลาสย่อยในโค้ดหลัก ตราบใดที่ลายเซ็นไม่เปลี่ยนแปลง โดยต้องไม่เข้าถึงจากภายนอกคลังหลัก
เลิกใช้งานแล้ว
คุณไม่ควรใช้รายการที่มีเครื่องหมาย @deprecated การเลิกใช้งานส่วนใหญ่จะมีวิธีการเกี่ยวกับโค้ดที่แนะนำ ไม่ว่าจะอยู่ในคำเตือนคอนโซลหรือ TSDoc
ฟังก์ชันที่เลิกใช้งานจะบันทึกคำเตือนที่มีวันที่ที่ตั้งใจจะลบและคำแนะนำสำหรับฟังก์ชันที่จะเรียกแทน หากเป็นไปได้
คำถามที่พบบ่อย
ต่อไปนี้คือคำถามที่พบบ่อยซึ่งทีม Blockly พบ
จะเกิดอะไรขึ้นหากฟังก์ชันที่ฉันต้องการใช้ไม่ใช่แบบสาธารณะ
ส่งคำขอฟีเจอร์ใน Blockly หลัก ระบุคำอธิบายกรณีการใช้งานและข้อความที่คุณต้องการให้เราเผยแพร่ต่อสาธารณะ
เราจะใช้ฟีเจอร์นี้เพื่อขอพูดคุยว่าจะเผยแพร่ข้อมูลดังกล่าวต่อสาธารณะหรือไม่ หรือมีวิธีอื่นให้คุณได้รับข้อมูลเดียวกันหรือไม่
หากเราตัดสินใจที่จะเผยแพร่ฟีเจอร์นี้ต่อสาธารณะ คุณหรือทีม Blockly จะต้องทําการเปลี่ยนแปลงที่เหมาะสม และฟีเจอร์ดังกล่าวจะเผยแพร่ในรุ่นถัดไปของ Blockly
หากเลือกใช้สมาชิกที่ไม่ใช่แบบสาธารณะในปลั๊กอิน ให้พิจารณาทำเครื่องหมายปลั๊กอินเป็นรุ่นเบต้าและระบุข้อมูลใน README
แล้วการแฮ็กโค้ดล่ะ
อ่านข้อมูลเกี่ยวกับการแก้ไขโค้ดขณะรันไทม์
การแก้ไขโค้ดแบบ Monkeypatching ไม่ปลอดภัยเนื่องจากแพตช์อาจหยุดทํางานโดยไม่แจ้งให้ทราบเนื่องจากมีการใช้ชิ้นส่วนของ Blockly API ที่ไม่เปิดเผยต่อสาธารณะ การแพตช์ในปลั๊กอินเป็นการกระทำที่อันตรายอย่างยิ่ง เนื่องจากโค้ดของคุณอาจทำงานร่วมกับปลั๊กอินอื่นๆ ที่ทำการแพตช์โค้ดเดียวกันได้ไม่ดี ด้วยเหตุนี้ เราจึงขอแนะนำอย่างยิ่งไม่ให้ใช้การแก้ไขโค้ดแบบ Monkey ในแอปพลิเคชันและปลั๊กอินของบุคคลที่สาม และจะไม่ยอมรับการแก้ไขโค้ดแบบ Monkey ในปลั๊กอินของบุคคลที่หนึ่ง
ฉันจะลบล้างฟังก์ชันสาธารณะได้ไหม
เมื่อเป็นคลาสย่อย: ใช่ ไม่ นั่นคือการแก้ไขโค้ด
ฉันลบล้างฟังก์ชันที่ได้รับการปกป้องได้ไหม
เมื่อเป็นคลาสย่อย: ใช่ ไม่ นั่นคือการแก้ไขโค้ด
ฉันจะลบล้างฟังก์ชันภายในหรือส่วนตัวได้ไหม
ไม่ นั่นคือการแก้ไขโค้ด
ฉันจะเข้าถึงพร็อพเพอร์ตี้ได้โดยตรงเมื่อใด ฉันควรใช้ getter หรือ setter เมื่อใด
หากเราเผยแพร่ getter หรือ setter โปรดใช้ฟังก์ชันดังกล่าวแทนการเข้าถึงพร็อพเพอร์ตี้โดยตรง หากพร็อพเพอร์ตี้ไม่ใช่แบบสาธารณะ ให้ใช้ getter และ setter
จะเกิดอะไรขึ้นหากพร็อพเพอร์ตี้ไม่มีคำอธิบายประกอบ
โดยค่าเริ่มต้น ตัวแปรจะเป็นแบบสาธารณะ แต่โปรดติดต่อเราในกรณีที่เราต้องการใช้คู่เมธอด getter/setter ให้คุณ
จะเกิดอะไรขึ้นหากฟังก์ชันไม่มีคําอธิบายประกอบ
โดยจะเป็นแบบสาธารณะโดยค่าเริ่มต้น
ฉันควรทำอย่างไรหากยังไม่แน่ใจ
ถามคำถามในฟอรัม แล้วเราจะติดต่อกลับหาคุณภายใน 2-3 วัน