Navegación por la tarjeta

La mayoría de los complementos basados en tarjetas se compilan mediante varias tarjetas que representan diferentes "páginas" de la interfaz del complemento. Para tener una experiencia del usuario eficaz, debes usar una navegación simple y natural entre las tarjetas de tu complemento.

Originalmente, en los complementos de Gmail, las transiciones entre diferentes tarjetas de la IU se controlan con el envío y la presentación de tarjetas hacia y desde una sola pila de tarjetas, con la tarjeta superior de la pila mostrada en Gmail.

Navegación de la tarjeta de la página principal

Los complementos de Google Workspace presentan páginas principales y tarjetas no contextuales. A fin de adaptarse a tarjetas contextuales y no contextuales, los complementos de Google Workspace tienen una pila de tarjetas interna para cada una. Cuando se abre un complemento en un host, se activa el homepageTrigger correspondiente para crear la primera tarjeta de la página principal en la pila (la tarjeta "página principal" de color azul oscuro en el siguiente diagrama). Si no se define un homepageTrigger, se crea una tarjeta predeterminada, se muestra y se envía a la pila no contextual. Esta primera tarjeta es raíz.

Tu complemento puede crear tarjetas no contextuales adicionales y enviarlas a la pila (las "tarjetas enviadas" de color azul en el diagrama) a medida que el usuario navega por el complemento. La IU del complemento muestra la tarjeta superior en la pila, por lo que enviar tarjetas nuevas a la pila cambia la pantalla, y quitar las tarjetas de la pila hace que se muestren las tarjetas anteriores.

Si tu complemento tiene un activador contextual definido, se activa el activador cuando el usuario ingresa a ese contexto. La función activadora compila la tarjeta contextual, pero la pantalla de la IU se actualiza en función del DisplayStyle de la nueva tarjeta:

  • Si DisplayStyle es REPLACE (la opción predeterminada), la tarjeta contextual (la tarjeta "contextual" de color naranja oscuro en el diagrama) reemplaza la tarjeta que se muestra actualmente. Esto inicia, de manera efectiva, una nueva pila de tarjetas contextuales sobre la pila de tarjetas no contextuales, y esta tarjeta es la tarjeta raíz de la pila contextual.
  • Si DisplayStyle es PEEK, la IU crea, en cambio, un encabezado de vista que aparece en la parte inferior de la barra lateral del complemento y se superpone con la tarjeta actual. El encabezado de vista rápida muestra el título de la tarjeta nueva y proporciona controles de botones al usuario que le permiten decidir si ver la tarjeta nueva o no. Si hace clic en el botón Ver, la tarjeta reemplazará la tarjeta actual (como se describió anteriormente con REPLACE).

Puedes crear tarjetas contextuales adicionales y enviarlas a la pila (las "tarjetas empujadas" amarillas en el diagrama). Cuando se actualiza la pila de tarjetas, se cambia la IU del complemento para mostrar la tarjeta que se encuentra en la parte superior. Si el usuario deja un contexto, se quitan las tarjetas contextuales de la pila y la pantalla se actualiza a la página principal o la tarjeta no contextual que se encuentra en la parte superior.

Si el usuario ingresa un contexto para el que tu complemento no define un activador contextual, no se crea ninguna tarjeta nueva y se muestra la tarjeta actual.

Las acciones de Navigation que se describen a continuación solo actúan en tarjetas del mismo contexto. Por ejemplo, popToRoot() dentro de una tarjeta contextual solo muestra todas las demás tarjetas contextuales y no afectará las tarjetas de la página principal.

Por el contrario, el botón siempre está disponible para que el usuario navegue desde tus tarjetas contextuales hasta tus tarjetas no contextuales.

Puedes crear transiciones entre tarjetas agregando o quitando tarjetas de las pilas de tarjetas. La clase Navigation proporciona funciones para enviar y destacar tarjetas de las pilas. Si quieres compilar una navegación por tarjetas eficaz, configura tus widgets para que usen acciones de navegación. Puedes enviar o mostrar varias tarjetas al mismo tiempo, pero no puedes quitar la tarjeta inicial de la página principal que se envía primero a la pila cuando se inicia el complemento.

Para navegar a una tarjeta nueva en respuesta a la interacción de un usuario con un widget, sigue estos pasos:

  1. Crea un objeto Action y asócialo con una función de devolución de llamada que definas.
  2. Llama a la función de controlador del widget correspondiente del widget para configurar Action en ese widget.
  3. Implementa la función de devolución de llamada que lleva a cabo la navegación. A esta función se le asigna un objeto de evento de acción como argumento y debe hacer lo siguiente:
    1. Crea un objeto Navigation para definir el cambio de tarjeta. Un solo objeto Navigation puede contener varios pasos de navegación, que se realizan en el orden en que se agregan al objeto.
    2. Compila un objeto ActionResponse con la clase ActionResponseBuilder y el objeto Navigation.
    3. Muestra el ActionResponse compilado.

