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

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

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

कॉलबैक फ़ंक्शन

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

के जवाब में अपने कार्ड को ठीक से डिसप्ले न कर पाए.

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

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

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

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

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

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

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

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

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