Metin girişleri için otomatik tamamlama önerileri

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

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

Önerileri yapılandırma

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

• Aşağıdaki ölçütlere göre bir öneri listesi oluşturun:
  • Statik liste oluşturma ve/veya
  • Bu listeyi bağlamdan dinamik olarak oluşturan bir geri çağırma işleviyle işlem tanımlayın.
• Ö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 kullanıcı karakter girmeye başlayana kadar uygulama kullanıcı arayüzü statik listeyi kullanır. Sonrasında 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 statik öneriyi addSuggestion() veya addSuggestions() kullanarak ekleyin.
3. Suggestions nesnesini TextInput.setSuggestions() kullanarak widget'a ekleyin.

Kullanıcı arayüzünde statik öneriler eklendikleri sırayla gösterilir. Ayrıca kullanıcı arayüzü, büyük/küçük harfe duyarlı olmayan ön ek eşleştirmeyi otomatik olarak gerçekleştirir ve kullanıcı widget'a karakter 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. Bunu aşağıdaki adımları uygulayarak yapabilirsiniz:

1. Bir Action nesnesi oluşturun ve bunu 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 nesnesini döndürmek için geri çağırma işlevini uygulayın.

Kullanıcı metin girişine bir karakter yazdıklarında, ancak bunun için kullanıcı bir süre yazmayı durdurduktan 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 bilgiler 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örüntüler. Kullanıcı arayüzü, statik listelerin aksine geri çağırma önerilerini kullanıcı girişine göre otomatik olarak filtrelemez. Bu tür bir filtrelemenin olmasını 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 bir liste, ikincisi geri çağırma işlevi kullanan 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ının, odağı kaybettiğinde yürütülecek bir setOnChangeAction() işleyici işlevi tanımlanmış olabilir. Bu işleyici ve önerilerin her ikisi de aynı metin girişi için etkinleştirilmişse 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 öneride değişiklik yapmadan Enter tuşuna basarsa (veya başka bir şekilde metin girişinin odağı kaybetmesine neden olursa) setOnChangeAction() tekrar tetiklenmez.
3. Kullanıcı bir öneriyi seçtikten sonra öneriyi listedeki önerilerden hiçbiriyle eşleşmeyecek şekilde düzenlerse setOnChangeAction() tekrar tetiklenir.
4. Kullanıcı bir öneri seçmezse metin girişinin odağı kaybolduğunda setOnChangeAction() tetiklenir.