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

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

ज़्यादातर मामलों में, Google 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

के जवाब में अपने कार्ड को सही तरीके से न दिखाए.

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

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

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

Google Workspace के होस्ट ऐप्लिकेशन के लिए उपलब्ध कार्रवाइयां

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

• Calendar में की गई कार्रवाइयाँ
• Chat से जुड़ी कार्रवाइयां
• कार्रवाइयों को बढ़ावा देना
• Gmail में की गई कार्रवाइयां
• संपादक की कार्रवाइयाँ

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

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

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

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

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

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

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