Navigasi kartu

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

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

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

Add-on Anda dapat membuat kartu non-kontekstual tambahan dan mendorongnya ke tumpukan ("kartu yang didorong" berwarna biru pada diagram) saat pengguna melakukan navigasi add-on Anda. UI add-on menampilkan kartu teratas dalam tumpukan, sehingga mengirim kartu baru kartu ke tumpukan akan mengubah tampilan, dan memunculkan kartu dari tumpukan akan mengembalikan tampilan ke kartu sebelumnya.

Jika add-on Anda memiliki pemicu kontekstual, saat pengguna memasuki konteks tersebut, pemicu akan diaktifkan. Fungsi pemicu membuat kartu kontekstual, tetapi tampilan UI diupdate berdasarkan DisplayStyle kartu baru:

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

Anda dapat membuat kartu konteks tambahan dan mendorongnya ke tumpukan ("kartu yang didorong" berwarna kuning pada diagram). Memperbarui tumpukan kartu mengubah UI add-on untuk menampilkan kartu paling atas. Jika pengguna meninggalkan konteks, kartu kontekstual pada tumpukan akan dihapus dan tampilan pembaruan untuk beranda atau kartu non-kontekstual teratas.

Jika pengguna memasukkan konteks bahwa add-on Anda tidak mendefinisikan pemicu kontekstual, tidak ada kartu baru yang dibuat dan kartu saat ini tetap ditampilkan.

Tindakan Navigation yang dijelaskan di bawah hanya menindaklanjuti 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 ke kartu non-kontekstual.

Metode navigasi

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

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

1. Membuat objek Action dan mengaitkannya dengan fungsi callback yang Anda tentukan.
2. Panggil widget yang sesuai fungsi pengendali widget untuk menyetel 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. Membuat Navigation untuk menentukan perubahan kartu. Satu objek Navigation dapat berisi beberapa langkah navigasi, yang dilakukan sesuai urutan mereka ditambahkan ke objek.
   2. Membangun ActionResponse menggunakan atribut ActionResponseBuilder dan Navigation .
   3. Mengembalikan yang dibangun ActionResponse

Catatan: Saat menavigasi di antara kartu, Anda tidak menentukan tumpukan mana (kontekstual atau non-kontekstual) kartu ditambahkan atau dihapus. Kontrol ini dikontrol oleh pengguna saat mereka masuk dan meninggalkan konteks. Saat membuat add-on, pastikan untuk menguji navigasi kartu Anda secara menyeluruh, termasuk perubahan konteks, untuk pengalaman pengguna yang positif.

Saat membuat kontrol navigasi, Anda menggunakan Fungsi objek Navigation:

Fungsi	Deskripsi
Navigation.pushCard(Card)	Mendorong kartu ke tumpukan saat ini. Anda harus membuat 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 menghapus kartu root.
Navigation.popToRoot()	Menghapus semua kartu dari tumpukan kecuali untuk kartu root. Pada dasarnya, setumpuk kartu tersebut direset.
Navigation.popToNamedCard(String)	Memunculkan kartu dari tumpukan hingga mencapai kartu dengan nama tertentu atau kartu root tumpukan. Anda dapat menetapkan nama ke kartu menggunakan fungsi CardBuilder.setName(String).
Navigation.updateCard(Card)	Melakukan penggantian kartu saat ini di tempat, memuat ulang tampilan di UI.

Praktik terbaik navigasi

Jika interaksi atau peristiwa pengguna menyebabkan rendering ulang kartu dengan cara konteks, gunakan Navigation.pushCard(), Navigation.popCard(), dan Navigation.updateCard() untuk mengganti kartu yang ada. Jika interaksi atau peristiwa pengguna harus menyebabkan rendering ulang kartu dalam konteks berbeda, gunakan ActionResponseBuilder.setStateChanged() untuk memaksa eksekusi ulang add-on Anda dalam konteks tersebut.

Berikut adalah contoh navigasi:

• Jika interaksi atau peristiwa mengubah status kartu saat ini (misalnya, menambahkan tugas ke daftar tugas), menggunakan updateCard()
• Apakah interaksi atau peristiwa memberikan detail lebih lanjut atau meminta pengguna untuk 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 dengan tampilan detail), gunakan sesuatu seperti popCard(), popCard(), pushCard(previous), dan pushCard(current) untuk memperbarui kartu sebelumnya dan kartu saat ini.

Memperbarui kartu

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

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

Mengembalikan beberapa kartu

Halaman beranda atau fungsi pemicu kontekstual digunakan untuk membuat dan menampilkan salah satu Objek Card atau array objek Card yang tampilan UI aplikasi Anda.

Jika hanya ada satu kartu, kartu tersebut akan ditambahkan ke tumpukan non-kontekstual atau kontekstual seperti kartu {i>root<i} dan UI aplikasi {i>host<i} menampilkannya.

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

Saat pengguna memilih kartu dari daftar, kartu tersebut akan didorong ke {i>stack <i}saat ini dan aplikasi {i> host<i} menampilkannya. Tujuan Tombol mengembalikan pengguna ke daftar header kartu.

'Flat' ini pengaturan kartu dapat berfungsi dengan baik jika add-on Anda tidak memerlukan transisi antarkartu yang Anda buat. Namun, dalam kebanyakan kasus, akan lebih baik berlatih untuk menentukan transisi kartu secara langsung, dan mengatur beranda serta fungsi pemicu kontekstual menampilkan satu objek kartu.

Contoh

Berikut adalah contoh yang menunjukkan cara membuat beberapa kartu dengan navigasi tombol yang melompat di antara mereka. Kartu ini dapat ditambahkan ke stack kontekstual atau non-kontekstual dengan mendorong kartu yang ditampilkan oleh createNavigationCard() 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();
  }