Google Docs API का असरदार तरीके से इस्तेमाल करने के लिए, आपको Google Docs दस्तावेज़ के आर्किटेक्चर और दस्तावेज़ बनाने वाले एलिमेंट के साथ-साथ, उनके बीच के संबंध को समझना होगा. इस पेज पर इन विषयों के बारे में पूरी जानकारी दी गई है:
- दस्तावेज़ के एलिमेंट का कॉन्सेप्ट मॉडल
- Docs API इन एलिमेंट को कैसे दिखाता है
- स्टाइलिंग प्रॉपर्टी
टॉप-लेवल एलिमेंट
Google Docs में सबसे बाहरी कंटेनर एलिमेंट, दस्तावेज़ होता है. यह एक ऐसी यूनिट है जिसे Google Drive में सेव किया जा सकता है, अन्य उपयोगकर्ताओं के साथ शेयर किया जा सकता है, और टेक्स्ट और इमेज के साथ अपडेट किया जा सकता है.
documents संसाधन के टॉप-लेवल एलिमेंट में, इसके Tab, SuggestionsViewMode, और अन्य एट्रिब्यूट शामिल होते हैं:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
टैब
एक दस्तावेज़ में कई टैब हो सकते हैं. इनमें टेक्स्ट लेवल का अलग-अलग कॉन्टेंट होता है. दस्तावेज़ की tabs प्रॉपर्टी, Tab ऑब्जेक्ट का क्रम होती है. Tab में ये फ़ील्ड शामिल होते हैं:
TabProperties: इसमें टैब के एट्रिब्यूट होते हैं. जैसे, आईडी, टाइटल, और इंडेक्स.childTabs: इससे किसी टैब के चाइल्ड टैब (ऐसे टैब जो सीधे तौर पर इसके नीचे नेस्ट किए गए हैं) दिखते हैं.DocumentTab: यह किसी टैब के टेक्स्ट कॉन्टेंट को दिखाता है.
बाद के सेक्शन में, दस्तावेज़ टैब के क्रम के बारे में खास जानकारी दी गई है. साथ ही, टैब के JSON फ़ॉर्मैट में भी ज़्यादा जानकारी दी गई है. टैब की सुविधा के बारे में ज़्यादा जानने के लिए, टैब के साथ काम करना लेख पढ़ें.
Body कॉन्टेंट के बाहर, ग्लोबल दस्तावेज़ टैब की सुविधाओं में बदलाव करने के लिए, एक या उससे ज़्यादा दस्तावेज़ टेंप्लेट का इस्तेमाल करना हमेशा बेहतर होता है. इनका इस्तेमाल, प्रोग्राम के हिसाब से नए दस्तावेज़ जनरेट करने के लिए किया जा सकता है. ज़्यादा जानकारी के लिए, किसी दस्तावेज़ में टेक्स्ट मर्ज करना लेख पढ़ें.
मुख्य कॉन्टेंट
Body में आम तौर पर, किसी दस्तावेज़ के टैब का पूरा कॉन्टेंट होता है. प्रोग्राम के हिसाब से इस्तेमाल किए जा सकने वाले ज़्यादातर आइटम, Body कॉन्टेंट में मौजूद एलिमेंट होते हैं:
स्ट्रक्चरल एलिमेंट
StructuralElement, दस्तावेज़ के स्ट्रक्चर के बारे में बताता है. Body कॉन्टेंट, StructuralElement ऑब्जेक्ट का क्रम होता है. कॉन्टेंट एलिमेंट, हर StructuralElement ऑब्जेक्ट को आपकी पसंद के मुताबिक बनाता है. इसे इस डायग्राम में दिखाया गया है:
स्ट्रक्चरल एलिमेंट और उनके कॉन्टेंट ऑब्जेक्ट में, दस्तावेज़ में मौजूद सभी विज़ुअल कॉम्पोनेंट शामिल होते हैं. इसमें टेक्स्ट, इनलाइन इमेज, और फ़ॉर्मैटिंग शामिल है.
पैराग्राफ़ का स्ट्रक्चर
Paragraph, StructuralElement है, जो पैराग्राफ़ के बारे में बताता है. इसमें कई तरह का कॉन्टेंट होता है. हर कॉन्टेंट के आखिर में नई लाइन का वर्ण होता है. इसमें ये ऑब्जेक्ट शामिल होते हैं:
ParagraphElement: किसी पैराग्राफ़ में मौजूद कॉन्टेंट के बारे में बताता है.ParagraphStyle: यह एक वैकल्पिक एलिमेंट है. इससे पैराग्राफ़ के लिए स्टाइल प्रॉपर्टी सेट की जाती हैं.Bullet: अगर पैराग्राफ़ किसी सूची का हिस्सा है, तो यह एक ऐसा एलिमेंट होता है जो बुलेट के बारे में जानकारी देता है. यह एलिमेंट ज़रूरी नहीं है.
ParagraphElement, StructuralElement की तरह काम करता है. कॉन्टेंट एलिमेंट टाइप का एक सेट (जैसे, ColumnBreak और Equation) अपने ParagraphElement को पसंद के मुताबिक बनाता है. इसे इस डाइग्राम में दिखाया गया है:
पूरे दस्तावेज़ के स्ट्रक्चर का उदाहरण देखने के लिए, JSON फ़ॉर्मैट में दस्तावेज़ का उदाहरण देखें. आउटपुट में, आपको स्ट्रक्चर और कॉन्टेंट के कई मुख्य एलिमेंट दिख सकते हैं. साथ ही, आपको स्टार्ट और एंड इंडेक्स का इस्तेमाल भी दिखेगा. इसके बारे में अगले सेक्शन में बताया गया है.
टेक्स्ट रन
TextRun एक ParagraphElement है. यह एक ही स्टाइल वाले टेक्स्ट की लगातार स्ट्रिंग को दिखाता है. किसी पैराग्राफ़ में एक से ज़्यादा टेक्स्ट रन हो सकते हैं, लेकिन टेक्स्ट रन कभी भी पैराग्राफ़ की सीमाओं को पार नहीं करते. कॉन्टेंट को न्यूलाइन वर्ण के बाद अलग-अलग टेक्स्ट रन में बांटा जाता है. उदाहरण के लिए, इस छोटे दस्तावेज़ पर ध्यान दें:
इस डायग्राम में दिखाया गया है कि पिछले दस्तावेज़ में पैराग्राफ़ के क्रम को कैसे विज़ुअलाइज़ किया जा सकता है. हर पैराग्राफ़ में अपना TextRun और Bullet सेटिंग होती है.
AutoText
AutoText एक ParagraphElement है. यह टेक्स्ट में ऐसी जगह को दिखाता है जिसे डाइनैमिक तरीके से बदल दिया जाता है. इस जगह पर ऐसा कॉन्टेंट होता है जो समय के साथ बदल सकता है. Docs में, इसका इस्तेमाल पेज नंबर के लिए किया जाता है.
शुरू और खत्म होने के इंडेक्स
किसी दस्तावेज़ के टैब के कॉन्टेंट में बदलाव करने पर, हर बदलाव दस्तावेज़ में किसी जगह या किसी रेंज में होता है. इन जगहों और रेंज के बारे में बताने के लिए, इंडेक्स का इस्तेमाल किया जाता है. ये इंडेक्स, किसी दस्तावेज़ के सेगमेंट में ऑफ़सेट को दिखाते हैं. सेगमेंट, बॉडी, हेडर, फ़ुटर या फ़ुटनोट होता है. इसमें स्ट्रक्चर या कॉन्टेंट एलिमेंट शामिल होते हैं. किसी सेगमेंट में मौजूद एलिमेंट के इंडेक्स, उस सेगमेंट की शुरुआत के हिसाब से होते हैं.
मुख्य कॉन्टेंट में मौजूद ज़्यादातर एलिमेंट में, ज़ीरो पर आधारित startIndex और endIndex प्रॉपर्टी होती हैं. इनसे किसी एलिमेंट के शुरू और खत्म होने के ऑफ़सेट का पता चलता है. यह ऑफ़सेट, एलिमेंट को शामिल करने वाले सेगमेंट की शुरुआत के हिसाब से होता है. Docs API के लिए, एक साथ कई कॉल को क्रम से लगाने के तरीके के बारे में ज़्यादा जानने के लिए, एक साथ कई अपडेट देखें.
इंडेक्स को UTF-16 कोड यूनिट में मापा जाता है. इसका मतलब है कि सरोगेट जोड़े दो इंडेक्स का इस्तेमाल करते हैं. उदाहरण के लिए, "मुस्कुराता हुआ चेहरा" इमोजी, 😄, को \uD83D\uDE00 के तौर पर दिखाया जाता है. यह दो इंडेक्स का इस्तेमाल करता है.
दस्तावेज़ के मुख्य हिस्से में मौजूद एलिमेंट के लिए, इंडेक्स मुख्य हिस्से के कॉन्टेंट की शुरुआत से ऑफ़सेट दिखाते हैं. मुख्य हिस्सा, "रूट" एलिमेंट होता है.
स्ट्रक्चरल एलिमेंट के लिए "व्यक्ति के हिसाब से बनाना" टाइप—SectionBreak, TableOfContents, Table, और Paragraph—में ये इंडेक्स नहीं होते, क्योंकि इनके StructuralElement में ये फ़ील्ड होते हैं. यह बात, ParagraphElement में शामिल निजी डेटा के टाइप पर भी लागू होती है. जैसे, TextRun, AutoText, और PageBreak.
ऐक्सेस एलिमेंट
documents.batchUpdate तरीके से कई एलिमेंट में बदलाव किया जा सकता है. उदाहरण के लिए, InsertTextRequest का इस्तेमाल करके, टेक्स्ट वाले किसी भी एलिमेंट के कॉन्टेंट को बदला जा सकता है. इसी तरह, एक या उससे ज़्यादा एलिमेंट में मौजूद टेक्स्ट की रेंज पर फ़ॉर्मैटिंग लागू करने के लिए, UpdateTextStyleRequest का इस्तेमाल किया जा सकता है.
दस्तावेज़ के एलिमेंट पढ़ने के लिए, documents.get तरीके का इस्तेमाल करके, पूरे दस्तावेज़ का JSON डंप पाएं. इसके बाद, अलग-अलग एलिमेंट की वैल्यू ढूंढने के लिए, नतीजे के तौर पर मिले JSON को पार्स किया जा सकता है. ज़्यादा जानकारी के लिए, आउटपुट दस्तावेज़ के कॉन्टेंट को JSON के तौर पर दिखाना लेख पढ़ें.
कॉन्टेंट को पार्स करने से, कई तरह के कामों में मदद मिल सकती है. उदाहरण के लिए, किसी दस्तावेज़ की कैटलॉगिंग करने वाले ऐप्लिकेशन पर विचार करें. यह ऐप्लिकेशन, खोजे गए दस्तावेज़ों को दिखाता है. यह ऐप्लिकेशन, किसी दस्तावेज़ के टैब का टाइटल, वर्शन आईडी, और शुरुआती पेज नंबर निकाल सकता है. इसे इस डायग्राम में दिखाया गया है:
इन सेटिंग को पढ़ने के लिए कोई तरीका उपलब्ध नहीं है. इसलिए, आपके ऐप्लिकेशन को पूरा दस्तावेज़ पाना होगा. इसके बाद, इन वैल्यू को निकालने के लिए JSON को पार्स करना होगा.
प्रॉपर्टी इनहेरिटेंस
कोई StructuralElement, अपने पैरंट ऑब्जेक्ट से प्रॉपर्टी इनहेरिट कर सकता है. किसी ऑब्जेक्ट की प्रॉपर्टी, उसकी विज़ुअल स्टाइल तय करती हैं. इनमें वे प्रॉपर्टी भी शामिल होती हैं जिन्हें ऑब्जेक्ट खुद तय करता है और वे प्रॉपर्टी भी शामिल होती हैं जिन्हें वह इनहेरिट करता है.
टेक्स्ट के वर्णों को फ़ॉर्मैट करने से यह तय होता है कि किसी दस्तावेज़ में टेक्स्ट कैसे दिखेगा. जैसे, बोल्ड, इटैलिक, और अंडरलाइन. लागू की गई फ़ॉर्मैटिंग, पैराग्राफ़ के TextStyle से मिली डिफ़ॉल्ट फ़ॉर्मैटिंग को बदल देती है.
इसके उलट, जिन वर्णों की फ़ॉर्मैटिंग सेट नहीं की जाती वे पैराग्राफ़ की स्टाइल से फ़ॉर्मैटिंग पाना जारी रखते हैं.
पैराग्राफ़ फ़ॉर्मैटिंग से यह तय होता है कि किसी दस्तावेज़ में टेक्स्ट के ब्लॉक कैसे रेंडर किए जाते हैं. जैसे, अलाइनमेंट, बॉर्डर, और इंडेंटेशन. आपके लागू किए गए फ़ॉर्मैटिंग के विकल्प, ParagraphStyle से मिले डिफ़ॉल्ट फ़ॉर्मैटिंग के विकल्प को बदल देते हैं.
इसके उलट, फ़ॉर्मैटिंग की ऐसी सभी सुविधाएं पैराग्राफ़ स्टाइल से इनहेरिट होती रहेंगी जिन्हें आपने सेट नहीं किया है.