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

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

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

הגדרת ההצעות

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

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

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

הצעות סטטיות

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

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()

לווידג'טים של קלט טקסט אפשר להגדיר את פונקציית ה-handler setOnChangeAction(), שמופעלת בכל פעם שהווידג'ט מאבד את המיקוד. אם גם ה-handler וגם ההצעות האלה מופעלים עבור אותו קלט טקסט, הכללים הבאים מגדירים את התנהגות האינטראקציה של קלט הטקסט:

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