เกริ่นนำ
หน้านี้อธิบายแนวทางปฏิบัติแนะนำสำหรับการเรียกใช้ฟังก์ชันและการเข้าถึงพร็อพเพอร์ตี้ในบริการหลักของ Blockly หลักการเหล่านี้ใช้กับการสร้างปลั๊กอินสำหรับ Blockly หรือการผสานรวม Blockly ในแอปพลิเคชันแบบสแตนด์อโลน
คลาสย่อยและการขยาย
Blockly มีกระบวนทัศน์มากมายสำหรับการเพิ่มฟังก์ชันการทำงาน ดังนี้
- คลาสย่อย (เช่น การสร้างตัวแสดงผลใหม่)
- มิกซ์ (เช่น การเพิ่มส่วนขยายบล็อกหรือการเปลี่ยนรูปแบบ)
- คําจํากัดความของบล็อก (เช่น คําจํากัดความของบล็อกกระบวนการ)
สำหรับจุดประสงค์ของเอกสารนี้ ทั้ง 3 กรณีจะเทียบเท่ากับการจัดคลาสย่อย
กำลังแทรกคลาสย่อย
เรารองรับการแทนที่บางคลาสผ่านเมธอด Blockly.inject
คลาสย่อยเหล่านี้ต้องขยายคลาสฐานหรือนำอินเทอร์เฟซที่สอดคล้องกันไปใช้
คุณส่งคลาสย่อยไปยังเมธอดการแทรกได้
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
หรือคุณจะลงทะเบียนชั้นเรียนโดยใช้ Blockly.registry
แล้วใช้ชื่อรีจิสทรีเพื่อแทรกคลาสก็ได้ วิธีนี้มีประโยชน์หากคุณจัดเก็บตัวเลือกการแทรกเป็นไฟล์ JSON แท้
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
ชั้นเรียนต่อไปนี้สามารถแทนที่ได้
ชื่อการจดทะเบียน | คลาสอินเทอร์เฟซ/พื้นฐาน |
---|---|
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 |
ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้อินเทอร์เฟซได้ที่ส่วนอินเทอร์เฟซของเอกสาร
ทัศนวิสัย
เราใช้ตัวปรับแต่งการเข้าถึง TypeScript เพื่อทำเครื่องหมายการเปิดเผยในไลบรารีหลักเป็น public
, private
หรือ protected
พร็อพเพอร์ตี้บางรายการอาจใส่คำอธิบายประกอบด้วย @internal
ในความคิดเห็นในTsDocของพร็อพเพอร์ตี้นั้นๆ
พร็อพเพอร์ตี้ public
และ protected
ทั้งหมดจะบันทึกอยู่ในส่วนข้อมูลอ้างอิงของเว็บไซต์ Blockly หรือจะตรวจสอบการเปิดเผย
โดยการอ่านรหัสก็ได้
สาธารณะ
ทุกอย่างที่มีเครื่องหมาย public
เป็นส่วนหนึ่งของ API สาธารณะของเรา พร็อพเพอร์ตี้ในโมดูลที่ไม่มีตัวปรับแต่งการแสดงผลจะถือว่าเป็นแบบสาธารณะ
เราพยายามไม่เปลี่ยนแปลง API สาธารณะของเราบ่อยๆ หรือโดยไม่มีเหตุผลและคำเตือนที่ดี ข้อยกเว้นคือ เราอาจทำให้ API ใหม่เป็นแบบสาธารณะในรุ่นหนึ่งและแก้ไขในรุ่นถัดไปเพื่อเป็นการตอบสนองต่อความคิดเห็นก่อนหน้า หลังจากนั้นคุณอาจลองใช้ฟังก์ชันสาธารณะหรือพร็อพเพอร์ตี้ที่เสถียร
ระบบอาจเรียกใช้ฟังก์ชันสาธารณะจากที่ใดก็ได้และลบล้างในคลาสย่อย ตราบใดที่ลายเซ็นไม่มีการเปลี่ยนแปลง
ได้รับการคุ้มครอง
ฟังก์ชันและพร็อพเพอร์ตี้ที่มีการป้องกันสามารถเข้าถึงได้โดยคลาสที่กำหนดหรือคลาสย่อยเท่านั้น
คลาสย่อยได้รับอนุญาตให้ลบล้างฟังก์ชันและพร็อพเพอร์ตี้ที่ได้รับการปกป้อง โดยไม่ต้องเปลี่ยนแปลงลายเซ็นประเภท
เช่น ตัวแสดงผลที่กำหนดเองซึ่งขยายคลาสการแสดงผลฐานอาจเข้าถึงพร็อพเพอร์ตี้ที่มีการป้องกัน
ในแต่ละกรณี คุณควรทำความเข้าใจวิธีใช้ฟังก์ชันหรือพร็อพเพอร์ตี้ในโค้ดที่เหลือ
private
ซึ่งจะเข้าถึงได้โดยใช้โค้ดในไฟล์เดียวกับคําจํากัดความเท่านั้น การเข้าถึงพร็อพเพอร์ตี้เหล่านี้โดยตรงอาจทำให้เกิดลักษณะการทำงานที่ไม่ได้กำหนด
ไม่อนุญาตให้คลาสย่อยลบล้างฟังก์ชันและพร็อพเพอร์ตี้ส่วนตัว
พร็อพเพอร์ตี้ส่วนตัวอาจมีการเปลี่ยนแปลงโดยไม่มีการแจ้งเตือน เนื่องจากไม่ได้เป็นส่วนหนึ่งของ API สาธารณะของ Blockly
บางฟังก์ชันใน Blockly จะไม่มีคำอธิบายประกอบระดับการเข้าถึงเนื่องจากไม่ได้ส่งออกจากโมดูล โดยพื้นฐานแล้ว ฟังก์ชันเหล่านี้คือตัวแปรภายใน และไม่สามารถใช้ได้นอกโมดูลที่กำหนด ซึ่งควรถือว่าเทียบเท่ากับ ทรัพย์สินส่วนบุคคล
ภายใน
ฟังก์ชันและพร็อพเพอร์ตี้ภายในมีจุดประสงค์เพื่อใช้ภายในไลบรารีหลัก แต่ไม่ใช้ภายนอก โดยใช้คำอธิบายประกอบ @internal
ของ TsDoc
พร็อพเพอร์ตี้ภายในอาจมีการเปลี่ยนแปลงโดยไม่มีการแจ้งเตือน เนื่องจากไม่ได้เป็นส่วนหนึ่งของ API สาธารณะของ Blockly
คุณสามารถเข้าถึงพร็อพเพอร์ตี้ภายในได้จากทุกที่ภายในบริการหลัก และลบล้างในคลาสย่อยใน Core ตราบใดที่ลายเซ็นไม่มีการเปลี่ยนแปลง และจะต้องไม่เข้าถึงจากภายนอก ไลบรารีหลัก
เลิกใช้งานแล้ว
ไม่ควรใช้ทุกส่วนที่ทำเครื่องหมายเป็น @deprecated
การเลิกใช้งานโดยส่วนใหญ่จะมีคำแนะนำในโค้ดที่ต้องการ ทั้งในคำเตือนของคอนโซลหรือ TSDoc
หากเป็นไปได้ ฟังก์ชันที่เลิกใช้งานแล้วจะบันทึกคำเตือนที่ระบุวันที่ลบที่กำหนดไว้ และคำแนะนำสำหรับการเรียกใช้ฟังก์ชันทดแทน
คำถามที่พบบ่อย
จะเกิดอะไรขึ้นหากฟังก์ชันที่ฉันต้องการใช้งานไม่แสดงต่อสาธารณะ
ส่งคำขอฟีเจอร์ ในบริการหลักของ Blockly ใส่คำอธิบาย Use Case ของคุณและข้อความถึงสิ่งที่คุณต้องการให้เราเผยแพร่ต่อสาธารณะ
เราจะใช้ฟีเจอร์นี้เพื่อปรึกษากันว่าเราจะเผยแพร่ข้อมูลนี้ต่อสาธารณะไหม หรือคุณมีวิธีอื่นๆ ในการรับข้อมูลเดียวกันนี้ไหม
หากเราตัดสินใจตั้งค่าเป็นแบบสาธารณะ คุณหรือทีม Blockly จะทำการเปลี่ยนแปลงตามความเหมาะสม และจะเผยแพร่ใน Blockly รุ่นถัดไป
หากเลือกใช้สมาชิกที่ไม่ใช่แบบสาธารณะในปลั๊กอิน ให้พิจารณาระบุปลั๊กอินเป็นเบต้าและระบุข้อมูลดังกล่าวใน README
แล้วการแพตช์ลิงล่ะ
โปรดอ่านเกี่ยวกับ monkeypatching
Monkeypatching ไม่ปลอดภัยเนื่องจากแพตช์อาจหยุดทำงานโดยไม่มีการแจ้งเตือนเนื่องจากมีการใช้ส่วนที่ไม่เผยแพร่ต่อสาธารณะของ Blockly API การแพตช์ในปลั๊กอินเป็นเรื่องอันตรายอย่างยิ่ง เนื่องจากโค้ดอาจมีการโต้ตอบที่ไม่ดีกับปลั๊กอินอื่นๆ ที่ใช้แพตช์โค้ดเดียวกัน ด้วยเหตุนี้ เราจึงขอแนะนำอย่างยิ่ง ไม่ให้ใช้ Monkeypatching ในแอปพลิเคชันและปลั๊กอินของบุคคลที่สาม และไม่ยอมรับในปลั๊กอินของบุคคลที่หนึ่ง
ฉันจะลบล้างฟังก์ชันสาธารณะได้ไหม
ในคลาสย่อย: ใช่ หรือคำตอบคือไม่ นั่นก็คือการแพทเทิร์น
ฉันจะลบล้างฟังก์ชันที่มีการป้องกันได้ไหม
ในคลาสย่อย: ใช่ หรือคำตอบคือไม่ นั่นก็คือการแพทเทิร์น
ฉันลบล้างฟังก์ชันภายในหรือส่วนตัวได้ไหม
ไม่ นั่นก็คือการแพทเทิร์น
ฉันจะเข้าถึงพร็อพเพอร์ตี้โดยตรงได้เมื่อใด ควรใช้ Getter หรือ Setter เมื่อใด
หากเราเผยแพร่ Getter หรือ Setter โปรดใช้ API แทนการเข้าถึงพร็อพเพอร์ตี้โดยตรง หากพร็อพเพอร์ตี้ไม่ใช่สาธารณะ ให้ใช้ Getters และ Setter
จะเกิดอะไรขึ้นหากพร็อพเพอร์ตี้ไม่มีคำอธิบายประกอบ
ค่าเริ่มต้นคือสาธารณะ แต่โปรดแจ้งให้เราทราบหากเราต้องการใส่คู่ Getter/Setter แทนคุณ
จะเกิดอะไรขึ้นหากฟังก์ชันไม่มีคำอธิบายประกอบ
เป็นแบบสาธารณะโดยค่าเริ่มต้น
ฉันต้องทำอย่างไรหากยังไม่แน่ใจ
ถามคำถามในฟอรัม แล้วเราจะติดต่อกลับหาคุณภายใน 1 วันทำการ