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

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

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

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

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

ध्यान दें: CardAction ऑब्जेक्ट के साथ Action मैच न करें. 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 Card service कॉल-टू-ऐक्शन को ज़्यादा से ज़्यादा 30 सेकंड तक चलने के लिए सीमित करती है. अगर स्क्रिप्ट एक्ज़ीक्यूट होने के समय से ज़्यादा समय लेती है, तो हो सकता है कि ऐड-ऑन यूज़र इंटरफ़ेस (यूआई) Action के हिसाब से अपना कार्ड डिसप्ले ठीक से अपडेट न करे.

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

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

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

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

• कैलेंडर कार्रवाइयां
• कार्रवाई करना
• Gmail की कार्रवाइयां
• एडिटर की कार्रवाइयां

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

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

कार्रवाई इवेंट ऑब्जेक्ट

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

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

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

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