पेज, पेज एलिमेंट, और प्रॉपर्टी

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

• प्रज़ेंटेशन के कॉम्पोनेंट का कॉन्सेप्चुअल मॉडल
• एपीआई इन कॉम्पोनेंट को कैसे दिखाता है
• कॉम्पोनेंट की स्टाइलिंग प्रॉपर्टी

इस खास जानकारी और अन्य कॉन्सेप्ट की खास जानकारी को पढ़ने से, इस्तेमाल करने के तरीके, रेफ़रंस दस्तावेज़, और कोड सैंपल को समझना और इस्तेमाल करना आसान हो जाएगा.

प्रज़ेंटेशन, पेज, और पेज एलिमेंट

Google Slides में सबसे बाहरी कंटेनर एलिमेंट, प्रज़ेंटेशन होता है. यह वह यूनिट है जिसे Google Drive में सेव किया जा सकता है, अन्य उपयोगकर्ताओं के साथ शेयर किया जा सकता है वगैरह.

हर प्रज़ेंटेशन में अलग-अलग तरह के पेज होते हैं. पेज का एक टाइप स्लाइड है. ये वे पेज होते हैं जिन्हें उपयोगकर्ता स्क्रीन पर प्रज़ेंटेशन रेंडर होने पर देखते हैं और उनके बीच स्विच करते हैं.

हर पेज में कई पेज एलिमेंट होते हैं. ये सभी एलिमेंट मिलकर पेज का कॉन्टेंट बनाते हैं, जैसा कि इस डायग्राम में दिखाया गया है:

स्लाइड के अलावा, अन्य तरह के पेज भी होते हैं. इनकी मदद से, कई अलग-अलग स्लाइड पर डिज़ाइन लागू किया जा सकता है. इससे एक जैसा लुक मिलता है. ये अन्य पेज टाइप, मास्टर और लेआउट हैं. इनकी प्रॉपर्टी से यह तय होता है कि स्लाइड कैसे रेंडर होंगी. इसके बारे में यहां दिए गए डायग्राम में बताया गया है:

मास्टर — मास्टर पेज के दो मकसद होते हैं. मास्टर स्लाइड पर मौजूद प्लेसहोल्डर में, आपके पूरे प्रज़ेंटेशन में इस्तेमाल किए गए टेक्स्ट स्टाइल के लिए डिफ़ॉल्ट स्टाइल होते हैं. मास्टर स्लाइड का बैकग्राउंड और अन्य आकृतियां, उस मास्टर स्लाइड पर आधारित सभी स्लाइड के लिए डिफ़ॉल्ट बैकग्राउंड बनाती हैं. अगर आपके पास कंपनी का कोई लोगो है और आपको उसे प्रज़ेंटेशन की हर स्लाइड पर दिखाना है, तो उसे मास्टर स्लाइड पर जोड़ें.

लेआउट — लेआउट टेंप्लेट से यह तय होता है कि हर तरह की स्लाइड पर कॉन्टेंट को कैसे व्यवस्थित किया जाए. उदाहरण के लिए, अगर आपको अपनी सभी टाइटल स्लाइड को एक जैसा दिखाना है, तो टाइटल लेआउट टेंप्लेट में बदलाव करें.

दो और तरह के पेज होते हैं—नोट पेज और नोट मास्टर. ये ज़्यादातर प्रज़ेंटर के नोट के साथ काम करने के लिए काम के होते हैं.

एपीआई रिप्रज़ेंटेशन के टाइप और स्ट्रक्चर

इस सेक्शन में बताया गया है कि ऊपर बताए गए Google Slides के कॉन्सेप्ट मॉडल को Slides API में कैसे दिखाया जाता है.

नीचे दिए गए डायग्राम में, Slides API में टाइप के तौर पर प्रज़ेंटेशन, पेज, और पेज एलिमेंट के बीच का संबंध दिखाया गया है:

यहां दिए गए सेक्शन में बताया गया है कि इन टाइप को JSON में कैसे दिखाया जाता है.

प्रज़ेंटेशन

