Blockly एपीआई का इस्तेमाल करना

शुरुआती जानकारी

इस पेज पर Blockly में कॉल फ़ंक्शन करने और प्रॉपर्टी ऐक्सेस करने के सबसे सही तरीके बताए गए हैं. ये सिद्धांत, Blockly के लिए प्लग इन बनाने या किसी स्टैंडअलोन ऐप्लिकेशन में Blockly को इंटिग्रेट करने पर लागू होते हैं.

सब-क्लासिंग और एक्सटेंडिंग

ब्लॉकली में सुविधाओं को जोड़ने के लिए कई उदाहरण हैं. जैसे:

  • सब-क्लास (जैसे, नया रेंडरर बनाना)
  • मिक्स इन (उदाहरण के लिए, ब्लॉक एक्सटेंशन या म्यूटेटर जोड़ना)
  • ब्लॉक करने की परिभाषाएं (जैसे, प्रोसेस ब्लॉक की परिभाषाएं)

इस दस्तावेज़ के लिहाज़ से, ये तीनों मामले सब-क्लासिंग के बराबर हैं.

सब-क्लास शामिल करना

हम कुछ क्लास को 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

इंटरफ़ेस का इस्तेमाल करने के बारे में ज़्यादा जानकारी के लिए, दस्तावेज़ का इंटरफ़ेस सेक्शन देखें.

विज़िबिलिटी

हम मुख्य लाइब्रेरी में 'किसको दिखे' सेटिंग को public, private या protected के तौर पर मार्क करने के लिए, TypeScript ऐक्सेस मॉडिफ़ायर का इस्तेमाल करते हैं. TsDoc की टिप्पणियों में कुछ प्रॉपर्टी के साथ, @internal के बारे में जानकारी दी जा सकती है.

सभी public और protected प्रॉपर्टी का दस्तावेज़, Blockly की वेबसाइट के पहचान फ़ाइलें सेक्शन में दिया गया है. कोड को पढ़कर यह भी देखा जा सकता है कि किसको दिखे.

सार्वजनिक

public के तौर पर मार्क की गई सभी चीज़ें, हमारे सार्वजनिक एपीआई का हिस्सा होती हैं. मॉड्यूल में मौजूद जिस प्रॉपर्टी में विज़िबिलिटी मॉडिफ़ायर नहीं होता है उसे सार्वजनिक माना जाता है.

हमारी कोशिश रहती है कि हम अपने सार्वजनिक एपीआई में बार-बार या किसी अच्छे वजह और चेतावनी के बिना बदलाव न करें. अपवाद: हम एक रिलीज़ में, एपीआई को सार्वजनिक कर सकते हैं और शुरुआती सुझाव को ध्यान में रखते हुए, अगली रिलीज़ में इसमें बदलाव कर सकते हैं. इसके बाद, आपको किसी सार्वजनिक काम या प्रॉपर्टी को स्टेबल चुनने का विकल्प मिल सकता है.

सार्वजनिक फ़ंक्शन को कहीं से भी कॉल किया जा सकता है. साथ ही, जब तक हस्ताक्षर में बदलाव नहीं होता, तब तक सब-क्लास में उन्हें बदला जा सकता है.

सुरक्षित किया गया

सुरक्षित फ़ंक्शन और प्रॉपर्टी को सिर्फ़ तय करने वाली क्लास या सब-क्लास ऐक्सेस कर सकता है.

सब-क्लास को सुरक्षित फ़ंक्शन और प्रॉपर्टी को बदलने की अनुमति है, वह भी टाइप सिग्नेचर में बदलाव किए बिना.

उदाहरण के लिए, बेस रेंडरर क्लास को बढ़ाने वाला कस्टम रेंडरर, उसकी सुरक्षित की गई प्रॉपर्टी को ऐक्सेस कर सकता है.

हर मामले में, आपको यह समझना चाहिए कि बाकी कोड में फ़ंक्शन या प्रॉपर्टी को कैसे इस्तेमाल किया जाता है.

निजी

इन्हें सिर्फ़ उसी फ़ाइल में मौजूद कोड से ऐक्सेस किया जा सकता है जिसमें परिभाषा दी गई है. इन प्रॉपर्टी को सीधे ऐक्सेस करने से, काम करने के तरीके में कोई बदलाव हो सकता है.

सब-क्लास को निजी फ़ंक्शन और प्रॉपर्टी को बदलने की अनुमति नहीं है.

निजी प्रॉपर्टी बिना किसी चेतावनी के बदली जा सकती हैं, क्योंकि उन्हें Blockly के सार्वजनिक एपीआई का हिस्सा नहीं माना जाता है.

Blockly के कुछ फ़ंक्शन में 'किसको दिखे' एनोटेशन नहीं होते, क्योंकि उन्हें उनके मॉड्यूल से एक्सपोर्ट नहीं किया जाता. ये फ़ंक्शन मुख्य तौर पर लोकल वैरिएबल होते हैं और तय करने वाले मॉड्यूल के बाहर इस्तेमाल नहीं किए जा सकते. इन्हें निजी प्रॉपर्टी की तरह ही देखा जाना चाहिए.

आंतरिक

