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

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

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

ضبط الاقتراحات

لضبط ميزة "الاقتراحات" في حقل إدخال نص، ما عليك سوى تنفيذ الخطوات التالية:

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

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

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

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

1. أنشئ عنصر Suggestions.
2. أضِف كل اقتراح ثابت إليه باستخدام addSuggestion() أو addSuggestions().
3. إرفاق العنصر Suggestions بالتطبيق المصغّر باستخدام TextInput.setSuggestions()

تعرِض واجهة المستخدم الاقتراحات الثابتة بالترتيب الذي تمت إضافتها به. يُجري واجهة المستخدم أيضًا مطابقة تلقائية للبادئة غير الحسّاسة لحالة الأحرف، كما تصفّل قائمة الاقتراحات عندما يكتب المستخدم أحرفًا في التطبيق المصغّر.

الإجراءات المقترَحة

إذا كنت لا تستخدِم قائمة اقتراحات ثابتة، عليك تحديد إجراء لإنشاء اقتراحاتك بشكل ديناميكي. ويمكنك إجراء ذلك باتّباع الخطوات التالية:

1. أنشئ عنصر Action واربطه بدالة رد اتصال تحدّدها.
2. استخدِم الدالة TextInput.setSuggestionsAction() للأداة المصغّرة، مع توفير العنصر Action.
3. نفِّذ دالة ردّ الاتصال لإنشاء قائمة الاقتراحات وإرجاع كائن SuggestionsResponse مُنشئ.

تستدعي واجهة المستخدم وظيفة طلب معاودة الاتصال كلما كتب المستخدم حرفًا في ملف إدخال النص، ولكن بعد أن يتوقف المستخدم عن الكتابة لبعض الوقت فقط. تتلقّى دالة callbackعنصر حدث يحتوي على معلومات عن التطبيقات المصغّرة للبطاقة المفتوحة. اطّلِع على عناصر أحداث الإجراءات للحصول على التفاصيل.

يجب أن تعرِض وظيفة ردّ الاتصال عنصرًا صالحًا 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() عندما يفقد إدخال النص التركيز.