پیشنهادات تکمیل خودکار برای ورودی متن

ویجت ورودی متن به افزونه شما اجازه می‌دهد متنی را که کاربران ارائه می‌دهند بخواند و به آن واکنش نشان دهد. می‌توانید این ویجت‌ها را طوری پیکربندی کنید که به طور خودکار پیشنهادهایی برای متن ورودی به کاربران ارائه دهند.

پیشنهادهای ارائه شده می‌توانند از یک لیست ثابت از رشته‌هایی که شما ارائه می‌دهید، باشند. همچنین می‌توانید پیشنهادها را از متن، مانند متنی که کاربر قبلاً در ویجت تایپ کرده است، بسازید.

پیکربندی پیشنهادات

پیکربندی پیشنهادها برای ورودی متن فقط مستلزم انجام موارد زیر است:

• ایجاد فهرستی از پیشنهادات بر اساس:
  • ایجاد یک لیست استاتیک، و/یا
  • تعریف یک اکشن با یک تابع فراخوانی که آن لیست را به صورت پویا از متن می‌سازد.
• لیست پیشنهادات و/یا اقدام را به ویجت ورودی متن پیوست کنید.

اگر هم یک لیست استاتیک از پیشنهادات و هم یک عمل ارائه دهید، رابط کاربری برنامه تا زمانی که کاربر شروع به وارد کردن کاراکترها نکند، از لیست استاتیک استفاده می‌کند، در این صورت از تابع فراخوانی استفاده می‌شود و لیست استاتیک نادیده گرفته می‌شود.

پیشنهادات استاتیک

برای ارائه یک لیست ثابت از پیشنهادات، فقط باید موارد زیر را انجام دهید:

1. یک شیء Suggestions ایجاد کنید.
2. هر پیشنهاد استاتیک را با استفاده از addSuggestion() یا addSuggestions() به آن اضافه کنید.
3. شیء Suggestions را با استفاده از TextInput.setSuggestions() به ویجت متصل کنید.

رابط کاربری، پیشنهادهای ثابت را به ترتیبی که اضافه شده‌اند نمایش می‌دهد. رابط کاربری همچنین به‌طور خودکار تطبیق پیشوند بدون حساسیت به حروف بزرگ و کوچک را انجام می‌دهد و فهرست پیشنهادها را همزمان با تایپ کاراکترها توسط کاربر در ویجت، فیلتر می‌کند.

اقدامات پیشنهادی

اگر از لیست پیشنهادات استاتیک استفاده نمی‌کنید، باید یک اکشن برای ساخت پیشنهادات خود به صورت پویا تعریف کنید. می‌توانید این کار را با دنبال کردن مراحل زیر انجام دهید:

1. یک شیء Action ایجاد کنید و آن را با یک تابع فراخوانی که تعریف می‌کنید، مرتبط کنید.
2. تابع TextInput.setSuggestionsAction() ویجت را فراخوانی کنید و شیء Action را به آن ارائه دهید.
3. تابع فراخوانی (callback) را برای ساخت لیست پیشنهادات پیاده‌سازی کنید و یک شیء SuggestionsResponse ساخته شده را برگردانید.

رابط کاربری هر زمان که کاربر کاراکتری را در ورودی متن تایپ کند، تابع فراخوانی را فراخوانی می‌کند، اما تنها پس از اینکه کاربر برای لحظه‌ای تایپ را متوقف کرد. تابع فراخوانی یک شیء رویداد حاوی اطلاعات مربوط به ابزارک‌های کارت باز را دریافت می‌کند. برای جزئیات بیشتر به اشیاء رویداد Action مراجعه کنید.

تابع فراخوانی باید یک شیء 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() تعریف کنند که هر زمان ویجت فوکوس را از دست می‌دهد، اجرا می‌شود. اگر این کنترل‌کننده و پیشنهادات هر دو برای یک ورودی متن فعال باشند، قوانین زیر رفتار تعاملی ورودی متن را تعریف می‌کنند:

1. تابع setOnChangeAction() پس از انتخاب یک پیشنهاد، اجرا می‌شود.
2. اگر کاربر بدون تغییر پیشنهاد انتخاب شده، کلید Enter را فشار دهد (یا به هر نحو دیگری باعث شود ورودی متن از فوکوس خارج شود)، setOnChangeAction() دوباره اجرا نمی‌شود.
3. اگر کاربر پس از انتخاب یک پیشنهاد، آن را طوری ویرایش کند که دیگر با هیچ یک از پیشنهادهای موجود در لیست مطابقت نداشته باشد، setOnChangeAction() دوباره فعال می‌شود.
4. اگر کاربر پیشنهادی را انتخاب نکند، setOnChangeAction() زمانی که ورودی متن فوکوس را از دست می‌دهد، فعال می‌شود.