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

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

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

הגדרת ההצעות

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

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

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

הצעות סטטיות

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

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

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

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

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

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

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

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

דוגמה

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

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