प्रज़ेंटेशन में कई प्रॉपर्टी और पेज शामिल होते हैं:

{
  "presentationId": string,
  "pageSize": { object(Size) },
  "slides": [ { object(Page) } ],
  "title": string,
  "masters": [ { object(Page) } ],
  "layouts": [ { object(Page) } ],
  "notesMaster": object(Page),
  "locale": string,
}

पेज

पेज में प्रॉपर्टी का एक सेट शामिल होता है. साथ ही, इसमें पेज के एलिमेंट भी शामिल होते हैं:

{
  "objectId": string,
  "pageType": enum(PageType),
  "pageElements": [ { object(PageElement) } ],
  "pageProperties": { object(PageProperties) },

  // Union field properties can be only one of the following:
  "slideProperties": { object(SlideProperties) },
  "layoutProperties": { object(LayoutProperties) },
  "notesProperties": { object(NotesProperties) },
  // End of list of possible types for union field properties.
}

पेज एलिमेंट

पेज एलिमेंट वे विज़ुअल कॉम्पोनेंट होते हैं जो पेजों पर मौजूद होते हैं. एपीआई में मौजूद पेज एलिमेंट में कई प्रॉपर्टी होती हैं. इनमें एक ऐसा फ़ील्ड भी शामिल होता है जो पेज एलिमेंट के टाइप के हिसाब से अलग-अलग होता है:

{
  "objectId": string,
  "size": { object(Size) },
  "transform": { object(AffineTransform) },
  "title": string,
  "description": string,

  // Union field element_kind can be only one of the following:
  "elementGroup": { object(Group) },
  "shape": { object(Shape) },
  "image": { object(Image) },
  "video": { object(Video) },
  "line": { object(Line) },
  "table": { object(Table) },
  "wordArt": { object(WordArt) },
  "sheetsChart": { object(SheetsChart) },
  // End of list of possible types for union field element_kind.
}

पेज एलिमेंट कई तरह के होते हैं. इनके बारे में ऊपर दी गई परिभाषा में, यूनियन फ़ील्ड element_kind में बताया गया है. इस तरह के पेज एलिमेंट के बारे में यहां दी गई टेबल में बताया गया है:

एलिमेंट का टाइप	ब्यौरा
ग्रुप	पेज एलिमेंट का एक सेट, जिसे एक अलग यूनिट के तौर पर माना जाता है. उन्हें एक साथ मूव किया जा सकता है, उनका साइज़ बदला जा सकता है, और उन्हें घुमाया जा सकता है.
आकार	एक सामान्य विज़ुअल ऑब्जेक्ट, जैसे कि रेक्टैंगल, एलिप्स, और टेक्स्ट बॉक्स. आकृतियों में टेक्स्ट शामिल हो सकता है. इसलिए, स्लाइड बनाने के लिए ये सबसे सामान्य पेज एलिमेंट हैं.
इमेज	Slides में इंपोर्ट किया गया ग्राफ़िक.
वीडियो	Slides में इंपोर्ट किया गया कोई वीडियो.
लाइन	कोई विज़ुअल लाइन, कर्व या कनेक्टर.
टेबल	कॉन्टेंट का ग्रिड.
WordArt	यह एक विज़ुअल टेक्स्ट एलिमेंट है, जो ज़्यादातर शेप की तरह काम करता है.
SheetsChart	Google Sheets से Slides में इंपोर्ट किया गया चार्ट.

पेज और पेज एलिमेंट की प्रॉपर्टी

Slides API की मदद से, अपने प्रज़ेंटेशन में पेजों और पेज एलिमेंट के दिखने के तरीके को पढ़ा और अपडेट किया जा सकता है. पेज के अलग-अलग एलिमेंट, अलग-अलग प्रॉपर्टी के साथ काम करते हैं. इनसे यह कंट्रोल किया जाता है कि पेज एलिमेंट को कैसे रेंडर किया जाए.

हर पेज एलिमेंट के लिए, उससे जुड़ी प्रॉपर्टी का एलिमेंट और प्रॉपर्टी अपडेट करने का मैसेज होता है. उदाहरण के लिए:

