Metin girişleri için otomatik tamamlama önerileri

Metin Girişi widget'ı, eklentinizin kullanıcıların gönderdiği metinleri okumasına ve tepki vermesine olanak tanır. Bu widget'ları, kullanıcılara girilen metin için otomatik öneriler sağlayacak şekilde yapılandırabilirsiniz.

Sağlanan öneriler, sağladığınız dizelerden oluşan statik bir listeden alınabilir. Alternatif olarak, önerileri bağlamdan (kullanıcının widget'a yazdığı metin gibi) oluşturabilirsiniz.

Önerileri yapılandırma

Metin girişi için önerileri yapılandırmak üzere yalnızca aşağıdakileri yapmanız gerekir:

• Aşağıdakileri yaparak bir öneri listesi oluşturun:
  • Statik liste oluşturma ve/veya
  • Bağlamdan dinamik olarak liste oluşturan bir geri çağırma işleviyle eylem tanımlama.
• Metin girişi widget'ına öneri listesini ve/veya eylemi 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. Bu işlemin 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 yalnızca aşağıdakileri yapmanız gerekir:

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

Kullanıcı arayüzü, statik önerileri eklendikleri sırayla görüntüler. Kullanıcı arayüzü, büyük/küçük harfe 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 ö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. 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 için geri çağırma işlevini uygulayın ve derleme SuggestionsResponse nesnesini döndürün.

Kullanıcı metin girişine bir karakter yazdığında, ancak yalnızca bir süre yazmayı bıraktıktan sonra kullanıcı arayüzü geri çağırma işlevini çağırır. 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 listelerden farklı olarak kullanıcı arayüzü, geri çağırma önerileri için kullanıcı girişine göre otomatik filtreleme yapmaz. Bu tür bir filtreleme uygulamak istiyorsanız etkinlik nesnesindeki metin giriş değerini okumanız ve listeyi oluştururken önerilerinizi filtrelemeniz gerekir.

Örnek

Aşağıdaki Google Workspace Eklentisi kod snippet'inde, ilki statik liste, ikincisi ise geri çağırma işlevi olmak üzere iki farklı metin girişi widget'ında önerilerin nasıl yapılandırılacağı gösterilmektedir:

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

Öneriler ve OnChangeAction()

Metin girişi widget'larında, widget odağı kaybolduğunda yürütülen bir setOnChangeAction() işleyici işlevi bulunabilir. Hem bu işleyici hem de öneriler aynı metin girişi için etkinleştirilirse aşağıdaki kurallar metin girişi etkileşim davranışını tanımlar:

1. setOnChangeAction() işleyici bir öneri seçildikten sonra yürütülür.
2. Kullanıcı seçilen öneriyi değiştirmeden Enter tuşuna basarsa (veya metin girişinin odağı kaybetmesine neden olursa) setOnChangeAction() bir daha tetiklenmez.
3. Kullanıcı bir öneriyi seçtikten sonra öneriyi artık listedeki önerilerin hiçbiriyle eşleşmeyecek şekilde düzenlerse setOnChangeAction() tekrar tetiklenir.
4. Kullanıcı bir öneri seçmezse metin girişi odağı kaybedildiğinde setOnChangeAction() tetiklenir.