ऐड-ऑन कार्रवाइयां

ऐड-ऑन कार्रवाइयां विजेट के लिए इंटरैक्टिव व्यवहार देती हैं. कार्रवाई बनाकर, यह तय किया जाता है कि जब उपयोगकर्ता किसी विजेट को चुनता है या उसे अपडेट करता है, तो क्या होता है.

ज़्यादातर मामलों में, Action Apps Script कार्ड सेवा से मिले ऑब्जेक्ट का इस्तेमाल करके, ऐड-ऑन ऐक्शन तय किए जा सकते हैं. जब किसी Action को बनाया जाता है, तो वह कॉलबैक फ़ंक्शन से जुड़ा होता है. उपयोगकर्ता के विजेट से इंटरैक्ट करने पर, मनमुताबिक कार्रवाई करने के लिए कॉलबैक फ़ंक्शन लागू किया जाता है. आपको सही विजेट हैंडलर फ़ंक्शन का इस्तेमाल करके, Action को विजेट से भी लिंक करना होगा. इससे पता चलेगा कि Action कॉलबैक किस तरह का इंटरैक्शन ट्रिगर करता है.

इस सामान्य प्रोसेस का इस्तेमाल करके, Action के साथ एक विजेट को कॉन्फ़िगर करें:

1. कॉलबैक फ़ंक्शन के बारे में बताते हुए, Action ऑब्जेक्ट बनाएं कि इसे ज़रूरी पैरामीटर के साथ काम करना चाहिए.
2. विजेट पर, Action ऑब्जेक्ट का इस्तेमाल करके, सही विजेट हैंडलर फ़ंक्शन को कॉल करें.
3. ज़रूरी व्यवहार लागू करने के लिए, कॉलबैक फ़ंक्शन लागू करें.

ध्यान दें: Action ऑब्जेक्ट और CardAction ऑब्जेक्ट के बीच भ्रम की स्थिति पैदा न करें. CardAction ऑब्जेक्ट, कार्ड हेडर मेन्यू आइटम होते हैं, जबकि Action ऑब्जेक्ट, यूज़र इंटरफ़ेस (यूआई) के साथ उपयोगकर्ता के इंटरैक्शन पर जवाब तय करते हैं.

विजेट हैंडलर के फ़ंक्शन

विजेट को किसी खास Action या दूसरे व्यवहार से लिंक करने के लिए, विजेट हैंडलर फ़ंक्शन का इस्तेमाल करें. हैंडलर फ़ंक्शन तय करता है कि किस तरह का इंटरैक्शन (उदाहरण के लिए, विजेट पर क्लिक करना या किसी टेक्स्ट फ़ील्ड में बदलाव करना) ऐक्शन व्यवहार को ट्रिगर करता है. हैंडलर फ़ंक्शन यह भी तय करता है कि कार्रवाई पूरी होने के बाद, यूज़र इंटरफ़ेस (यूआई) कौनसे कदम उठाता है.

नीचे दी गई टेबल में विजेट के लिए अलग-अलग तरह के हैंडलर शामिल किए गए हैं. साथ ही, यह भी बताया गया है कि वे किस विजेट के साथ इस्तेमाल किए जाते हैं:

