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

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 Editor में प्रज़ेंटेशन की थीम बदलने पर, इस कलर स्कीम को आम तौर पर अपडेट किया जाता है.
भरें	फ़िल, किसी ऑब्जेक्ट के अंदर की खाली जगह को रेंडर करने के लिए होता है. Slides में, सबसे ज़्यादा इस्तेमाल किया जाने वाला फ़िल, सॉलिड फ़िल होता है. इसमें किसी ऑब्जेक्ट के अंदर एक ही रंग भरा जाता है. पेजों के बैकग्राउंड के लिए भी फ़िल का इस्तेमाल किया जा सकता है.
आउटलाइन	आउटलाइन, पेज तत्व को घेरने वाली लाइनों के सेट को दिखाती है. लाइनों के रंग को फ़िल से कंट्रोल किया जाता है. कॉल करने वाले लोग, आउटलाइन की चौड़ाई और डैश स्टाइल में भी बदलाव कर सकते हैं.
शैडो	शैडो, एक विज़ुअल इफ़ेक्ट है. इसका मकसद, ऑब्जेक्ट की वजह से पड़ने वाली असली शैडो की नकल करना है. फ़िलहाल, Slides API में शैडो सिर्फ़ पढ़ने के लिए उपलब्ध हैं.

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

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

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

का इस्तेमाल न करें.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Placeholder1: propertyA को "Yellow" और propertyB को "Green" के तौर पर रेंडर किया गया है.
• Placeholder2: propertyA को "Yellow" और propertyB को "Purple" के तौर पर रेंडर किया जाता है.
• Placeholder3: propertyA को "Yellow" और propertyB को "Purple" के तौर पर रेंडर किया जाता है.

पेज तत्व में सिर्फ़ शेप के पैरंट हो सकते हैं. इमेज, टेबल, और चार्ट जैसे अन्य टाइप, प्लेसहोल्डर नहीं हो सकते. साथ ही, इनके पैरंट नहीं हो सकते.

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

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

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

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

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

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

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

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