השלמה אוטומטית של הצעות להזנת טקסט

הווידג'ט קלט טקסט מאפשרת לתוסף לקרוא טקסט שהמשתמשים מספקים ולהגיב עליו. אפשר להגדיר את הווידג'טים האלה כדי לספק למשתמשים הצעות אוטומטיות של טקסט הקלט.

ההצעות יכולות להגיע מרשימה סטטית של מחרוזות שאתם מספקים. אפשרות אחרת היא ליצור את ההצעות מתוך ההקשר, כמו הטקסט המשתמש כבר הקליד בווידג'ט.

הגדרת ההצעות

כדי להגדיר הצעות לקלט טקסט, צריך רק לבצע הבאים:

• יצירת רשימת הצעות לפי:
  • יצירת רשימה סטטית ו/או
  • הגדרת פעולה עם פונקציית קריאה חוזרת שיוצרת את הרשימה באופן דינמי מההקשר.
• מצרפים את רשימת ההצעות או את הפעולה לווידג'ט של קלט הטקסט.

אם אתם מציגים גם רשימה סטטית של הצעות וגם פעולה, בממשק המשתמש של האפליקציה משתמש ברשימה הסטטית עד שהמשתמש מתחיל להזין תווים, שבו נעשה שימוש בפונקציית הקריאה החוזרת ומתעלמים מהרשימה הסטטית.

הצעות סטטיות

כדי להציע רשימה סטטית של הצעות, צריך רק לבצע את הפעולות הבאות:

1. יצירת Suggestions לאובייקט.
2. מוסיפים לה כל הצעה סטטית באמצעות addSuggestion() או addSuggestions().
3. צריך לצרף את Suggestions לווידג'ט באמצעות TextInput.setSuggestions().

בממשק המשתמש מוצגות ההצעות הסטטיות לפי הסדר שבו הן נוספו. ממשק המשתמש וגם מבצע באופן אוטומטי התאמת קידומת לא תלוית-רישיות ומסננת את את רשימת ההצעות בזמן שהמשתמש מקליד תווים בווידג'ט.

פעולות להצעה

אם אתם לא משתמשים ברשימת הצעות סטטית, עליכם להגדיר פעולה כדי לבנות את ההצעות שלכם באופן דינמי. כדי לעשות זאת:

1. יצירת אובייקט Action ולשייך אותו לפונקציית קריאה חוזרת שאתם מגדירים.
2. קוראים לווידג'ט 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() פונקציית handler שמוגדרת ומופעלת בכל פעם שהווידג'ט מאבד את המיקוד. אם גם ה-handler וגם ההצעות האלה מופעלים עבור אותו קלט טקסט, המאפיין הכללים הבאים מגדירים את התנהגות האינטראקציה של קלט טקסט:

1. ה-handler של setOnChangeAction() יופעל אחרי שבוחרים הצעה.
2. אם המשתמש מקיש על Enter (או גורם לכך שקלט הטקסט יאבד) בלי לשנות את ההצעה שנבחרה, setOnChangeAction() לא להפעיל אותו שוב.
3. setOnChangeAction() כן יופעל שוב אם המשתמש, לאחר בחירה הצעה, עורך אותה כך שלא יתאים יותר לאף אחת מההצעות ברשימה.
4. אם המשתמש לא בוחר הצעה, setOnChangeAction() מפעיל כשקלט הטקסט מאבד את המיקוד.