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 में इसका इस्तेमाल पेज नंबर
के लिए किया जाता है.
इंडेक्स शुरू और खत्म करें
किसी दस्तावेज़ के कॉन्टेंट में बदलाव करते समय, हर अपडेट किसी जगह या दस्तावेज़ में अलग-अलग जगहों पर होता है. इन जगहों और रेंज को indexes का इस्तेमाल करके तय किया जाता है. ये इंडेक्स, ऐसे दस्तावेज़ सेगमेंट में ऑफ़सेट दिखाते हैं जिसमें शामिल हो. सेगमेंट, एक ऐसा मुख्य हिस्सा, हेडर, फ़ुटर या फ़ुटनोट होता है जिसमें स्ट्रक्चरल या कॉन्टेंट एलिमेंट शामिल होते हैं. किसी सेगमेंट में एलिमेंट के इंडेक्स, उस सेगमेंट की शुरुआत से जुड़े होते हैं.
मुख्य हिस्से के कॉन्टेंट के ज़्यादातर एलिमेंट में startIndex और endIndex प्रॉपर्टी शून्य पर आधारित होती हैं. ये एलिमेंट के शुरुआती और आखिरी हिस्से के मुकाबले, एलिमेंट के शुरू और खत्म होने के ऑफ़सेट को दिखाते हैं. Docs API कॉल के अपने बैच को ऑर्डर करने के तरीके के बारे में ज़्यादा जानकारी के लिए, बैच अपडेट देखें.
इंडेक्स, UTF-16 कोड यूनिट में मापे जाते हैं. इसका मतलब है कि सरोगेट जोड़े,
दो इंडेक्स का इस्तेमाल करते हैं. उदाहरण के लिए, "GRINNING FACE" इमोजी, YOUTUBE को \uD83D\uDE00 के तौर पर दिखाया जाता है और यह दो इंडेक्स का इस्तेमाल करता है.
दस्तावेज़ के मुख्य हिस्से में मौजूद एलिमेंट के लिए, इंडेक्स, मुख्य हिस्से के कॉन्टेंट की शुरुआत से ऑफ़सेट दिखाते हैं, जो "रूट" एलिमेंट है.
स्ट्रक्चरल एलिमेंट के लिए, "लोगों के हिसाब से बनाना" टाइप, जैसे कि SectionBreak,
TableOfContents,
Table, और
Paragraph में ये इंडेक्स नहीं होते हैं, क्योंकि एनक्लोज़र StructuralElement में ये फ़ील्ड होते हैं. यही बात ParagraphElement में मौजूद
TextRun, AutoText, और
PageBreak जैसे ऐप्लिकेशन को उपयोगकर्ता के मनमुताबिक बनाने की सुविधा पर भी लागू होती है.
ऐक्सेस एलिमेंट
documents.batchUpdate तरीके से कई एलिमेंट में बदलाव किया जा सकता है. उदाहरण के लिए, InsertTextRequest का इस्तेमाल करके, टेक्स्ट वाले किसी भी एलिमेंट का कॉन्टेंट बदला जा सकता है. इसी तरह, एक या एक से ज़्यादा एलिमेंट में मौजूद टेक्स्ट की रेंज में फ़ॉर्मैटिंग लागू करने के लिए, UpdateTextStyleRequest का इस्तेमाल किया जा सकता है.
दस्तावेज़ के एलिमेंट पढ़ने के लिए, पूरे दस्तावेज़ का JSON डंप पाने के लिए, documents.get तरीके का इस्तेमाल करें. इसके बाद, अलग-अलग एलिमेंट की वैल्यू ढूंढने के लिए, जनरेट किए गए JSON को पार्स किया जा सकता है. ज़्यादा जानकारी के लिए, आउटपुट दस्तावेज़ का कॉन्टेंट, JSON फ़ॉर्मैट में देखें.
कॉन्टेंट को पार्स करने से, अलग-अलग तरह के कामों में मदद मिल सकती है. उदाहरण के लिए, एक ऐसे दस्तावेज़ की सूची बनाएं जिसमें ऐप्लिकेशन को मिले दस्तावेज़ों की सूची मौजूद हो. यह ऐप्लिकेशन, दस्तावेज़ का टाइटल, रिविज़न आईडी, और शुरुआती पेज नंबर एक्सट्रैक्ट कर सकता है, जैसा कि नीचे डायग्राम में दिखाया गया है:
साफ़ तौर पर इन सेटिंग को पढ़ने का कोई तरीका नहीं है, इसलिए आपके ऐप्लिकेशन को पूरे दस्तावेज़ की जानकारी लेनी होगी और फिर इन वैल्यू को एक्सट्रैक्ट करने के लिए, JSON को पार्स करना होगा.
प्रॉपर्टी इनहेरिटेंस
StructuralElement अपने पैरंट ऑब्जेक्ट से प्रॉपर्टी इनहेरिट कर सकता है. किसी ऑब्जेक्ट की प्रॉपर्टी, उसके फ़ाइनल विज़ुअल लुक को तय करती हैं. इनमें, तय की गई और इनहेरिट की गई प्रॉपर्टी भी शामिल होती हैं.
टेक्स्ट कैरेक्टर फ़ॉर्मैटिंग से यह तय होता है कि किसी दस्तावेज़ में टेक्स्ट कैसे रेंडर होगा. जैसे, बोल्ड, इटैलिक, और अंडरलाइन. लागू किया गया फ़ॉर्मैट, पैराग्राफ़ के TextStyle से इनहेरिट किए गए डिफ़ॉल्ट फ़ॉर्मैट को बदल देता है. इसके ठीक उलट, आपने जिन वर्णों की फ़ॉर्मैटिंग सेट नहीं की है वे पैराग्राफ़ की स्टाइल को अपनाते हैं.
पैराग्राफ़ फ़ॉर्मैटिंग से यह तय होता है कि किसी दस्तावेज़ में टेक्स्ट के ब्लॉक कैसे रेंडर किए जाते हैं.
जैसे, अलाइनमेंट, बॉर्डर, और इंडेंट. लागू की गई फ़ॉर्मैटिंग, ParagraphStyle से इनहेरिट की गई डिफ़ॉल्ट फ़ॉर्मैटिंग को बदल देती है.
इसके ठीक उलट, आपने जिन फ़ॉर्मैटिंग सुविधाओं को सेट नहीं किया है वे पैराग्राफ़ स्टाइल से इनहेरिट करती रहती हैं.