• पेज एलिमेंट का टाइप आकार है
• इसका प्रॉपर्टी फ़ील्ड shapeProperties है
• इन प्रॉपर्टी को अपडेट करने का अनुरोध UpdateShapePropertiesRequest है

हर पेज एलिमेंट टाइप के लिए, एलिमेंट/प्रॉपर्टी/अपडेट के अनुरोध का एक ही सेट मौजूद होता है: Image/imageProperties/UpdateImageProperties वगैरह.

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

प्रॉपर्टी के टाइप

Slides API में, कई तरह के ऑब्जेक्ट के बीच कुछ प्रॉपर्टी सामान्य होती हैं:

प्रॉपर्टी	ब्यौरा
रंग	Slides API में रंग, आरजीबी वैल्यू या थीम के रंग का रेफ़रंस हो सकते हैं. थीम के रंगों को नाम से रेफ़र किया जाता है. उदाहरण के लिए, "DARK1". इन्हें पेज की कलर स्कीम का इस्तेमाल करके, आरजीबी वैल्यू पर मैप किया जा सकता है. Slides एडिटर में प्रज़ेंटेशन की थीम बदलने पर, आम तौर पर यह कलर स्कीम अपडेट हो जाती है.
भरें	फ़िल, किसी ऑब्जेक्ट के अंदर खाली जगह को रेंडर करने की प्रोसेस को दिखाता है. Slides में सबसे ज़्यादा इस्तेमाल किया जाने वाला फ़िल, सॉलिड फ़िल है. इसमें किसी ऑब्जेक्ट के अंदरूनी हिस्से को एक ही सॉलिड कलर से भरा जाता है. पेजों के बैकग्राउंड के लिए भी फ़िल का इस्तेमाल किया जा सकता है.
आउटलाइन	आउटलाइन, पेज एलिमेंट के चारों ओर मौजूद लाइनों के सेट को दिखाती है. लाइनों के रंग को 'भरें' विकल्प से कंट्रोल किया जाता है. कॉल करने वाले लोग, आउटलाइन की चौड़ाई और डैश स्टाइल में भी बदलाव कर सकते हैं.
शैडो	शैडो, एक विज़ुअल इफ़ेक्ट है. इसका मकसद, ऑब्जेक्ट की परछाई को दिखाना है. फ़िलहाल, Slides API में शैडो सिर्फ़ रीड-ओनली मोड में उपलब्ध हैं.

प्रॉपर्टी अपडेट की जा रही हैं

किसी प्रॉपर्टी को अपडेट करने के लिए, batchUpdate कॉल में सही Update...Properties अनुरोध का इस्तेमाल करें. उदाहरण के लिए, आकृतियों के लिए UpdateShapeProperties. इन अनुरोधों में, प्रॉपर्टी का पूरा मैसेज स्वीकार किया जाता है. साथ ही, फ़ील्ड मास्क का इस्तेमाल करके यह तय किया जा सकता है कि प्रॉपर्टी के मैसेज में किन फ़ील्ड को अपडेट किया जाना चाहिए.

* के फ़ील्ड मास्क को वाइल्डकार्ड की तरह माना जाता है. साथ ही, यह किसी मैसेज में हर फ़ील्ड की जानकारी देने का शॉर्टहैंड है. अगर आने वाले समय में एपीआई को अपडेट किया जाता है, तो वाइल्डकार्ड सिंटैक्स से अनचाहे नतीजे मिल सकते हैं. ऐसा इसलिए, क्योंकि सिर्फ़ पढ़ने के लिए उपलब्ध फ़ील्ड और नए जोड़े गए फ़ील्ड की वजह से गड़बड़ियां हो सकती हैं. प्रोडक्शन ऐप्लिकेशन के लिए, हमेशा फ़ील्ड मास्क में अपडेट किए जा रहे खास फ़ील्ड की सूची बनाएं. साथ ही, * वाइल्डकार्ड का इस्तेमाल करने से बचें.

प्रॉपर्टी इनहेरिटेंस