हैंडलर फ़ंक्शन	कार्रवाई को ट्रिगर करती है	लागू होने वाले विजेट	ब्यौरा
setOnChangeAction()	विजेट की वैल्यू बदल जाएगी	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	विजेट के फ़ोकस बंद होने पर, Action सेट करता है जो Apps Script फ़ंक्शन को चालू करता है. उदाहरण के लिए, जब उपयोगकर्ता किसी इनपुट में टेक्स्ट डालता है और Enter दबाता है. हैंडलर अपने-आप एक इवेंट ऑब्जेक्ट को उस फ़ंक्शन में पास कर देता है जिसे वह कॉल करता है. अगर आप चाहें, तो इस इवेंट ऑब्जेक्ट में पैरामीटर की ज़्यादा जानकारी भी डाली जा सकती है.
setOnClickAction()	उपयोगकर्ता, विजेट पर क्लिक करता है	CardAction Image ImageButton DecoratedText TextButton	यह नीति एक ऐसा Action सेट करती है जो उपयोगकर्ता के विजेट पर क्लिक करने के बाद Apps Script फ़ंक्शन को एक्ज़ीक्यूट करता है. हैंडलर अपने-आप एक इवेंट ऑब्जेक्ट को उस फ़ंक्शन में पास कर देता है जिसे वह कॉल करता है. इस इवेंट ऑब्जेक्ट में, पैरामीटर की वैकल्पिक जानकारी इंसर्ट की जा सकती है.
setComposeAction()	उपयोगकर्ता, विजेट पर क्लिक करता है	CardAction Image ImageButton DecoratedText TextButton	Gmail के लिए खास. एक Action सेट करता है, जो ईमेल ड्राफ़्ट बनाता है. इसके बाद, उस ड्राफ़्ट को Gmail के यूज़र इंटरफ़ेस (यूआई) की कंपोज़ विंडो में उपयोगकर्ता को दिखाता है. यह ड्राफ़्ट, नए मैसेज के तौर पर या Gmail में खुले हुए मैसेज के जवाब के तौर पर बनाया जा सकता है. जब हैंडलर ड्राफ़्ट-बिल्डिंग कॉलबैक फ़ंक्शन को कॉल करता है, तब यह कॉलबैक फ़ंक्शन में एक इवेंट ऑब्जेक्ट पास करता है. ज़्यादा जानकारी के लिए, ड्राफ़्ट मैसेज लिखना देखें.
setOnClickOpenLinkAction()	उपयोगकर्ता, विजेट पर क्लिक करता है	CardAction Image ImageButton DecoratedText TextButton	जब उपयोगकर्ता विजेट पर क्लिक करता है, तब यूआरएल खोलने के लिए, Action सेट करता है. इस हैंडलर का इस्तेमाल तब करें, जब आपको यूआरएल बनाना हो या लिंक खुलने से पहले अन्य कार्रवाइयां की जानी चाहिए. वरना, आम तौर पर setOpenLink() का इस्तेमाल करना ज़्यादा आसान होता है. यूआरएल को सिर्फ़ नई विंडो में खोला जा सकता है. बंद होने पर, आपके पास यूज़र इंटरफ़ेस (यूआई) से ऐड-ऑन को फिर से लोड करने का विकल्प होता है.
setOpenLink()	उपयोगकर्ता, विजेट पर क्लिक करता है	CardAction Image ImageButton DecoratedText TextButton	जब उपयोगकर्ता विजेट पर क्लिक करता है, तो सीधे यूआरएल खोलता है. इस हैंडलर का इस्तेमाल तब करें, जब आपको यूआरएल पता हो और उसे सिर्फ़ खोलने की ज़रूरत हो. अगर ऐसा नहीं है, तो setOnClickOpenLinkAction() का इस्तेमाल करें. यूआरएल को नई विंडो या ओवरले में खोला जा सकता है. बंद होने पर, यूज़र इंटरफ़ेस (यूआई) से ऐड-ऑन को फिर से लोड किया जा सकता है.
setSuggestionsAction()	उपयोगकर्ता किसी इनपुट में टेक्स्ट डालता है	TextInput	यह Action सेट करता है, जो तब Apps Script फ़ंक्शन को काम करता है, जब उपयोगकर्ता किसी टेक्स्ट इनपुट विजेट में टेक्स्ट डालता है. हैंडलर अपने-आप एक इवेंट ऑब्जेक्ट को उस फ़ंक्शन में पास कर देता है जिसे वह कॉल करता है. ज़्यादा जानकारी के लिए, टेक्स्ट इनपुट के लिए अपने-आप पूरे होने वाले सुझाव देखें.

कॉलबैक फ़ंक्शन

Action ट्रिगर होने पर, कॉलबैक फ़ंक्शन काम करते हैं. कॉलबैक फ़ंक्शन Apps Script फ़ंक्शन होते हैं. इसलिए, दूसरे स्क्रिप्ट फ़ंक्शन में जो भी काम किया जा सकता है, वे करीब-करीब सभी तरह के काम कर सकते हैं.

चेतावनी: Apps Script कार्ड सेवा कॉलबैक फ़ंक्शन को ज़्यादा से ज़्यादा 30 सेकंड तक सीमित करती है. अगर कार्रवाई होने में इससे ज़्यादा समय लगता है, तो हो सकता है कि आपका ऐड-ऑन यूज़र इंटरफ़ेस (यूआई), Action के जवाब में अपने कार्ड को ठीक से अपडेट न कर पाए.

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

