การใช้ Blockly API

บทนำ

หน้านี้อธิบายแนวทางปฏิบัติแนะนำสำหรับฟังก์ชันการเรียกใช้และการเข้าถึง ใน Blockly หลัก หลักการเหล่านี้ใช้กับการสร้างปลั๊กอินสำหรับ บล็อกหรือผสานรวม Blockly ไว้ในแอปพลิเคชันแบบสแตนด์อโลน

การแยกประเภทย่อยและการขยายระยะเวลา

Blockly มีกรอบการทำงานที่หลากหลายสำหรับการเพิ่มฟังก์ชันการทำงาน ดังนี้

  • คลาสย่อย (เช่น การสร้างโหมดแสดงภาพใหม่)
  • มิกซ์ (เช่น การเพิ่มส่วนขยายบล็อกหรือ Mutator)
  • คําจํากัดความของการบล็อก (เช่น คําจํากัดความของการบล็อกกระบวนการ)

ตามจุดประสงค์ของเอกสารนี้ ทั้ง 3 กรณีมีค่าเท่ากับ ใหม่ได้อีกด้วย

การแทรกคลาสย่อย

เรารองรับการแทนที่ชั้นเรียนบางชั้นเรียนโดยใช้เมธอด Blockly.inject เหล่านี้ คลาสย่อยต้องขยายคลาสพื้นฐานหรือนำคลาสย่อยมาใช้ ของ Google

คุณส่งคลาสย่อยไปยังเมธอดการแทรกได้

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 ใหม่เป็นแบบสาธารณะในรุ่นเดียวและ แก้ไขได้ในรุ่นถัดไปเพื่อตอบสนองต่อความคิดเห็นก่อนหน้านี้ หลังจากนั้นคุณสามารถ พิจารณาฟังก์ชันสาธารณะหรือทรัพย์สินที่มั่นคง

ฟังก์ชันสาธารณะอาจมีการเรียกได้จากทุกที่ และถูกลบล้างในคลาสย่อยเป็น ตราบใดที่ลายเซ็นไม่เปลี่ยนแปลง

ป้องกัน

เข้าถึงฟังก์ชันและพร็อพเพอร์ตี้ที่มีการป้องกันได้โดยคลาสที่กำหนดหรือ คลาสย่อย

คลาสย่อยสามารถลบล้างฟังก์ชันและพร็อพเพอร์ตี้ที่มีการป้องกัน การเปลี่ยนลายเซ็นประเภท

ตัวอย่างเช่น โหมดแสดงภาพที่กำหนดเองที่ขยายคลาสโหมดแสดงภาพพื้นฐานอาจเข้าถึงได้ พร็อพเพอร์ตี้ที่ได้รับการคุ้มครอง

ในแต่ละกรณี คุณควรทำความเข้าใจเกี่ยวกับฟังก์ชันหรือพร็อพเพอร์ตี้ ใช้งานในโค้ดที่เหลือทั้งหมด

ส่วนตัว

คุณสามารถเข้าถึงรายการเหล่านี้ได้ด้วยโค้ดในไฟล์เดียวกับคำจำกัดความเท่านั้น โดยตรง การเข้าถึงพร็อพเพอร์ตี้เหล่านี้อาจทำให้เกิดลักษณะการทำงานที่ไม่ระบุ

ไม่อนุญาตให้คลาสย่อยลบล้างฟังก์ชันและพร็อพเพอร์ตี้ส่วนตัว

สถานที่ส่วนบุคคลอาจมีการเปลี่ยนแปลงโดยไม่ต้องแสดงคำเตือน เนื่องจากไม่ได้มีการเปลี่ยนแปลง ถือว่าเป็นส่วนหนึ่งของ API สาธารณะของ Blockly

ฟังก์ชันบางอย่างใน Blockly ไม่มีคำอธิบายประกอบระดับการมองเห็นเนื่องจาก ไม่ได้ส่งออกจากโมดูล ฟังก์ชันเหล่านี้เป็นตัวแปรภายใน และไม่สามารถใช้นอกโมดูลกำหนดได้ ควรพิจารณา ที่เทียบเท่ากับทรัพย์สินส่วนบุคคล

ภายใน

ฟังก์ชันและคุณสมบัติภายในมีจุดประสงค์เพื่อใช้ภายใน ไลบรารี แต่ไม่ใช่ภายนอก มีการกำหนดให้ใช้เอกสาร TsDoc @internal หมายเหตุ

พร็อพเพอร์ตี้ภายในอาจมีการเปลี่ยนแปลงโดยไม่มีคําเตือน เนื่องจากไม่ได้เป็นเช่นนั้น ถือว่าเป็นส่วนหนึ่งของ API สาธารณะของ Blockly

