Metin girişleri için otomatik tamamlama önerileri

Metin Girişi widget'ı, eklentinizin kullanıcıların sağladığı metinleri okuyup bunlara tepki vermesini sağlar. Bu widget'ları, kullanıcılara giriş metni için otomatik öneriler sunacak şekilde yapılandırabilirsiniz.

Sağlanan öneriler, sizin sağladığınız statik bir dizeler listesinden gelebilir. Alternatif olarak, önerileri bağlama göre de oluşturabilirsiniz. Örneğin, kullanıcının widget'a yazdığı metin gibi.

Önerileri yapılandırma

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

• Aşağıdaki yöntemlerle öneri listesi oluşturabilirsiniz:
  • Statik liste oluşturma ve/veya
  • Bu listeyi bağlamdan dinamik olarak oluşturan bir geri çağırma işleviyle eylem tanımlama.
• Öneri 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. Bu noktada 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. Suggestions nesnesi oluşturun.
2. addSuggestion() veya addSuggestions() kullanarak her statik öneriyi ekleyin.
3. Suggestions nesnesini TextInput.setSuggestions() kullanarak widget'a ekleyin.

Kullanıcı arayüzünde statik öneriler, eklendikleri sırayla gösterilir. Kullanıcı arayüzü, büyük/küçük harfe duyarsız önek eşleştirme işlemini de otomatik olarak gerçekleştirir ve kullanıcı widget'a karakter yazdıkça ö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. Bir Action nesnesi oluşturun ve bunu tanımladığınız bir geri çağırma işleviyle ilişkilendirin.
2. TextInput.setSuggestionsAction() işlevini çağırın ve 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ı arayüzü, kullanıcı metin girişine bir karakter yazdığında geri çağırma işlevini çağırır ancak yalnızca kullanıcının bir an için yazmayı bırakmasından sonra ç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österilecek öneri listesini içeren geçerli bir SuggestionsResponse nesnesi döndürmelidir. Kullanıcı arayüzünde öneriler, eklendikleri sırayla gösterilir. Statik listelerin aksine, kullanıcı arayüzü, kullanıcı girişine göre geri çağırma önerilerini otomatik olarak filtrelemez. Bu tür bir filtreleme yapmak istiyorsanız etkinlik nesnesinden metin girişi değerini okumanız ve listeyi oluştururken önerilerinizi filtrelemeniz gerekir.

Örnek

Aşağıdaki Google Workspace eklentisi kod snippet'i, iki farklı metin girişi widget'ında önerilerin nasıl yapılandırılacağını gösterir. Bunlardan ilki statik bir liste, ikincisi ise geri çağırma işlevi kullanı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 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 odak kaybedildiğinde yürütülen bir setOnChangeAction() işleyici işlevi tanımlanabilir. Bu işleyici ve öneriler aynı metin girişi için etkinleştirilmişse metin girişi etkileşimi davranışını aşağıdaki kurallar tanımlar:

1. setOnChangeAction() işleyici, bir öneri seçildikten sonra yürütülür.
2. Kullanıcı, seçili öneriyi değiştirmeden Enter tuşuna basarsa (veya metin girişinin odağını başka bir şekilde kaybederse) setOnChangeAction() tekrar tetiklenmez.
3. setOnChangeAction(), kullanıcı bir öneriyi seçtikten sonra listedeki önerilerle eşleşmeyecek şekilde düzenlerse tekrar tetiklenir.
4. Kullanıcı bir öneri seçmezse setOnChangeAction(), metin girişi odağını kaybettiğinde tetiklenir.