Saran pelengkapan otomatis untuk input teks

Widget Input Teks memungkinkan add-on Anda membaca dan bereaksi terhadap teks yang diberikan pengguna. Anda dapat mengonfigurasi widget ini untuk memberikan saran otomatis kepada pengguna untuk teks input.

Saran yang diberikan dapat berasal dari daftar string statis yang Anda berikan. Atau, Anda dapat membuat saran dari konteks, seperti teks yang telah diketik pengguna ke dalam widget.

Mengonfigurasi saran

Untuk mengonfigurasi saran input teks, Anda hanya perlu melakukan hal berikut:

  • Buat daftar saran berdasarkan:
    • Membuat daftar statis, dan/atau
    • Menentukan tindakan dengan fungsi callback yang membuat daftar tersebut secara dinamis dari konteks.
  • Lampirkan daftar saran dan/atau tindakan ke widget input teks.

Jika Anda memberikan daftar saran dan tindakan statis, UI aplikasi akan menggunakan daftar statis hingga pengguna mulai memasukkan karakter, lalu fungsi callback digunakan dan daftar statis diabaikan.

Saran statis

Untuk menawarkan daftar saran statis, Anda hanya perlu melakukan hal berikut:

  1. Buat objek Suggestions.
  2. Tambahkan setiap saran statis ke dalamnya menggunakan addSuggestion() atau addSuggestions().
  3. Lampirkan objek Suggestions ke widget menggunakan TextInput.setSuggestions().

UI menampilkan saran statis sesuai urutan penambahannya. UI juga otomatis melakukan pencocokan awalan yang tidak peka huruf besar/kecil dan memfilter daftar saran saat pengguna mengetik karakter ke dalam widget.

Tindakan saran

Jika tidak menggunakan daftar saran statis, Anda harus menentukan tindakan untuk membuat saran secara dinamis. Anda dapat melakukan hal ini dengan mengikuti langkah-langkah berikut:

  1. Buat objek Action dan kaitkan dengan fungsi callback yang Anda tentukan.
  2. Panggil fungsi TextInput.setSuggestionsAction() widget, yang menyediakan objek Action.
  3. Terapkan fungsi callback untuk membuat daftar saran dan menampilkan objek SuggestionsResponse yang dibuat.

UI memanggil fungsi callback setiap kali pengguna mengetik karakter ke dalam input teks, tetapi hanya setelah pengguna berhenti mengetik untuk sesaat. Fungsi callback menerima objek peristiwa yang berisi informasi tentang widget kartu yang terbuka. Lihat Objek peristiwa tindakan untuk mengetahui detailnya.

Fungsi callback harus menampilkan objek SuggestionsResponse yang valid yang berisi daftar saran untuk ditampilkan. UI menampilkan saran sesuai urutan penambahannya. Tidak seperti daftar statis, UI tidak melakukan pemfilteran otomatis saran callback berdasarkan input pengguna. Jika ingin memiliki pemfilteran tersebut, Anda harus membaca nilai input teks dari objek peristiwa dan memfilter saran saat membuat daftar.

Contoh

Cuplikan kode add-on Google Workspace berikut menunjukkan cara mengonfigurasi saran di dua widget input teks yang berbeda, yang pertama dengan daftar statis dan yang kedua menggunakan fungsi callback:

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

Saran dan OnChangeAction()

Widget input teks dapat memiliki fungsi pengendali setOnChangeAction() yang ditentukan yang dieksekusi setiap kali widget kehilangan fokus. Jika pengendali dan saran ini diaktifkan untuk input teks yang sama, aturan berikut akan menentukan perilaku interaksi input teks:

  1. Pengendali setOnChangeAction() dieksekusi setelah saran dipilih.
  2. Jika pengguna menekan Enter (atau membuat input teks kehilangan fokus) tanpa mengubah saran yang dipilih, setOnChangeAction() tidak akan dipicu lagi.
  3. setOnChangeAction() akan dipicu lagi jika pengguna, setelah memilih saran, mengeditnya sehingga tidak lagi cocok dengan saran apa pun dalam daftar.
  4. Jika pengguna tidak memilih saran, setOnChangeAction() akan terpicu saat input teks kehilangan fokus.