टेक्स्ट इनपुट के लिए, अपने-आप पूरा होने वाले सुझाव

टेक्स्ट इनपुट विजेट की मदद से, आपका ऐड-ऑन उस टेक्स्ट को पढ़कर उस पर प्रतिक्रिया देता है जो उपयोगकर्ता उपलब्ध कराते हैं. इन विजेट को कॉन्फ़िगर करके, उपयोगकर्ताओं को इनपुट टेक्स्ट के लिए अपने-आप सुझाव दिए जा सकते हैं.

दिए जाने वाले सुझाव, आपके दिए गए स्ट्रिंग की स्टैटिक सूची से मिल सकते हैं. वैकल्पिक रूप से, आप संदर्भ से सुझाव बना सकते हैं, जैसे कि वह टेक्स्ट जो उपयोगकर्ता ने पहले ही विजेट में टाइप कर दिया है.

सुझाव कॉन्फ़िगर किए जा रहे हैं

टेक्स्ट इनपुट के सुझावों को कॉन्फ़िगर करने के लिए, सिर्फ़ ये काम करने ज़रूरी होते हैं:

  • सुझावों की एक सूची बनाएं:
    • स्टैटिक सूची बनाना और/या
    • कॉलबैक फ़ंक्शन से कार्रवाई को तय करना, जो संदर्भ से डाइनैमिक तौर पर सूची बनाता है.
  • टेक्स्ट की सूची के विजेट के साथ, सुझावों की सूची और/या कार्रवाई अटैच करें.

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

स्टैटिक सुझाव

सुझावों की स्टैटिक सूची देने के लिए, आपको सिर्फ़ ये काम करने होंगे:

  1. Suggestions ऑब्जेक्ट बनाएं.
  2. हर स्टैटिक सुझाव को addSuggestion() या addSuggestions() का इस्तेमाल करके जोड़ें.
  3. विजेट को TextInput.setSuggestions() का इस्तेमाल करके Suggestions ऑब्जेक्ट से जोड़ें.

यूज़र इंटरफ़ेस (यूआई) उस क्रम में स्टैटिक सुझाव दिखाता है जिसमें उन्हें जोड़ा गया था. यूज़र इंटरफ़ेस (यूआई) में भी केस-इनसेंसिटिव प्रीफ़िक्स मैच होते हैं. साथ ही, सुझाव की सूची को फ़िल्टर करता है, ताकि उपयोगकर्ता विजेट में वर्णों को टाइप कर सके.

कार्रवाइयों के सुझाव

अगर आप स्टैटिक सुझाव सूची का इस्तेमाल नहीं कर रहे हैं, तो आपको अपने सुझाव डाइनैमिक तौर पर बनाने के लिए कोई कार्रवाई तय करनी होगी. ऐसा करने के लिए, आप ये कदम उठा सकते हैं:

  1. एक Action ऑब्जेक्ट बनाएं और इसे एक कॉलबैक फ़ंक्शन से जोड़ें.
  2. विजेट को कॉल करें's TextInput.setSuggestionsAction() फ़ंक्शन को उपलब्ध कराना, Action ऑब्जेक्ट.
  3. कॉलबैक फ़ंक्शन लागू करके, सुझाव की सूची बनाएं और बनाया गया SuggestionsResponse ऑब्जेक्ट दिखाएं.

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

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

उदाहरण

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

// Create an input with a static suggestion list.
var textInput1 = CardService.newTextInput()
    .setFieldName('colorInput')
    .setTitle('Color choice')
    .setSuggestions(CardService.newSuggestions()
        .addSuggestion('Red')
        .addSuggestion('Yellow')
        .addSuggestions(['Blue', 'Black', 'Green']));

// Create an input with a dynamic suggestion list.
var action = CardService.newAction()
    .setFunctionName('refreshSuggestions');
var textInput2 = CardService.newTextInput()
    .setFieldName('emailInput')
    .setTitle('Email')
    .setSuggestionsAction(action);

// ...

/**
 *  Build and return a suggestion response. In this case, the suggestions
 *  are a list of emails taken from the To: and CC: lists of the open
 *  message in Gmail, filtered by the text that the user has already
 *  entered. This method assumes the Google Workspace
 *  add-on extends Gmail; the add-on only calls this method for cards
 *  displayed when the user has entered a message context.
 *
 *  @param {Object} e the event object containing data associated with
 *      this text input widget.
 *  @return {SuggestionsResponse}
 */
 function refreshSuggestions(e) {
   // Activate temporary Gmail scopes, in this case so that the
   // open message metadata can be read.
   var accessToken = e.gmail.accessToken;
   GmailApp.setCurrentMessageAccessToken(accessToken);

   var userInput = e && e.formInput['emailInput'].toLowerCase();
   var messageId = e.gmail.messageId;
   var message = GmailApp.getMessageById(messageId);

   // Combine the comma-separated returned by these methods.
   var addresses = message.getTo() + ',' + message.getCc();

   // Filter the address list to those containing the text the user
   // has already entered.
   var suggestionList = [];
   addresses.split(',').forEach(function(email) {
     if (email.toLowerCase().indexOf(userInput) !== -1) {
       suggestionList.push(email);
     }
   });
   suggestionList.sort();

   return CardService.newSuggestionsResponseBuilder()
       .setSuggestions(CardService.newSuggestions()
           .addSuggestions(suggestionList))
       .build();  // Don't forget to build the response!
 }

सुझाव और OnChangeAction()

टेक्स्ट इनपुट विजेट में setOnChangeAction() फ़ंक्शन फ़ंक्शन तय किया जा सकता है, जो विजेट के फ़ोकस खोने पर, एक्ज़ीक्यूट हो जाता है. अगर इस हैंडलर और सुझावों, दोनों को एक ही टेक्स्ट इनपुट के लिए चालू किया जाता है, तो नीचे दिए गए नियम, टेक्स्ट इनपुट इंटरैक्शन के व्यवहार के बारे में बताते हैं:

  1. किसी सुझाव को चुनने के बाद, setOnChangeAction() हैंडलर लागू होता है.
  2. अगर उपयोगकर्ता Enter दबाएं (या ऐसा करने पर, टेक्स्ट इनपुट फ़ोकस खो देता है), तो चुने गए सुझाव में बदलाव किए बिना setOnChangeAction() फिर से ट्रिगर नहीं करता.
  3. अगर setOnChangeAction() किसी सुझाव को चुनने के बाद, उपयोगकर्ता में बदलाव करता है, तो वह सूची में दिए गए किसी भी सुझाव से मिलता-जुलता नहीं रहेगा.
  4. अगर उपयोगकर्ता कोई सुझाव नहीं चुनता है, तो टेक्स्ट इनपुट में फ़ोकस खोने पर setOnChangeAction() ट्रिगर होता है.