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

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

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

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

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

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

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

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

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

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

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