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

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

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

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

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

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

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

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

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

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