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

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

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

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

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

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

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

پیشنهادات ثابت

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

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

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

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

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

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

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

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

مثال

قطعه کد افزونه 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() فعال می شود.