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

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

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

הגדרת ההצעות

כדי להגדיר הצעות לקלט טקסט, נדרשים רק:

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

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

הצעות סטטיות

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

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