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

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

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

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

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

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

किसी विजेट को किसी खास 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 फ़ंक्शन होते हैं. इसलिए, इन्हें ऐसे किसी भी काम के लिए कहा जा सकता है जो कोई भी अन्य स्क्रिप्ट फ़ंक्शन कर सकता है.

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

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

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

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

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

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

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

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