Navigasi kartu

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

Sebagian besar add-on berbasis kartu dibuat menggunakan beberapa kartu yang mewakili 'halaman' berbeda dari antarmuka add-on. Untuk memiliki pengalaman pengguna yang efektif, Anda harus menggunakan navigasi yang sederhana dan alami antar-kartu di add-on.

Awalnya di add-on Gmail, transisi antara kartu UI yang berbeda ditangani dengan mendorong dan memunculkan kartu ke dan dari satu tumpukan kartu, dengan kartu teratas stack ditampilkan oleh Gmail.

Navigasi kartu halaman beranda

Google Workspace Add-on memperkenalkan halaman beranda dan kartu non-kontekstual. Untuk mengakomodasi kartu kontekstual dan non-kontekstual, Google Workspace Add-on memiliki tumpukan kartu internal untuk setiap kartu. Saat add-on dibuka di host, homepageTrigger yang sesuai akan diaktifkan untuk membuat kartu halaman beranda pertama pada tumpukan (kartu "halaman beranda" berwarna biru tua dalam diagram di bawah). Jika homepageTrigger tidak ditentukan, kartu default akan dibuat, ditampilkan, dan dikirim ke tumpukan non-kontekstual. Kartu pertama ini adalah kartu root.

Add-on dapat membuat kartu non-kontekstual tambahan dan mendorongnya ke tumpukan (kartu "pushed" biru) pada diagram saat pengguna membuka add-on. UI add-on menampilkan kartu teratas dalam tumpukan, sehingga mendorong kartu baru ke tumpukan akan mengubah tampilan, dan memunculkan kartu dari tumpukan akan mengembalikan tampilan ke kartu sebelumnya.

Jika add-on Anda memiliki pemicu kontekstual yang telah ditentukan, saat pengguna memasukkan konteks tersebut, pemicu akan diaktifkan. Fungsi pemicu mem-build kartu kontekstual, tetapi tampilan UI diperbarui berdasarkan DisplayStyle kartu baru:

  • Jika DisplayStyle adalah REPLACE (default), kartu kontekstual (kartu "kontekstual" oranye gelap dalam diagram) akan menggantikan kartu yang saat ini ditampilkan. Ini secara efektif akan memulai tumpukan kartu kontekstual baru di atas stack kartu non-kontekstual, dan kartu kontekstual ini adalah kartu root dari tumpukan kontekstual.
  • Jika DisplayStyle adalah PEEK, UI akan membuat header yang mengintip yang muncul di bagian bawah sidebar add-on, yang menempatkan kartu saat ini. Header intip menampilkan judul kartu baru dan memberikan kontrol tombol pengguna yang memungkinkan mereka memutuskan apakah akan melihat kartu baru atau tidak. Jika mereka mengklik tombol Lihat, kartu akan menggantikan kartu saat ini (seperti yang dijelaskan di atas dengan REPLACE).

Anda dapat membuat kartu kontekstual tambahan dan mendorongnya ke tumpukan ("kartu push" kuning dalam diagram). Memperbarui stack kartu akan mengubah UI add-on untuk menampilkan kartu teratas. Jika pengguna keluar dari konteks, kartu kontekstual di tumpukan akan dihapus dan tampilan akan diperbarui ke kartu atau halaman beranda non-kontekstual teratas.

Jika pengguna memasukkan konteks yang tidak ditentukan oleh add-on add-on, tidak ada kartu baru yang akan dibuat dan kartu saat ini akan tetap ditampilkan.

Tindakan Navigation yang dijelaskan di bawah hanya bertindak pada kartu dari konteks yang sama; misalnya, popToRoot() dari dalam kartu kontekstual hanya memunculkan semua kartu kontekstual lainnya, dan tidak akan memengaruhi kartu halaman beranda.

Sebaliknya, tombol selalu tersedia bagi pengguna untuk menavigasi dari kartu kontekstual Anda ke kartu non-kontekstual Anda.

Anda dapat membuat transisi antar-kartu dengan menambahkan atau menghapus kartu dari tumpukan kartu. Class Navigation menyediakan fungsi untuk mendorong dan memunculkan kartu dari stack. Untuk membuat navigasi kartu yang efektif, konfigurasikan widget Anda untuk menggunakan tindakan navigasi. Anda dapat mendorong atau memunculkan beberapa kartu secara bersamaan, tetapi Anda tidak dapat menghapus kartu halaman beranda awal yang pertama kali didorong ke tumpukan saat add-on dimulai.

