Saran pelengkapan otomatis untuk input teks

Widget Input Teks memungkinkan add-on Anda membaca dan bereaksi terhadap teks yang diberikan pengguna. Anda dapat konfigurasikan widget ini guna 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 pengguna sudah mengetiknya di dalam widget.

Mengonfigurasi saran

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

  • 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 saran dan tindakan statis, UI aplikasi menggunakan daftar statis hingga pengguna mulai memasukkan karakter, ketika fungsi callback akan digunakan dan daftar statis diabaikan.

Saran statis

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

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

UI menampilkan saran statis sesuai urutan penambahannya. UI juga secara otomatis melakukan pencocokan awalan yang 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 Anda secara dinamis. Anda dapat melakukan hal ini dengan mengikuti langkah-langkah berikut:

  1. Membuat objek Action dan mengaitkannya dengan fungsi callback yang Anda tentukan.
  2. Panggil TextInput.setSuggestionsAction() widget , dengan memberikan Action .
  3. Implementasikan fungsi callback untuk membangun daftar saran dan menampilkan SuggestionsResponse bawaan .

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

Fungsi callback harus menampilkan nilai yang valid SuggestionsResponse yang berisi daftar saran untuk ditampilkan. UI menampilkan saran sesuai urutan penambahannya. Tidak seperti daftar statis, UI melakukan tidak melakukan pemfilteran otomatis terhadap saran callback berdasarkan pengguna input teks. Jika ingin memiliki pemfilteran tersebut, Anda harus membaca nilai input teks dari objek peristiwa dan memfilter saran saat Anda membuat 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 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 setOnChangeAction() fungsi pengendali yang ditentukan yang dijalankan setiap kali widget kehilangan fokus. Jika pengendali dan saran ini diaktifkan untuk input teks yang sama, aturan berikut 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 dipicu lagi.
  3. setOnChangeAction() akan terpicu lagi jika pengguna, setelah memilih saran, edit agar tidak lagi cocok dengan saran yang ada dalam daftar.
  4. Jika pengguna tidak memilih saran, setOnChangeAction() akan terpicu saat input teks kehilangan fokus.