اقتراحات الإكمال التلقائي لإدخال النصوص

تتيح أداة إدخال النص للإضافة قراءة النص الذي يقدّمه المستخدمون والتفاعل معه. يمكنك ضبط هذه التطبيقات المصغّرة لتقديم اقتراحات تلقائية للمستخدمين بشأن نص الإدخال.

يمكن أن تأتي الاقتراحات المقدَّمة من قائمة ثابتة من السلاسل التي توفّرها. بدلاً من ذلك، يمكنك إنشاء اقتراحات استنادًا إلى السياق، مثل النص الذي كتبه المستخدم في الأداة من قبل.

إعداد الاقتراحات

يتطلب إعداد الاقتراحات لإدخال النص ما يلي فقط:

  • يمكنك إنشاء قائمة اقتراحات حسب:
    • إنشاء قائمة ثابتة و/أو
    • يُحدِّد إجراء باستخدام دالة استدعاء تُنشئ هذه القائمة ديناميكيًا من السياق.
  • إرفاق قائمة الاقتراحات و/أو الإجراء بأداة إدخال النص

وفي حال تقديم قائمة ثابتة من الاقتراحات والإجراء، ستستخدم واجهة مستخدم التطبيق القائمة الثابتة إلى أن يبدأ المستخدم في إدخال الأحرف، حيث يتم استخدام دالة الاستدعاء ويتم تجاهل القائمة الثابتة.

الاقتراحات الثابتة

لتقديم قائمة ثابتة من الاقتراحات، ما عليك سوى تنفيذ ما يلي:

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

يمكن أن تحتوي التطبيقات المصغّرة لإدخال النص على وظيفة معالج setOnChangeAction() محددة يتم تنفيذها كلما فقدت الأداة التركيز. إذا تم تفعيل كل من هذا المعالج والاقتراحات لإدخال النص نفسه، تحدِّد القواعد التالية سلوك تفاعل إدخال النص:

  1. يتم تنفيذ معالج setOnChangeAction() بعد اختيار اقتراح.
  2. إذا ضغط المستخدم على مفتاح Enter (أو جعل الإدخال النصي يفقد التركيز) بدون تعديل الاقتراح المحدّد، لن يتم تشغيل setOnChangeAction() مرة أخرى.
  3. يتم تشغيل setOnChangeAction() مرة أخرى إذا أجرى المستخدم تعديلاً بعد اختيار اقتراح لكي لا يتطابق مع أي من الاقتراحات الواردة في القائمة.
  4. إذا لم يختَر المستخدم اقتراحًا، سيتم تشغيل setOnChangeAction() عندما يفقد الإدخال النصي التركيز.