พร็อพเพอร์ตี้ภายในอาจเข้าถึงได้จากทุกที่ภายในส่วนหลักและถูกลบล้างใน คลาสย่อยในแกนหลักตราบใดที่ไม่มีการเปลี่ยนแปลงลายเซ็น และจะต้องไม่ เข้าถึงได้จากภายนอกไลบรารีหลัก

เลิกใช้งานแล้ว

สิ่งที่มีเครื่องหมายว่า @deprecated ไม่ควรใช้ การเลิกใช้งานส่วนใหญ่รวมถึง ในโค้ดที่ต้องการ ทั้งในคำเตือนของคอนโซลหรือ TSDoc

หากเป็นไปได้ ฟังก์ชันที่เลิกใช้งานแล้วจะบันทึกคำเตือนที่มีฟิลด์ วันที่ควรลบและคำแนะนำสำหรับฟังก์ชันแทนที่ที่จะเรียกใช้

คำถามที่พบบ่อย

จะเกิดอะไรขึ้นหากฟังก์ชันที่ฉันต้องการใช้ไม่ใช่สาธารณะ

ส่งคำขอฟีเจอร์ ของ Blockly ระบุรายละเอียดกรณีการใช้งานและคำชี้แจงเกี่ยวกับ คุณต้องการให้เราเปิดเผยต่อสาธารณะ

เราจะใช้ฟีเจอร์นี้เพื่อขอให้มีการพูดคุยว่าจะเผยแพร่ให้เป็นสาธารณะ หรือ ดูว่ามีวิธีอื่นๆ ที่คุณจะได้รับข้อมูลเดียวกันหรือไม่

หากเราตัดสินใจให้เป็นแบบสาธารณะ คุณหรือทีม Blockly จะ การเปลี่ยนแปลงให้เหมาะสม และจะเผยแพร่ใน Blockly ครั้งถัดไป

หากคุณเลือกใช้สมาชิกที่ไม่ใช่สาธารณะในปลั๊กอิน ให้พิจารณาทำเครื่องหมาย ปลั๊กอินรุ่นเบต้า และรวมข้อมูลไว้ใน README ของคุณ

ถักเป็นลิงด้วยมั้ย

อ่านเกี่ยวกับ monkeypatching

Monkeypatching ไม่ปลอดภัย เนื่องจากแพตช์อาจหยุดทำงานโดยไม่แจ้งให้ทราบล่วงหน้า ของการใช้ API ของ Blockly API ที่ไม่เป็นสาธารณะ การแพตช์ในปลั๊กอินปัจจุบันคือ อันตรายเป็นพิเศษ เนื่องจากโค้ดของคุณอาจมีการโต้ตอบที่ไม่เหมาะสม ที่ monkeypatatch กับโค้ดเดียวกัน ด้วยเหตุนี้ เราจึงขอ แนะนำให้ใช้ Monkeypatching ในแอปพลิเคชันและปลั๊กอินของบุคคลที่สาม และ จะไม่ยอมรับในปลั๊กอินของบุคคลที่หนึ่ง

ฉันลบล้างฟังก์ชันสาธารณะได้ไหม

เมื่อทำการจัดประเภทย่อย: ใช่ ไม่อย่างนั้น นี่มันตบตีกันนะ

ฉันจะลบล้างฟังก์ชันที่มีการป้องกันได้ไหม

เมื่อทำการจัดประเภทย่อย: ใช่ ไม่งั้นหรอก นี่มันตบตีกันเลยนะ

ฉันจะลบล้างฟังก์ชันภายในหรือฟังก์ชันส่วนตัวได้ไหม

ไม่ นั่นมันแหกปาก

ฉันจะเข้าถึงพร็อพเพอร์ตี้โดยตรงได้เมื่อใด ฉันควรใช้ Getter หรือ Setter เมื่อใด

หากเราเผยแพร่ Getter หรือ setter โปรดใช้แทนโดยตรง ในการเข้าถึงพร็อพเพอร์ตี้ หากพร็อพเพอร์ตี้ไม่ใช่สาธารณะ ให้ใช้ getters และ Setters

จะเกิดอะไรขึ้นหากพร็อพเพอร์ตี้ไม่มีคำอธิบายประกอบ

ตามค่าเริ่มต้น โปรไฟล์นี้ถือเป็นสาธารณะ แต่โปรดฝากข้อความถึงเราเผื่อไว้ในกรณีที่เราต้องการ คู่ Getter/setter ให้คุณ

จะเกิดอะไรขึ้นหากฟังก์ชันไม่มีคำอธิบายประกอบ

ค่าเริ่มต้นคือสาธารณะ

ควรทำอย่างไร หากยังไม่แน่ใจ

ถามคำถามในฟอรัม แล้วเราจะติดต่อกลับภายใน 1 วันทำการ