Untuk membuka kartu baru sebagai respons terhadap interaksi pengguna dengan widget, ikuti langkah-langkah berikut:

  1. Buat objek Action dan kaitkan dengan fungsi callback yang Anda tentukan.
  2. Panggil fungsi pengendali widget widget yang sesuai untuk menetapkan Action pada widget tersebut.
  3. Implementasikan fungsi callback yang melakukan navigasi. Fungsi ini diberi objek peristiwa tindakan sebagai argumen dan harus melakukan hal berikut:
    1. Buat objek Navigation untuk menentukan perubahan kartu. Satu objek Navigation dapat berisi beberapa langkah navigasi, yang dilakukan sesuai urutan ditambahkan ke objek.
    2. Buat objek ActionResponse menggunakan class ActionResponseBuilder dan objek Navigation.
    3. Tampilkan ActionResponse bawaan.

Saat membuat kontrol navigasi, Anda menggunakan fungsi objek Navigation berikut:

Fungsi Deskripsi
Navigation.pushCard(Card) Mengirimkan kartu ke tumpukan saat ini. Hal ini memerlukan pembuatan kartu sepenuhnya terlebih dahulu.
Navigation.popCard() Menghapus satu kartu dari bagian atas tumpukan. Setara dengan mengklik panah kembali di baris header add-on. Tindakan ini tidak akan menghapus kartu root.
Navigation.popToRoot() Menghapus semua kartu dari tumpukan kecuali untuk kartu root. Pada dasarnya, mereset stack kartu tersebut.
Navigation.popToNamedCard(String) Memunculkan kartu dari tumpukan hingga mencapai kartu dengan nama yang diberikan atau kartu root tumpukan. Anda dapat menetapkan nama ke kartu menggunakan fungsi CardBuilder.setName(String).
Navigation.updateCard(Card) Melakukan penggantian tempat saat ini pada kartu, sehingga pembaruan kartu akan ditampilkan di UI.

Jika interaksi atau peristiwa pengguna akan menghasilkan rendering ulang kartu dalam konteks yang sama, gunakan metode Navigation.pushCard(), Navigation.popCard(), dan Navigation.updateCard() untuk mengganti kartu yang sudah ada. Jika interaksi atau peristiwa pengguna harus menghasilkan kartu rendering ulang dalam konteks yang berbeda, gunakan ActionResponseBuilder.setStateChanged() untuk memaksa eksekusi ulang add-on dalam konteks tersebut.

Berikut adalah contoh navigasi:

  • Jika interaksi atau peristiwa mengubah status kartu saat ini (misalnya, menambahkan tugas ke daftar tugas), gunakan updateCard().
  • Jika interaksi atau peristiwa memberikan detail lebih lanjut atau meminta pengguna melakukan tindakan lebih lanjut (misalnya, mengklik judul item untuk melihat detail selengkapnya, atau menekan tombol untuk membuat acara Kalender baru), gunakan pushCard() untuk menampilkan halaman baru sekaligus memungkinkan pengguna keluar dari halaman baru menggunakan tombol kembali.
  • Jika interaksi atau peristiwa memperbarui status di kartu sebelumnya (misalnya, memperbarui judul item dari dengan tampilan detail), gunakan sesuatu seperti popCard(), popCard(), pushCard(previous), dan pushCard(current) untuk memperbarui kartu sebelumnya dan kartu saat ini.

Memperbarui kartu

Google Workspace add-on memberi pengguna kemampuan untuk memuat ulang kartu Anda dengan menjalankan kembali fungsi pemicu Apps Script yang terdaftar di manifes. Pengguna memicu pembaruan ini melalui item menu add-on:

 sidebar add-onGoogle Workspace  sidebar add-onGoogle Workspace





Tindakan ini otomatis ditambahkan ke kartu yang dihasilkan oleh fungsi pemicu homepageTrigger atau contextualTrigger, seperti yang ditentukan dalam file manifes add-on ('root' dari tumpukan kartu kontekstual dan non-kontekstual).

Menampilkan beberapa kartu

Contoh kartu add-on

Halaman beranda atau fungsi pemicu kontekstual digunakan untuk mem-build dan menampilkan satu objek Card atau array objek Card yang ditampilkan oleh UI aplikasi.

