Saran pelengkapan otomatis untuk input teks

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Widget Input Teks memungkinkan add-on Anda membaca dan bereaksi terhadap teks yang diberikan pengguna. Anda dapat mengonfigurasi widget ini agar 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

Mengonfigurasi saran untuk input teks hanya mengharuskan Anda melakukan hal berikut:

  • Buat daftar saran dengan:
    • 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 statis saran dan tindakan, UI aplikasi akan menggunakan daftar statis hingga pengguna mulai memasukkan karakter, yang pada saat itu fungsi callback akan digunakan dan daftar statis akan diabaikan.

Saran statis

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

  1. Buat objek Suggestions.
  2. Tambahkan setiap saran statis ke saran tersebut 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. Implementasikan fungsi callback untuk membuat daftar saran dan menampilkan objek SuggestionsResponse yang di-build.

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

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

Contoh

Cuplikan kode add-on Google Workspace berikut menunjukkan cara mengonfigurasi saran pada 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 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!
 }

Saran dan OnChangeAction()

Widget input teks dapat memiliki fungsi pengendali setOnChangeAction() yang ditentukan dan 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 memicu lagi.
  3. setOnChangeAction() dipicu lagi jika pengguna, setelah memilih saran, mengeditnya sehingga tidak lagi cocok dengan saran dalam daftar.
  4. Jika pengguna tidak memilih saran, setOnChangeAction() akan terpicu saat input teks kehilangan fokus.