Navegação no card

A maioria dos complementos baseados em cartão é criada usando vários cards que representam diferentes "páginas" da do complemento. Para ter uma experiência do usuário eficaz, use uma navegação simples e natural entre os cartões no complemento.

Originalmente nos complementos do Gmail, as transições entre os diferentes cards da interface são é manipulada empurrando e estourando cartas de e para uma única pilha de cartas, com o card na parte de cima da pilha exibido pelo Gmail.

Conheça os complementos do Google Workspace páginas iniciais e cards não contextuais. Para acomodar cards contextuais e não contextuais, Os complementos do Google Workspace têm uma pilha de cards interna para cada um. Quando um complemento é aberto em um host, a homepageTrigger correspondente é acionada para criar a primeira na pilha (o card azul escuro "página inicial" no diagrama abaixo). Se um homepageTrigger não for definido, um cartão padrão será criado, exibido e enviados para a pilha não contextual. O primeiro é um cartão raiz.

Seu complemento pode criar outros cards não contextuais e enviá-los para a (os "cartões enviados" azuis no diagrama) conforme o usuário navega seu complemento. A interface do complemento mostra o card de cima na pilha, ou seja, enviar novos as cartas na pilha mudam a exibição, e remover as cartas da pilha retorna mostrar aos cartões anteriores.

Caso seu complemento tenha um acionador contextual, quando o usuário entra nesse contexto, o acionador é disparado. Função de gatilho cria o card de contexto, mas a exibição da interface é atualizada com base no DisplayStyle do novo cartão:

• Se o DisplayStyle for REPLACE (o padrão), o card de contexto (laranja-escuro) "contextual" no diagrama) substitui o campo card exibido. Isso inicia uma nova pilha de cards contextuais na parte de cima. da pilha de cards não contextuais, e esse cartão de contexto é o raiz da pilha contextual.
• Se o DisplayStyle for PEEK, a interface criará um cabeçalho que aparece parte inferior da barra lateral do complemento, sobrepondo o card atual. Cabeçalho de exibição mostra o título do novo card e fornece controles de botão do usuário que permitem que decidem se querem ver o novo cartão ou não. Se ele clicar no botão Visualizar , o cartão substitui o atual (como descrito acima por REPLACE).

Você pode criar outros cards contextuais e envie-os para a pilha (os "cartões enviados" amarelos no diagrama). Atualizando a pilha de cartões muda a interface do complemento para exibir o cartão no topo. Se o usuário sai de um contexto, os cards de contexto na pilha são removidos e a exibição atualizações no card ou na página inicial não contextual mais acima.

Se o usuário inserir um contexto que seu complemento não define um acionador contextual, nenhum cartão novo é criado, e a o cartão atual permanece na tela.

As ações Navigation descritos abaixo só funcionam em cards do mesmo contexto. por exemplo, popToRoot() de dentro de um cartão de contexto exibe apenas todos os outros cards contextuais; e não afetará os cards da página inicial.

Por outro lado, o botão arrow_back é estará sempre disponível para que o usuário navegue dos cards contextuais para seu cards não contextuais.

Métodos de navegação

É possível criar transições entre cards adicionando ou removendo cards do pilhas de cards. O Navigation fornece funções para enviar e retirar cards das pilhas. Para criar uma navegação de card eficaz, você configura widgets para usar a navegação. ações. Você pode pressionar ou soltar vários cards simultaneamente, mas não é possível remover o card inicial da página inicial que é enviado pela primeira vez para a pilha quando o complemento é iniciado.

Para acessar um novo card em resposta a uma interação do usuário com um widget, faça o seguinte: siga estas etapas:

1. Crie um objeto Action. e associá-lo a um função de callback definido por você.
2. Chame o método função do gerenciador de widgets para definir o Action nesse widget.
3. Implemente a função de callback que conduz a navegação. Essa função recebe um objeto de evento de ação; como argumento e precisa fazer o seguinte:
   1. Criar um Navigation para definir a alteração do cartão. Um único objeto Navigation pode contêm várias etapas de navegação, que são realizadas na ordem eles são adicionados ao objeto.
   2. Criar um ActionResponse usando o ActionResponseBuilder classe e a classe Navigation objeto.
   3. Retornar o build ActionResponse

Ao criar controles de navegação, você usa o seguinte Funções do objeto Navigation:

Prática recomendada de navegação

Se uma interação ou um evento do usuário resultar em uma nova renderização dos cards da mesma forma contexto, use Navigation.pushCard(), Navigation.popCard(), e Navigation.updateCard() para substituir os cartões existentes. Se uma interação ou evento do usuário resultar na nova renderização dos cards em um contexto diferente, use ActionResponseBuilder.setStateChanged() para forçar a reexecução do complemento nesses contextos.

Confira a seguir exemplos de navegação:

• Se uma interação ou um evento mudar o estado do card atual (por exemplo, adicionar uma tarefa a uma lista), use updateCard()
• Se uma interação ou um evento fornecer mais detalhes ou solicitar que o usuário outra ação (por exemplo, clicar no título de um item para ver mais detalhes ou pressionando um botão para criar um novo evento da Agenda), use pushCard() para mostrar a nova página e, ao mesmo tempo, permitir que o usuário saia dela usando o botão Voltar.
• Se uma interação ou um evento atualizar o estado em um card anterior (por exemplo, atualizar o título de um item com a visualização de detalhes), use algo como popCard(), popCard(), pushCard(previous), e pushCard(current) para atualizar o cartão anterior e o atual.

Atualizando cards

Com os complementos do Google Workspace, os usuários podem atualize o card executando novamente a função de gatilho do Apps Script registrada manifesto. Os usuários acionam essa atualização com um item de menu de complemento:

Esta ação é adicionada automaticamente aos cards gerados por homepageTrigger ou contextualTrigger funções de gatilho, conforme especificado no manifesto do seu complemento (as "raiz" das pilhas de cards contextuais e não contextuais).

Como retornar vários cartões

A página inicial ou funções de gatilho contextual são usadas para criar e retornar um único objeto Card ou uma matriz de Objetos Card que o na interface do aplicativo.

Se houver apenas um card, ele será adicionado à pilha não contextual ou contextual como o cartão raiz e a interface do aplicativo host o exibe.

Se a matriz retornada incluir mais de um Card objeto, o aplicativo host exibirá um novo cartão, que contém um lista do cabeçalho de cada card. Quando o usuário clica em qualquer um desses cabeçalhos, a interface exibe o cartão correspondente.

Quando o usuário seleciona um cartão da lista, esse cartão é enviado para a a pilha atual e o aplicativo host a exibe. O O botão arrow_back retorna o usuário ao do cabeçalho do card.

Esta posição a organização do cartão pode funcionar bem se seu complemento não precisar de transições entre os cards criados. No entanto, na maioria dos casos, é melhor para definir diretamente as transições de cards e ter sua página inicial e As funções de gatilho contextual retornam um único objeto card.

Exemplo

Confira um exemplo que mostra como criar vários cards com navegação que alternam entre elas. Esses cartões podem ser adicionados pilha contextual ou não contextual ao enviar o card retornado por createNavigationCard() dentro ou fora de um contexto específico.

  /**
   *  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();
  }