Membuat kartu interaktif

Sebagian besar add-on, selain menampilkan data, mengharuskan pengguna untuk memasukkan tidak akurat atau tidak sesuai. Saat membuat add-on berbasis kartu, Anda dapat menggunakan widget interaktif seperti tombol, item menu toolbar, atau kotak centang untuk meminta data dari add-on atau menyediakan kontrol interaksi lainnya.

Menambahkan tindakan ke widget

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

Pada umumnya, Anda dapat mengikuti prosedur umum ini untuk mengonfigurasi widget untuk mengambil tindakan tertentu saat dipilih atau diperbarui:

1. Buat objek Action, menetapkan fungsi callback yang harus dieksekusi, beserta parameter yang diperlukan.
2. Tautkan widget ke Action dengan memanggil metode fungsi pengendali widget.
3. Mengimplementasikan 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 menetapkan teks notifikasi. Mengembalikan build ActionResponse 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!
  }

Merancang interaksi yang efektif

Saat mendesain kartu interaktif, ingatlah hal berikut:

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

• Menggunakan widget setOpenLink() fungsi handler jika Anda memiliki URL dan hanya ingin membukanya di tab. Hal ini menghindari kebutuhan untuk mendefinisikan Objek dan callback Action . Jika Anda perlu membuat URL terlebih dahulu, atau mengambil resource tambahan langkah sebelum membuka URL, tentukan Action dan gunakan setOnClickOpenLinkAction() sebagai gantinya.

• Saat menggunakan setOpenLink() atau setOnClickOpenLinkAction() fungsi pengendali widget, Anda harus menyediakan OpenLink untuk menentukan URL yang akan dibuka. Anda juga bisa menggunakan objek ini untuk menentukan perilaku pembukaan dan penutupan menggunakan OpenAs dan enum OnClose.

• Lebih dari satu widget dapat menggunakan jenis Objek Action. Namun, Anda perlu mendefinisikan Objek Action jika Anda menginginkannya untuk memberikan parameter berbeda kepada fungsi callback.

• Buat fungsi callback Anda tetap sederhana. Agar add-on tetap responsif, Layanan kartu membatasi fungsi callback hingga maksimum 30 detik serta waktu eksekusinya. Jika eksekusi memakan waktu lebih lama dari itu, UI add-on Anda mungkin tidak memperbarui tampilan kartunya dengan benar sebagai tanggapan terhadap Action .

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