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

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

ज़्यादातर मामलों में, Apps Script की कार्ड सेवा से मिले Action ऑब्जेक्ट का इस्तेमाल करके, ऐड-ऑन ऐक्शन तय किए जा सकते हैं. हर 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
अन्य कार्रवाइयां	Nothing

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

• Calendar में की जाने वाली कार्रवाइयां
• कार्रवाइयां बढ़ाना
• Gmail से जुड़ी कार्रवाइयां
• एडिटर की कार्रवाइयां

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

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

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

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

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

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

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