इस टेबल से पता चलता है कि आपके कॉलबैक फ़ंक्शन को खास कार्रवाइयों के लिए, खास रिस्पॉन्स ऑब्जेक्ट कब दिखाना चाहिए. ये कार्रवाइयां, ऐड-ऑन के ज़रिए उपलब्ध कराए गए खास होस्ट ऐप्लिकेशन पर निर्भर नहीं करती हैं:

कार्रवाई की कोशिश की गई	कॉलबैक फ़ंक्शन को वापस आना चाहिए
कार्ड के बीच नेविगेट करना	ActionResponse
Notification दिखाएं	ActionResponse
setOnClickOpenLinkAction() का इस्तेमाल करके लिंक खोलें	ActionResponse
अपने-आप पूरा होने वाले सुझाव दिखाना	SuggestionResponse
यूनिवर्सल ऐक्शन का इस्तेमाल करें	UniversalActionResponse
अन्य कार्रवाइयां	कुछ भी नहीं

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

• कैलेंडर ऐक्शन
• Drive पर की जाने वाली कार्रवाइयां
• Gmail की कार्रवाइयां
• एडिटर की कार्रवाइयां

ध्यान दें: रिस्पॉन्स बिल्डर क्लास का इस्तेमाल करते समय, रिस्पॉन्स ऑब्जेक्ट बनाने के लिए, build() को कॉल ज़रूर करें. ऐसा न करने पर गड़बड़ी हो सकती है.

ध्यान दें: प्रोजेक्ट मेनिफ़ेस्ट में यूनिवर्सल ऐक्शन के बारे में बताया जाता है और इनके लिए Action ऑब्जेक्ट की ज़रूरत नहीं होती है. हालांकि, उनके कॉलबैक फ़ंक्शन को एक UniversalActionResponse दिखाना ज़रूरी है.

ऐक्शन इवेंट ऑब्जेक्ट

जब आपका ऐड-ऑन, किसी Action को ट्रिगर करता है, तब यूज़र इंटरफ़ेस (यूआई) अपने-आप एक JSON इवेंट ऑब्जेक्ट बनाता है और उसे Action कॉलबैक फ़ंक्शन में एक आर्ग्युमेंट के तौर पर पास करता है. इस इवेंट ऑब्जेक्ट में उपयोगकर्ता के मौजूदा क्लाइंट-साइड कॉन्टेक्स्ट के बारे में जानकारी होती है, जैसे कि दिखाए गए कार्ड में मौजूद सभी इंटरैक्टिव विजेट की मौजूदा वैल्यू.

ऐक्शन इवेंट ऑब्जेक्ट में एक खास JSON स्ट्रक्चर होता है. यह उनमें शामिल जानकारी को व्यवस्थित करता है. जब कोई होम पेज ट्रिगर होता है, तो होम पेज बनाने के लिए इसी स्ट्रक्चर का इस्तेमाल किया जाता है. इसके अलावा, ऐसा तब भी होता है, जब ऐड-ऑन डिसप्ले को अपडेट करने के लिए, संदर्भ के हिसाब से ट्रिगर चालू होता है.

इवेंट ऑब्जेक्ट स्ट्रक्चर की पूरी जानकारी के लिए, इवेंट ऑब्जेक्ट देखें.

ध्यान दें: Gmail ऐड-ऑन में, इवेंट ऑब्जेक्ट के इस स्ट्रक्चर के आसान वर्शन का इस्तेमाल किया जाता था. हालांकि, अब इसका इस्तेमाल नहीं किया जाता. पुराने सिस्टम के साथ काम करने की सुविधा के लिए, Gmail के सभी मूल ऐड-ऑन इवेंट ऑब्जेक्ट फ़ील्ड अब भी नए इवेंट ऑब्जेक्ट स्ट्रक्चर में शामिल हैं (इवेंट ऑब्जेक्ट स्ट्रक्चर देखें). हालांकि, उसी जानकारी को सामान्य इवेंट और Gmail इवेंट ऑब्जेक्ट सबस्ट्रक्चर में फिर से दिखाया जाता है. अगर Gmail ऐड-ऑन को Google Workspace ऐड-ऑन में अपग्रेड किया जा रहा है, तो अपडेट किए गए इवेंट ऑब्जेक्ट फ़ील्ड का इस्तेमाल करने के लिए, आपको अपने कोड में बदलाव करना होगा. ऐसा करने पर, Gmail इवेंट के ओरिजनल ऑब्जेक्ट फ़ील्ड हटा दिए जाएंगे.