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

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

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

הגדרת ההצעות

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

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

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

הצעות סטטיות

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

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

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

פעולות בהצעות

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

1. יוצרים אובייקט Action ומשייכים אותו לפונקציית קריאה חוזרת שאתם מגדירים.
2. קוראים לפונקציה TextInput.setSuggestionsAction() של הווידג'ט ומספקים לה את האובייקט Action.
3. מטמיעים את פונקציית הקריאה החוזרת כדי ליצור את רשימת ההצעות ולהחזיר אובייקט SuggestionsResponse שנוצר.

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

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

דוגמה

קטע הקוד הבא של תוסף Google Workspace מראה איך להגדיר הצעות בשני ווידג'טים שונים של קלט טקסט, הראשון עם רשימה סטטית והשני באמצעות פונקציית קריאה חוזרת (callback):

// 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() מופעל כשהמיקוד בטקסט מפסיק.