Membuat kartu interaktif

Sebagian besar add-on, selain menyajikan data, mengharuskan pengguna memasukkan informasi. Saat membuat add-on berbasis kartu, Anda dapat menggunakan widget interaktif seperti tombol, item menu toolbar, atau kotak centang untuk meminta data yang dibutuhkan add-on atau menyediakan kontrol interaksi lainnya.

Menambahkan tindakan ke widget

Sebagian besar, Anda membuat widget interaktif dengan menautkannya ke tindakan tertentu dan menerapkan perilaku yang diperlukan dalam fungsi callback. Lihat tindakan add-on untuk mengetahui detailnya.

Dalam sebagian besar kasus, Anda dapat mengikuti prosedur umum ini untuk mengonfigurasi widget agar melakukan tindakan tertentu saat dipilih atau diperbarui:

  1. Buat objek Action, dengan menentukan fungsi callback yang harus dijalankan, beserta parameter yang diperlukan.
  2. Tautkan widget ke Action dengan memanggil fungsi pengendali widget yang sesuai.
  3. Terapkan fungsi callback untuk menerapkan perilaku yang diperlukan.

Contoh

Contoh berikut menetapkan tombol yang menampilkan notifikasi pengguna setelah diklik. Klik memicu fungsi callback notifyUser() dengan argumen yang menentukan teks notifikasi. Menampilkan ActionResponse yang dibuat akan menghasilkan notifikasi yang ditampilkan.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText))
        .build();      // Don't forget to build the response!
  }

Mendesain interaksi yang efektif

Saat mendesain kartu interaktif, perhatikan hal-hal berikut:

  • Widget interaktif biasanya memerlukan setidaknya satu metode pengendali untuk menentukan perilakunya.

  • Gunakan fungsi handler widget setOpenLink() saat Anda memiliki URL dan hanya ingin membukanya di tab. Hal ini menghindari kebutuhan untuk menentukan objek Action dan fungsi callback. Jika Anda perlu membuat URL terlebih dahulu, atau melakukan langkah-langkah tambahan lainnya sebelum membuka URL, tentukan Action dan gunakan setOnClickOpenLinkAction() sebagai gantinya.

  • Saat menggunakan fungsi handler widget setOpenLink() atau setOnClickOpenLinkAction(), Anda harus memberikan objek OpenLink untuk menentukan URL mana yang akan dibuka. Anda juga dapat menggunakan objek ini untuk menentukan perilaku membuka dan menutup menggunakan enum OpenAs dan OnClose.

  • Lebih dari satu widget dapat menggunakan objek Action yang sama. Namun, Anda perlu menentukan objek Action yang berbeda jika ingin memberikan parameter yang berbeda untuk fungsi callback.

  • Buat fungsi callback Anda tetap sederhana. Agar add-on tetap responsif, layanan Card membatasi fungsi callback hingga maksimum 30 detik waktu eksekusi. Jika eksekusi memerlukan waktu lebih lama dari itu, UI add-on Anda mungkin tidak memperbarui tampilan kartunya dengan benar sebagai respons terhadap Action .

  • Jika status data di backend pihak ketiga berubah sebagai akibat dari interaksi pengguna dengan UI add-on Anda, sebaiknya add-on menetapkan bit 'status berubah' ke true sehingga cache sisi klien yang ada akan dihapus. Lihat deskripsi metode ActionResponseBuilder.setStateChanged() untuk mengetahui detail tambahan.