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

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

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

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

لا تتطلب تهيئة الاقتراحات لإدخال نص سوى إجراء ما يلي:

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

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

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

لتقديم قائمة ثابتة بالاقتراحات، عليك فقط إجراء ما يلي:

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