कोई पेज या पेज एलिमेंट, अपने पैरंट ऑब्जेक्ट से प्रॉपर्टी इनहेरिट कर सकता है. किसी ऑब्जेक्ट की प्रॉपर्टी से यह तय होता है कि वह कैसा दिखेगा. इसमें वे प्रॉपर्टी भी शामिल होती हैं जो वह तय करता है और जो उसे इनहेरिट होती हैं.

• पेज प्रॉपर्टी — किसी पेज में ऐसी प्रॉपर्टी शामिल होती हैं जिन्हें वह तय नहीं करता. हालांकि, ये प्रॉपर्टी उस लेआउट या मास्टर में तय की जाती हैं जिस पर वह आधारित होता है.
• शेप की प्रॉपर्टी — किसी शेप को प्लेसहोल्डर के तौर पर मार्क किया जा सकता है. इससे, किसी दूसरे प्लेसहोल्डर शेप (पेज के पैरंट लेआउट या मास्टर पर) को साफ़ तौर पर रेफ़रंस के तौर पर इस्तेमाल किया जा सकता है. इससे प्रॉपर्टी इनहेरिट की जा सकती हैं.

इन आइडिया के बारे में, यहां दिए गए पैराग्राफ़ में ज़्यादा जानकारी दी गई है.

पेज की प्रॉपर्टी इनहेरिट करना

स्लाइड, लेआउट, और मास्टर का स्ट्रक्चर, प्रज़ेंटेशन में इनहेरिटेंस की हैरारकी तय करता है: स्लाइड, लेआउट से इनहेरिट करती हैं और लेआउट, मास्टर से इनहेरिट करते हैं. किसी स्लाइड का पैरंट लेआउट और मास्टर, स्लाइड के slideProperties फ़ील्ड में तय किए जाते हैं.

कोई पेज, पैरंट पेज से बैकग्राउंड और कलर स्कीम जैसी प्रॉपर्टी इनहेरिट कर सकता है. किसी प्रॉपर्टी को इनहेरिट करने के लिए, चाइल्ड पेज को अपने PageProperties मैसेज में उस प्रॉपर्टी के लिए कोई वैल्यू सेट नहीं करनी होती. पैरंट पेज से तय की गई वैल्यू को "बदलने" के बजाय, पेज इनहेरिट की गई वैल्यू को स्वीकार करता है.

यहां दिए गए डायग्राम में, एक ऐसी स्लाइड दिखाई गई है जो किसी लेआउट से प्रॉपर्टी इनहेरिट करती है. यह लेआउट, मास्टर से प्रॉपर्टी इनहेरिट करता है:

किसी स्लाइड को रेंडर करने के लिए इस्तेमाल की जाने वाली प्रॉपर्टी, उन प्रॉपर्टी का कॉम्बिनेशन होती हैं जिन्हें वह तय करती है और जिन्हें वह इनहेरिट करती है. इस उदाहरण में, स्लाइड 1 को रेंडर करने के लिए इस्तेमाल की गई वैल्यू इस तरह हैं:

• PropertyA की वैल्यू "Red" है.
• PropertyB "Orange" है.

जिस पेज का कोई पैरंट पेज नहीं होता है वह उन प्रॉपर्टी के लिए Google Slides से डिफ़ॉल्ट वैल्यू इनहेरिट करता है जिन्हें वह तय नहीं करता.

आकार की प्रॉपर्टी इनहेरिट करना

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

Slides एडिटर का इस्तेमाल करके प्लेसहोल्डर बनाए जा सकते हैं. हालांकि, Slides API का इस्तेमाल करके ऐसा नहीं किया जा सकता.

इनहेरिटेंस की इस हैरारकी के तय होने पर, चाइल्ड पेज किसी प्रॉपर्टी को इनहेरिट करता है. इसके लिए, वह अपने ShapeProperties मैसेज में उस वैल्यू को सेट नहीं करता. पैरंट शेप से तय की गई वैल्यू को ओवरराइड न करने पर, चाइल्ड शेप इनहेरिट की गई वैल्यू को स्वीकार करता है.