Jika hanya ada satu kartu, kartu itu akan ditambahkan ke stack non-kontekstual atau kontekstual sebagai kartu root dan UI aplikasi host akan menampilkannya.

Jika array yang ditampilkan menyertakan lebih dari satu objek Card bawaan, aplikasi host akan menampilkan kartu baru yang berisi daftar header setiap kartu. Saat pengguna mengklik salah satu header tersebut, UI akan menampilkan kartu yang sesuai.

Saat pengguna memilih kartu dari daftar, kartu tersebut akan didorong ke stack saat ini dan aplikasi host akan menampilkannya. Tombol menampilkan pengguna ke daftar header kartu.

Pengaturan kartu 'flat' ini dapat berfungsi dengan baik jika add-on tidak memerlukan transisi antar-kartu yang Anda buat. Namun, dalam sebagian besar kasus, sebaiknya tentukan transisi kartu secara langsung, dan buat agar fungsi halaman beranda dan pemicu kontekstual Anda menampilkan satu objek kartu.

Contoh

Berikut adalah contoh yang menunjukkan cara membuat beberapa kartu dengan tombol navigasi yang melompat di antara kartu tersebut. Kartu ini dapat ditambahkan ke stack kontekstual atau non-kontekstual dengan mendorong kartu yang ditampilkan oleh createNavigationCard() di dalam atau di luar konteks tertentu.

  /**
   *  Create the top-level card, with buttons leading to each of three
   *  'children' cards, as well as buttons to backtrack and return to the
   *  root card of the stack.
   *  @return {Card}
   */
  function createNavigationCard() {
    // Create a button set with actions to navigate to 3 different
    // 'children' cards.
    var buttonSet = CardService.newButtonSet();
    for(var i = 1; i <= 3; i++) {
      buttonSet.addButton(createToCardButton(i));
    }

    // Build the card with all the buttons (two rows)
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle('Navigation'))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()));
    return card.build();
  }

  /**
   *  Create a button that navigates to the specified child card.
   *  @return {TextButton}
   */
  function createToCardButton(id) {
    var action = CardService.newAction()
        .setFunctionName('gotoChildCard')
        .setParameters({'id': id.toString()});
    var button = CardService.newTextButton()
        .setText('Card ' + id)
        .setOnClickAction(action);
    return button;
  }

  /**
   *  Create a ButtonSet with two buttons: one that backtracks to the
   *  last card and another that returns to the original (root) card.
   *  @return {ButtonSet}
   */
  function buildPreviousAndRootButtonSet() {
    var previousButton = CardService.newTextButton()
        .setText('Back')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoPreviousCard'));
    var toRootButton = CardService.newTextButton()
        .setText('To Root')
        .setOnClickAction(CardService.newAction()
            .setFunctionName('gotoRootCard'));

    // Return a new ButtonSet containing these two buttons.
    return CardService.newButtonSet()
        .addButton(previousButton)
        .addButton(toRootButton);
  }

  /**
   *  Create a child card, with buttons leading to each of the other
   *  child cards, and then navigate to it.
   *  @param {Object} e object containing the id of the card to build.
   *  @return {ActionResponse}
   */
  function gotoChildCard(e) {
    var id = parseInt(e.parameters.id);  // Current card ID
    var id2 = (id==3) ? 1 : id + 1;      // 2nd card ID
    var id3 = (id==1) ? 3 : id - 1;      // 3rd card ID
    var title = 'CARD ' + id;

    // Create buttons that go to the other two child cards.
    var buttonSet = CardService.newButtonSet()
      .addButton(createToCardButton(id2))
      .addButton(createToCardButton(id3));

    // Build the child card.
    var card = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader().setTitle(title))
        .addSection(CardService.newCardSection()
            .addWidget(buttonSet)
            .addWidget(buildPreviousAndRootButtonSet()))
        .build();

    // Create a Navigation object to push the card onto the stack.
    // Return a built ActionResponse that uses the navigation object.
    var nav = CardService.newNavigation().pushCard(card);
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Pop a card from the stack.
   *  @return {ActionResponse}
   */
  function gotoPreviousCard() {
    var nav = CardService.newNavigation().popCard();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }

  /**
   *  Return to the initial add-on card.
   *  @return {ActionResponse}
   */
  function gotoRootCard() {
    var nav = CardService.newNavigation().popToRoot();
    return CardService.newActionResponseBuilder()
        .setNavigation(nav)
        .build();
  }