Metin girişleri için otomatik tamamlama önerileri

Metin Girişi widget'ı eklentinizin, kullanıcıların sağladığı metinleri okumasını ve bunlara tepki vermesini sağlar. Şunları yapabilirsiniz: kullanıcılara otomatik öneriler sağlayacak şekilde giriş metni.

Sağlanan öneriler, sağladığınız dizelerden oluşan statik bir listeden alınabilir. Alternatif olarak önerileri bağlamdan (örneğin, kullanıcı widget'a zaten yazmıştır.

Önerileri yapılandırma

Metin girişi için önerileri yapılandırmak üzere yalnızca şunları yapmanız gerekir: takip etmek için:

• Aşağıdaki ölçütlere göre öneri listesi oluşturun:
  • Statik liste oluşturma ve/veya
  • Şununla bir eylem tanımlamak bağlamdan dinamik bir şekilde liste oluşturan bir geri çağırma işlevi.
• 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ı karakterleri girmeye başlayana kadar statik listeyi kullanır. bunun 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 oluşturun nesnesini tanımlayın.
2. Her statik öneriyi addSuggestion() kullanarak ona ekleyin veya addSuggestions().
3. Suggestions nesneye eklemek için TextInput.setSuggestions() kullanın.

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 bir öneri listesi oluşturur.

Öneri işlemleri

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

1. Action nesnesi oluşturma ve bunu bir geri çağırma işleviyle ilişkilendirme her şeyi kapsıyor.
2. Widget'ın TextInput.setSuggestionsAction() numarasını ara işlevini kullanarak Action nesnesini tanımlayın.
3. Öneri listesini oluşturmak ve geri çağırma işlevini kullanmak için geri çağırma işlevini uygulayın oluşturulmuş bir SuggestionsResponse nesnesini tanımlayın.

Kullanıcı metin girişi, yalnızca kullanıcı kısa bir süre yazmayı bıraktıktan sonra. İlgili içeriği oluşturmak için kullanılan geri çağırma işlevi, alan hakkında bilgi içeren bir etkinlik nesnesi kartın widget'larını açın. Görüntüleyin İşlem etkinliği nesneleri inceleyebilirsiniz.

Geri çağırma işlevi, SuggestionsResponse görüntülenecek önerilerin listesini içeren nesne. Kullanıcı arayüzü, önerileri eklendi. Statik listelerden farklı olarak kullanıcı arayüzü kullanıcıya göre geri arama önerilerinde otomatik olarak filtre uygulamamalıdır giriş. Bu tür bir filtreleme uygulamak istiyorsanız, metin giriş değerini okumanız gerekir. kaldırın ve listeyi oluştururken önerilerinizi filtreleyin.

Örnek

Aşağıdaki Google Workspace eklentisi kod snippet'i önerilerin nasıl yapılandırılacağını gösterir iki farklı metin girişi widget'ında bulunuyor. Birincisi statik liste, diğeri ise ikincisi için geri çağırma işlevi kullanılı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 setOnChangeAction() işleyici işlevi tanımlıdır. Bu işlev, widget odağı kaybettiğinde yürütülür. Bu işleyici ve önerilerin her ikisi de 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ı Enter tuşuna basarsa (veya metin girişinin odağı kaybetmesine neden olursa) setOnChangeAction(), seçilen öneriyi değiştirmeden tekrar tetikleyin.
3. Kullanıcı bir seçim yaptıktan sonra setOnChangeAction() işlemini tekrar önerinin artık hiçbir öneriyle eşleşmeyecek şekilde düzenlenmesini sağlar görünür.
4. Kullanıcı bir öneri seçmezse setOnChangeAction() tetiklenir metin girişi odağı kaybolduğunda.