इस डायग्राम में, स्लाइड, लेआउट, और मास्टर में मौजूद तीन प्लेसहोल्डर के बीच प्रॉपर्टी के इनहेरिटेंस को दिखाया गया है:

प्लेसहोल्डर शेप को रेंडर करने के लिए इस्तेमाल की जाने वाली प्रॉपर्टी, उन प्रॉपर्टी का कॉम्बिनेशन होती हैं जिन्हें वह तय करता है और जिन्हें वह इनहेरिट करता है. इस उदाहरण में, इन आकृतियों के लिए रिज़ॉल्व की गई वैल्यू इस तरह हैं:

• Placeholder1: propertyA को "पीला" और propertyB को "हरा" के तौर पर रेंडर किया गया है.
• Placeholder2: propertyA को "पीला" और propertyB को "बैंगनी" के तौर पर रेंडर किया गया है.
• Placeholder3: propertyA को "पीला" और propertyB को "बैंगनी" के तौर पर रेंडर किया गया है.

आकार ही पेज एलिमेंट का ऐसा टाइप है जिसमें पैरंट एलिमेंट हो सकते हैं. इमेज, टेबल, और चार्ट जैसे अन्य टाइप, प्लेसहोल्डर नहीं हो सकते और उनके पैरंट नहीं हो सकते.

जब किसी शेप का कोई पैरंट नहीं होता, तो जो वैल्यू सेट नहीं की जाती हैं वे ऐप्लिकेशन की डिफ़ॉल्ट वैल्यू से अपने-आप भर जाती हैं.

PropertyState का इस्तेमाल करके प्रॉपर्टी "छिपाना"

PropertyState एन्यूमरेशन यह कंट्रोल करता है कि किसी शेप की प्रॉपर्टी का इस्तेमाल असल में रेंडरिंग के लिए किया जाता है या वैल्यू का इस्तेमाल सिर्फ़ चाइल्ड शेप के इनहेरिटेंस के लिए किया जाता है. प्रॉपर्टी की स्थिति NOT_RENDERED वाली प्रॉपर्टी का इस्तेमाल, उसके पेज पर शेप को रेंडर करते समय नहीं किया जाएगा. हालांकि, जिन चाइल्ड प्रॉपर्टी की प्रॉपर्टी की स्थिति RENDERED है वे अब भी इस प्रॉपर्टी को इनहेरिट कर सकती हैं.

किसी प्रॉपर्टी को अपडेट करने पर, उसकी स्थिति अपने-आप `RENDERED` पर सेट हो जाती है. हालांकि, अगर आपने उसी अनुरोध में स्थिति को किसी दूसरी वैल्यू पर सेट किया है, तो ऐसा नहीं होगा.

नीचे दिए गए डायग्राम में, PropertyState फ़ील्ड में बदलाव करने वाले तीन प्लेसहोल्डर के बीच प्रॉपर्टी के इनहेरिटेंस को दिखाया गया है:

PropertyState फ़ील्ड की वजह से, शेप की प्रॉपर्टी की रेंडरिंग पर असर पड़ सकता है. इस उदाहरण में, इन आकृतियों के लिए हल की गई वैल्यू इस तरह हैं:

• Placeholder1: propertyA को "लाल" के तौर पर रेंडर किया जाता है.
• Placeholder2: propertyA को रेंडर नहीं किया गया है. अगर यह आउटलाइन प्रॉपर्टी होती, तो Placeholder2 में कोई आउटलाइन नहीं होती.
• Placeholder3: propertyA को रेंडर नहीं किया गया है.

PropertyState एन्यूमरेशन की एक और वैल्यू हो सकती है: INHERIT प्रॉपर्टी स्टेट का मतलब है कि प्रॉपर्टी स्टेट को इनहेरिट किया गया है और पैरंट की वैल्यू का इस्तेमाल किया जाना चाहिए. जिन शेप की कोई पैरंट प्रॉपर्टी नहीं होती उनकी प्रॉपर्टी की स्थिति INHERIT नहीं हो सकती.