การใช้ Blockly API

เกริ่นนำ

หน้านี้อธิบายแนวทางปฏิบัติแนะนำสำหรับการเรียกใช้ฟังก์ชันและการเข้าถึงพร็อพเพอร์ตี้ในบริการหลักของ 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 วันทำการ