Metin girişleri için otomatik tamamlama önerileri

Metin Giriş widget'ı, eklentinizin kullanıcıların sağladığı metni okumasına ve buna tepki vermesine olanak tanır. Bu widget'ları, kullanıcılara giriş metni için otomatik öneriler sunacak şekilde yapılandırabilirsiniz.

Sağlanan öneriler, sağladığınız statik bir dize listesinden gelebilir. Alternatif olarak, önerileri bağlama göre de oluşturabilirsiniz (ör. kullanıcının widget'a daha önce yazdığı metin).

Önerileri yapılandırma

Metin girişi için önerileri yapılandırmak için aşağıdakileri yapmanız yeterlidir:

• Aşağıdaki ölçütlere göre öneri listesi oluşturma:
  • Statik liste oluşturma ve/veya
  • Bu listeyi bağlama göre dinamik olarak oluşturan bir geri çağırma işleviyle bir işlem tanımlayabilirsiniz.
• Öneriler listesini ve/veya işlemi metin girişi widget'ına ekleyin.

Hem statik bir öneri listesi hem de bir işlem sağlarsanız uygulama kullanıcı arayüzü, kullanıcı karakter girmeye başlayana kadar statik listeyi kullanır. Ardından geri çağırma işlevi kullanılır ve statik liste yoksayılır.

Statik öneriler

Statik bir öneri listesi sunmak için yapmanız gerekenler:

1. Bir Suggestions nesnesi oluşturun.
2. Her statik öneriyi addSuggestion() veya addSuggestions() kullanarak buraya ekleyin.
3. TextInput.setSuggestions() simgesini kullanarak Suggestions nesneyi widget'a ekleyin.

Kullanıcı arayüzü, statik önerileri eklendikleri sırayla gösterir. Kullanıcı arayüzü, büyük/küçük harf duyarlı olmayan ön ek eşleştirmeyi de otomatik olarak gerçekleştirir ve kullanıcı widget'a karakterler yazarken öneri listesini filtreler.

Öneri işlemleri

Statik bir öneri listesi kullanmıyorsanız önerilerinizi dinamik olarak oluşturmak için bir işlem tanımlamanız gerekir. Bunun için aşağıdaki adımları uygulayabilirsiniz:

1. Bir Action nesnesi oluşturun ve bu nesneyi tanımladığınız bir geri çağırma işleviyle ilişkilendirin.
2. Widget'ın TextInput.setSuggestionsAction() işlevini çağırarak Action nesnesini sağlayın.
3. Öneri listesini oluşturmak ve oluşturulmuş bir SuggestionsResponse nesnesi döndürmek için geri çağırma işlevini uygulayın.

Kullanıcı metin girişine bir karakter yazdığında kullanıcı arayüzü geri çağırma işlevini çağırır ancak yalnızca kullanıcı bir süre yazmayı bıraktıktan sonra. Geri çağırma işlevi, açık kartın widget'ları hakkında bilgi içeren bir etkinlik nesnesi alır. Ayrıntılar için İşlem etkinliği nesneleri bölümüne bakın.

Geri çağırma işlevi, görüntülenecek önerilerin listesini içeren geçerli bir SuggestionsResponse nesnesi döndürmelidir. Kullanıcı arayüzü, önerileri eklendikleri sırayla gösterir. Statik listelerin aksine kullanıcı arayüzü, kullanıcı girişine göre geri arama önerilerini otomatik olarak filtrelemez. Bu tür bir filtreleme yapmak istiyorsanız etkinlik nesnesinden metin giriş değerini okumanız ve listeyi oluştururken önerilerinizi filtrelemeniz gerekir.

Örnek

Aşağıdaki Google Workspace eklentisi kod snippet'inde, iki farklı metin girişi widget'ında önerilerin nasıl yapılandırılacağı gösterilmektedir. Bunlardan ilki statik bir listeyle, ikincisi ise geri çağırma işlevi kullanılarak yapılandırılmıştır:

// 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 
 *  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!
 }

Öneriler ve OnChangeAction()

Metin girişi widget'larında, widget odağını kaybettiğinde çalıştırılan bir setOnChangeAction() işleyici işlevi tanımlanabilir. Bu işleyici ve öneriler aynı metin girişi için etkinleştirildiyse metin girişi etkileşim davranışı aşağıdaki kurallarla tanımlanır:

1. setOnChangeAction() işleyicisi, bir öneri seçildikten sonra çalışır.
2. Kullanıcı, seçili öneriyi değiştirmeden Enter tuşuna basarsa (veya başka bir şekilde metin girişinin odağını kaybederse) setOnChangeAction() tekrar tetiklenmez.
3. Kullanıcı bir öneriyi seçtikten sonra, öneriyi artık listedeki önerilerden hiçbiriyle eşleşmeyecek şekilde düzenlerse setOnChangeAction() yeniden tetiklenir.
4. Kullanıcı bir öneri seçmezse metin girişi odağı kaybettiğinde setOnChangeAction() tetiklenir.