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

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

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

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

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

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

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

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

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

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