Navegação do card

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

A maioria dos complementos baseados em cartões é criada usando vários cards que representam &&39;pages' diferentes da interface do complemento. Para que o usuário tenha uma experiência eficaz, use uma navegação simples e natural entre os cards no complemento.

Originalmente, nos complementos do Gmail, as transições entre diferentes cards da IU são processadas com o envio e o envio de cards de e para uma única pilha de cartões, com o card da parte superior da pilha exibido pelo Gmail.

Navegação no card da página inicial

Google Workspace Os complementos apresentam páginas iniciais e cards não contextuais. Para acomodar cartões contextuais e não contextuais, Google Workspace os complementos têm uma pilha de cartões interna para cada um. Quando um complemento é aberto em um host, o homepageTrigger correspondente é acionado para criar o primeiro card da página inicial na pilha (o card "quot;página inicial" azul-escuro" no diagrama abaixo). Se um homepageTrigger não for definido, um cartão padrão será criado, exibido e enviado à pilha não contextual. O primeiro cartão é do tipo root.

Seu complemento pode criar outros cartões não contextuais e enviá-los para a pilha (os cartões azuis e enviados no diagrama) conforme o usuário navega pelo complemento. A IU dos complementos exibe o card superior na pilha. Portanto, o envio de novos cartões para a pilha muda a exibição, e a remoção dos cards da pilha retorna a exibição para os cards anteriores.

Se o complemento tiver um gatilho contextual definido, quando o usuário entrar nesse contexto, o acionador será disparado. A função de gatilho cria o card contextual, mas a exibição da IU é atualizada com base no DisplayStyle do novo cartão:

  • Se o DisplayStyle for REPLACE (o padrão), o cartão contextual (o laranja "context" no diagrama) substituirá o cartão exibido no momento. Isso inicia efetivamente uma nova pilha de cartões contextuais sobre a pilha de cartões não contextuais, e esse cartão contextual é o cartão raiz da pilha contextual.
  • Se o DisplayStyle for PEEK, a IU vai criar um cabeçalho de exibição na parte inferior da barra lateral do complemento, sobrepondo o card atual. O cabeçalho de exibição mostra o título do novo cartão e informa os controles do botão do usuário que permitem decidir se o novo cartão será exibido ou não. Se ele clicar no botão Ver, o card substituirá o cartão atual (conforme descrito acima por REPLACE).

É possível criar outros cartões de contexto e enviá-los na pilha, o que é feito no diagrama, como os cartões "enviados em amarelo" Atualizar a pilha de cards altera a IU do complemento para exibir o cartão mais acima. Se o usuário sair de um contexto, os cards contextuais na pilha serão removidos e a tela será atualizada no primeiro card ou na página inicial não contextual.

Se o usuário entrar em um contexto em que seu complemento não define um gatilho contextual, nenhum cartão novo será criado, e o card atual permanecerá exibido.

As ações Navigation descritas abaixo atuam somente em cards do mesmo contexto. Por exemplo, popToRoot() em um card de contexto exibe apenas todos os outros cards de contexto e não afetam os cards da página inicial.

Por outro lado, o botão está sempre disponível para o usuário navegar dos cartões contextuais para os cards não contextuais.

Você pode criar transições entre cards adicionando ou removendo cards das pilhas de cards. A classe Navigation fornece funções para enviar e abrir cards das pilhas. Para criar uma navegação de card eficiente, configure os widgets para usar ações de navegação. Você pode enviar ou abrir vários cartões simultaneamente, mas não é possível remover o cartão inicial da página inicial que é inserido primeiro na pilha quando o complemento é iniciado.

Para navegar até um novo cartão em resposta a uma interação do usuário com um widget, siga estas etapas:

  1. Crie um objeto Action e o associe a uma função de callback definida por você.
  2. Chamar a função de gerenciador de widgets apropriada do widget para definir a 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. Crie um objeto Navigation para definir a mudança do cartão. Um único objeto Navigation pode conter várias etapas de navegação, que são conduzidas na ordem em que são adicionadas ao objeto.
    2. Crie um objeto ActionResponse usando a classe ActionResponseBuilder e o objeto Navigation.
    3. Retorne o ActionResponse criado.

Ao criar controles de navegação, use as seguintes funções de objeto Navigation:

Função Descrição
Navigation.pushCard(Card) Envia um cartão para a pilha atual. Isso exige a criação completa do card.
Navigation.popCard() Remove um card do topo da pilha. Equivalente a clicar na seta para voltar na linha do cabeçalho do complemento. Isso não remove os cartões raiz.
Navigation.popToRoot() Remove todos os cartões da pilha, exceto o cartão raiz. Basicamente, redefine essa pilha de cartões.
Navigation.popToNamedCard(String) Retira os cards da pilha até alcançar um cartão com o nome fornecido ou o cartão raiz da pilha. Você pode atribuir nomes aos cards usando a função CardBuilder.setName(String).
Navigation.updateCard(Card) Substitui o cartão atual, atualizando a exibição dele na IU.

Se uma interação do usuário ou um evento precisar resultar na nova renderização dos cards no mesmo contexto, use os métodos Navigation.pushCard(), Navigation.popCard() e Navigation.updateCard() para substituir os cards atuais. Se uma interação do usuário ou um evento precisar resultar na renderização de cartões novamente em um contexto diferente, use ActionResponseBuilder.setStateChanged() para forçar a nova execução do complemento nesses contextos.

Veja alguns exemplos de navegação:

  • Se uma interação ou evento mudar o estado do card atual (por exemplo, adicionar uma tarefa a uma lista de tarefas), use updateCard().
  • Se uma interação ou um evento fornecer mais detalhes ou solicitar ao usuário mais ações (por exemplo, clicar no título de um item para ver mais detalhes ou pressionar um botão para criar um novo evento do Agenda), use pushCard() para mostrar a nova página enquanto permite que o usuário saia da nova página usando o botão "Voltar".
  • Se uma interação ou um evento for atualizado no estado de um card anterior (por exemplo, atualizando 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

Google Workspace Os complementos oferecem aos usuários a capacidade de atualizar o cartão executando novamente a função de gatilho do Apps Script registrada no manifesto. Os usuários acionam essa atualização usando um item de menu complementar:

 l10n-placeholder39=  l10n-placeholder40=





Esta ação é adicionada automaticamente aos cartões gerados pelas funções de gatilho homepageTrigger ou contextualTrigger, conforme especificado no arquivo de manifesto dos complementos, que é o 'roots' das pilhas de cartões contextuais e não contextuais.

Como retornar vários cartões

Exemplo de card de complementos

As funções de página inicial ou de acionador contextual são usadas para criar e retornar um único objeto Card ou uma matriz de objetos Card que a IU do aplicativo exibe.

Se houver apenas um cartão, ele será adicionado à pilha não contextual ou contextual conforme o cartão raiz e a IU do aplicativo host exibirá.

Se a matriz retornada incluir mais de um objeto criado Card, o aplicativo host exibirá um novo cartão, que contém uma lista de cabeçalhos de cada card. Quando o usuário clica em algum desses cabeçalhos, a IU mostra o card correspondente.

Quando o usuário seleciona um cartão da lista, ele é enviado para a pilha atual e o aplicativo host o exibe. O botão retorna o usuário à lista de cabeçalhos do card.

Essa disposição de cartão pode funcionar bem se seu complemento não precisar de transições entre os cartões criados por você. No entanto, na maioria dos casos, a prática recomendada é definir diretamente as transições de cartão e fazer com que a página inicial e as funções de acionador contextual retornem um único objeto de cartão.

Exemplo

Veja um exemplo que mostra como criar vários cards com botões de navegação que pulam entre eles. Esses cards 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();
  }