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

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

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

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

لا يتطلّب ضبط الاقتراحات لإدخال نص سوى اتّباع الخطوات التالية:

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

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

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

لعرض قائمة ثابتة بالاقتراحات، عليك اتّباع الخطوات التالية فقط:

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() عندما يفقد إدخال النص التركيز.