Cuando compilas controles de navegación, usas las siguientes funciones del objeto Navigation:

Función Descripción
Navigation.pushCard(Card) Envía una tarjeta a la pila actual. Para ello, primero debes compilar la tarjeta por completo.
Navigation.popCard() Quita una tarjeta de la parte superior de la pila. El servicio equivale a hacer clic en la flecha hacia atrás de la fila del encabezado del complemento. Esta acción no quita las tarjetas raíz.
Navigation.popToRoot() Quita todas las tarjetas de la pila, excepto la tarjeta raíz. Básicamente, restablece esa pila de tarjetas.
Navigation.popToNamedCard(String) Muestra cartas de la pila hasta que llega a una con el nombre dado o a la tarjeta raíz de la pila. Puedes asignarles nombres a las tarjetas con la función CardBuilder.setName(String).
Navigation.updateCard(Card) Realiza un reemplazo in situ de la tarjeta actual y actualiza la pantalla en la IU.

Si una interacción o un evento del usuario tienen como resultado que se vuelvan a renderizar las tarjetas en el mismo contexto, usa los métodos Navigation.pushCard(), Navigation.popCard() y Navigation.updateCard() para reemplazar las tarjetas existentes. Si una interacción o un evento del usuario generan que se vuelvan a renderizar las tarjetas en un contexto diferente, usa ActionResponseBuilder.setStateChanged() para forzar que se vuelva a ejecutar tu complemento en esos contextos.

Los siguientes son ejemplos de navegación:

  • Si una interacción o un evento cambia el estado de la tarjeta actual (por ejemplo, agregar una tarea a una lista de tareas), usa updateCard().
  • Si una interacción o un evento proporciona más detalles o le solicita al usuario que realice más acciones (por ejemplo, hacer clic en el título de un elemento para ver más detalles o presionar un botón para crear un evento de Calendario nuevo), usa pushCard() para mostrar la página nueva y permitir que el usuario salga de ella con el botón Atrás.
  • Si una interacción o un evento actualiza el estado en una tarjeta anterior (por ejemplo, cuando se actualiza el título de un elemento desde la vista detallada), usa algo como popCard(), popCard(), pushCard(previous) y pushCard(current) para actualizar la tarjeta anterior y la actual.

Actualizando tarjetas

Los complementos de Google Workspace ofrecen a los usuarios la capacidad de actualizar la tarjeta. Para ello, deben volver a ejecutar la función de activación de Apps Script registrada en tu manifiesto. Los usuarios activan esta actualización a través de un elemento de menú de complementos:

Barra lateral del complemento de Google Workspace

Esta acción se agrega automáticamente a las tarjetas generadas por las funciones de activación homepageTrigger o contextualTrigger, como se especifica en el archivo de manifiesto de tu complemento (las "raíces" de las pilas de tarjetas contextuales y no contextuales).

Cómo devolver varias tarjetas

Ejemplo de tarjeta de complemento

La página principal o las funciones de activación contextuales se usan para compilar y mostrar un solo objeto Card o un array de objetos Card que muestra la IU de la aplicación.

Si solo hay una tarjeta, se agrega a la pila no contextual o contextual como la tarjeta raíz y la IU de la aplicación host la muestra.

Si el array que se muestra incluye más de un objeto Card compilado, la aplicación host mostrará una tarjeta nueva, que contiene una lista de los encabezados de cada tarjeta. Cuando el usuario hace clic en cualquiera de esos encabezados, la IU muestra la tarjeta correspondiente.

Cuando el usuario selecciona una tarjeta de la lista, esta se envía a la pila actual y la aplicación host la muestra. El botón dirige al usuario a la lista de encabezados de tarjetas.

Esta disposición de tarjetas "plana" puede funcionar bien si tu complemento no necesita ninguna transición entre las tarjetas que crees. Sin embargo, en la mayoría de los casos, es mejor definir directamente las transiciones de tarjetas y hacer que la página principal y las funciones de activador contextuales muestren un solo objeto de tarjeta.

Ejemplo

En el siguiente ejemplo, se muestra cómo construir varias tarjetas con botones de navegación que salten entre ellas. Estas tarjetas se pueden agregar a la pila contextual o no contextual enviando la tarjeta que muestra createNavigationCard() dentro o fuera de un contexto en particular.

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