अंदरूनी फ़ंक्शन और प्रॉपर्टी कोर लाइब्रेरी में इस्तेमाल किया जाना चाहिए, बाहर से नहीं. इन्हें TsDoc @internal एनोटेशन के साथ तय किया जाता है.

इंटरनल प्रॉपर्टी में बिना किसी चेतावनी के बदलाव किया जा सकता है, क्योंकि उन्हें Blockly के सार्वजनिक एपीआई का हिस्सा नहीं माना जाता है.

इंटरनल प्रॉपर्टी को कोर में कहीं से भी ऐक्सेस किया जा सकता है. साथ ही, जब तक हस्ताक्षर में बदलाव नहीं होता, तब तक कोर में सब-क्लास में इसे बदला जा सकता है. उन्हें मुख्य लाइब्रेरी के बाहर से ऐक्सेस नहीं किया जाना चाहिए.

बंद किया गया

@deprecated के तौर पर मार्क की गई कोई भी चीज़ इस्तेमाल नहीं की जानी चाहिए. ज़्यादातर मामलों में, पसंदीदा कोड पर निर्देश देना शामिल होता है. ऐसा कंसोल पर चेतावनी या TSDoc के तौर पर किया जाता है.

जहां भी संभव होगा, काम नहीं करने वाले फ़ंक्शन एक चेतावनी लॉग करेंगे. इसमें डेटा मिटाने की तय तारीख शामिल होगी. साथ ही, किसी दूसरे फ़ंक्शन को कॉल करने का सुझाव दिया जाएगा.

अक्सर पूछे जाने वाले सवाल

अगर मुझे जिस फ़ंक्शन का इस्तेमाल करना है वह सार्वजनिक नहीं है, तो क्या होगा?

ब्लॉकली के मुख्य फ़ंक्शन पर सुविधा का अनुरोध करें. अपने इस्तेमाल के उदाहरण का ब्यौरा दें. साथ ही, यह भी बताएं कि आपको हमसे किस तरह की जानकारी सार्वजनिक करनी है.

हम इस सुविधा का इस्तेमाल, अनुरोध करके यह चर्चा करेंगे कि इसे सार्वजनिक करना है या नहीं या आपके पास इस जानकारी को पाने के दूसरे तरीके हैं या नहीं.

अगर हम इसे सार्वजनिक करने का फ़ैसला करते हैं, तो आप या Blockly की टीम इसमें सही बदलाव करेगी. यह बदलाव, Blockly के अगले वर्शन में लाइव हो जाएगा.

अगर आपको प्लगिन में ऐसे सदस्य का इस्तेमाल करना है जो सार्वजनिक न हो, तो अपने प्लग इन को बीटा के तौर पर मार्क करें और उस जानकारी को अपने README में शामिल करें.

बंदरपैचिंग के बारे में क्या?

बंदर की पट्टी के बारे में पढ़ें.

बंदरपैच करना असुरक्षित है, क्योंकि Blockly API के गैर-सार्वजनिक हिस्सों का इस्तेमाल करने की वजह से, पैच बिना सूचना के काम करना बंद कर सकते हैं. प्लगिन में पैच करना खास तौर पर खतरनाक होता है, क्योंकि हो सकता है कि आपका कोड, किसी ऐसे दूसरे प्लगिन के साथ ठीक से इंटरैक्ट न करे जो उसी कोड को बंद करता हो. इस वजह से, हम ऐप्लिकेशन और तीसरे पक्ष के प्लग इन में बंदरपैचिंग के इस्तेमाल की जोरदार सलाह देते हैं. साथ ही, पहले पक्ष के प्लग इन में इसे स्वीकार नहीं करेंगे.

क्या सार्वजनिक फ़ंक्शन को बदला जा सकता है?

सब-क्लास करते समय: हां. नहीं तो: नहीं, यह बंदरपैचिंग है.

क्या सुरक्षित फ़ंक्शन को बदला जा सकता है?

सब-क्लास करते समय: हां. नहीं तो: नहीं, यह बंदरपैचिंग है.

क्या इंटरनल या निजी फ़ंक्शन को बदला जा सकता है?

नहीं, इसे बंदरपैचिंग कर रहा है.

प्रॉपर्टी को सीधे ऐक्सेस कब किया जा सकता है? मुझे गैटर या सेटर का इस्तेमाल कब करना चाहिए?

अगर हम किसी गैटर या सेटर को पब्लिश करते हैं, तो सीधे प्रॉपर्टी को ऐक्सेस करने के बजाय कृपया उसका इस्तेमाल करें. अगर प्रॉपर्टी सार्वजनिक नहीं है, तो गैटर और सेटर इस्तेमाल करें.

किसी प्रॉपर्टी में एनोटेशन न होने पर क्या होता है?

डिफ़ॉल्ट रूप से यह सार्वजनिक होता है, लेकिन अगर हमें आपके लिए गेटर/सेटर पेयर की सुविधा देनी हो, तो कृपया हमें एक लाइन दें.

अगर किसी फ़ंक्शन में एनोटेशन न हो, तो क्या होता है?

यह डिफ़ॉल्ट रूप से सार्वजनिक होता है.

अगर मुझे अब भी पक्के तौर पर नहीं पता है, तो क्या करना होगा?

फ़ोरम पर कोई सवाल पूछें. इसके बाद, हम आपसे एक कामकाजी दिन में संपर्क करेंगे.