Google Docs API का बेहतर तरीके से इस्तेमाल करने के लिए, आपको Google Docs दस्तावेज़ के आर्किटेक्चर और दस्तावेज़ बनाने वाले एलिमेंट को समझना होगा. साथ ही, आपको उनके बीच के संबंध को भी समझना होगा. इस पेज पर इन विषयों के बारे में खास जानकारी दी गई है:
- दस्तावेज़ के एलिमेंट का कॉन्सेप्चुअल मॉडल
- Docs API इन एलिमेंट को कैसे दिखाता है
- एलिमेंट की स्टाइलिंग प्रॉपर्टी
टॉप लेवल एलिमेंट
Google Docs का सबसे बाहरी कंटेनर एलिमेंट, दस्तावेज़ होता है. यह ऐसी इकाई है जिसे Google Drive में सेव किया जा सकता है और दूसरे उपयोगकर्ताओं के साथ शेयर किया जा सकता है. साथ ही, इसे टेक्स्ट और इमेज की मदद से अपडेट किया जा सकता है.
documents
संसाधन के टॉप-लेवल एलिमेंट में Body
,Header
, Footer
, और कई दूसरे एट्रिब्यूट शामिल हैं:
document: { body: ... , documentStyle: ... , lists: ... , documentId: ... , namedStyles: ... , revisionId: ... , title: ... }
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 कोड यूनिट में किया जाता है. इसका मतलब है कि सरोगेट जोड़े दो इंडेक्स
इस्तेमाल करते हैं. उदाहरण के लिए, "GRINNING FACE" इमोजी, टारगेट को \uD83D\uDE00
के तौर पर दिखाया जाता है और यह दो इंडेक्स का इस्तेमाल करता है.
दस्तावेज़ के मुख्य हिस्से में एलिमेंट के लिए, इंडेक्स मुख्य हिस्से के कॉन्टेंट की शुरुआत से ऑफ़सेट को दिखाते हैं, जो "रूट" एलिमेंट होता है.
स्ट्रक्चरल एलिमेंट के लिए "मनमुताबिक बनाने" के टाइप—SectionBreak
,
TableOfContents
,
Table
, और
Paragraph
— में ये इंडेक्स नहीं होते, क्योंकि उन्हें शामिल किया जाता है
StructuralElement
में ये फ़ील्ड होते हैं. यह ParagraphElement
में मौजूद, मनमुताबिक बनाने के टाइप पर भी लागू होता है, जैसे कि TextRun
, AutoText
, और
PageBreak
.
ऐक्सेस एलिमेंट
कई एलिमेंट में documents.batchUpdate
तरीके से बदलाव किया जा सकता है. उदाहरण के लिए, InsertTextRequest
का इस्तेमाल करके, टेक्स्ट वाले किसी भी एलिमेंट का कॉन्टेंट बदला जा सकता है. इसी तरह, एक या एक से ज़्यादा एलिमेंट में मौजूद टेक्स्ट की रेंज पर फ़ॉर्मैटिंग लागू करने के लिए, UpdateTextStyleRequest
का इस्तेमाल करें.
दस्तावेज़ के एलिमेंट पढ़ने के लिए, documents.get
तरीके का इस्तेमाल करके, पूरे दस्तावेज़ का JSON डंप पाएं. इसके बाद, बनने वाले JSON को पार्स करके, अलग-अलग एलिमेंट की वैल्यू
ढूंढी जा सकती हैं. ज़्यादा जानकारी के लिए, आउटपुट दस्तावेज़ की सामग्री JSON के रूप में देखें.
कॉन्टेंट को पार्स करने से, अलग-अलग कामों में मदद मिल सकती है. उदाहरण के लिए, ऐप्लिकेशन की सूची में शामिल दस्तावेज़ों की सूची बनाने वाले दस्तावेज़ों का इस्तेमाल करें. यह ऐप्लिकेशन किसी दस्तावेज़ का टाइटल, रिविज़न आईडी, और शुरुआती पेज नंबर एक्सट्रैक्ट कर सकता है, जैसा कि इस डायग्राम में दिखाया गया है:
इन सेटिंग को साफ़ तौर पर पढ़ने का कोई तरीका नहीं है. इसलिए, आपके ऐप्लिकेशन को पूरे दस्तावेज़ को हासिल करना होगा. इसके बाद, इन वैल्यू को एक्सट्रैक्ट करने के लिए JSON को पार्स करना होगा.
प्रॉपर्टी इनहेरिटेंस
StructuralElement
अपने पैरंट ऑब्जेक्ट से प्रॉपर्टी को इनहेरिट कर सकता है. किसी ऑब्जेक्ट की प्रॉपर्टी
यह तय करती है कि ऑब्जेक्ट का विज़ुअल कैसा दिखेगा.
टेक्स्ट कैरेक्टर फ़ॉर्मैटिंग से यह तय होता है कि किसी दस्तावेज़ में टेक्स्ट कैसे रेंडर होगा. जैसे, बोल्ड, इटैलिक, और अंडरलाइन. लागू किया गया फ़ॉर्मैटिंग, पैराग्राफ़ के TextStyle
से इनहेरिट किए गए डिफ़ॉल्ट फ़ॉर्मैट को बदल देता है. इसके उलट, जिस वर्ण की फ़ॉर्मैटिंग सेट नहीं की जाती वह पैराग्राफ़ की स्टाइल से इनहेरिट किया जाता है.
पैराग्राफ़ फ़ॉर्मैटिंग से यह तय होता है कि दस्तावेज़ में टेक्स्ट के ब्लॉक कैसे रेंडर होंगे, जैसे कि अलाइनमेंट, बॉर्डर, और इंडेंट. लागू की गई फ़ॉर्मैटिंग, ParagraphStyle
से इनहेरिट की गई डिफ़ॉल्ट फ़ॉर्मैटिंग को बदल देती है.
इसके उलट, फ़ॉर्मैट की ऐसी कोई भी सुविधा जिसे आपने सेट नहीं किया है वह पैराग्राफ़ की स्टाइल से मिलती-जुलती जारी रहती है.