Navigation par carte

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

La plupart des modules complémentaires se composent de plusieurs fiches qui représentent les différentes pages de l'interface. Pour une expérience utilisateur efficace, vous devez utiliser la navigation simple et naturelle entre les fiches de votre module complémentaire.

À l'origine, dans les modules complémentaires Gmail, les transitions entre les différentes cartes de l'interface étaient gérées par l'envoi de fiches aux cartes et leur transfert depuis une seule et même carte, la fiche supérieure de la pile étant affichée par Gmail.

Navigation sur la fiche de la page d'accueil

Google Workspace Les modules complémentaires présentent les pages d'accueil et les fiches non contextuelles. Pour prendre en charge les fiches contextuelles et non contextuelles,Google Workspace les modules complémentaires disposent d'une pile de fiches interne pour chacun. Lorsqu'un module complémentaire est ouvert dans un hôte, le homepageTrigger correspondant se déclenche pour créer la première fiche de la page d'accueil sur la pile (la fiche"page d'accueil"bleu foncé dans le schéma ci-dessous). Si aucune propriété homepageTrigger n'est définie, une fiche par défaut est créée, affichée et transférée sur la pile non contextuelle. La première est une carte racine.

Votre module complémentaire peut créer des fiches non contextuelles supplémentaires et les transférer vers la pile (les "cartes" bleues figurant dans le schéma) à mesure que l'utilisateur parcourt le module. L'interface utilisateur du module complémentaire affiche la fiche supérieure de la pile. Lorsque vous placez de nouvelles fiches dans la pile, l'écran s'affiche, et les cartes qui sortent de la pile renvoient les cartes précédentes.

Si votre module complémentaire dispose d'un déclencheur de contexte défini, il est exécuté lorsque l'utilisateur saisit ce contexte. La fonction de déclenchement crée la fiche contextuelle, mais l'interface utilisateur est mise à jour en fonction de la propriété DisplayStyle de la nouvelle fiche:

  • Si DisplayStyle est REPLACE (valeur par défaut), la carte contextuelle (carte orange foncée du schéma) remplace la carte actuellement affichée. Cela crée une pile de fiches contextuelles en plus de la pile de cartes non contextuelles. Cette carte contextuelle est la carte racine de la pile contextuelle.
  • Si DisplayStyle est défini sur PEEK, l'interface utilisateur crée à la place un en-tête d'aperçu qui apparaît en bas de la barre latérale du module complémentaire, en superposition de la fiche actuelle. L'en-tête d'aperçu affiche le titre de la nouvelle fiche et fournit les commandes permettant à l'utilisateur de choisir s'il doit l'afficher ou non. S'il clique sur le bouton Afficher, la fiche remplace la carte actuelle (comme décrit ci-dessus par REPLACE).

Vous pouvez créer des fiches contextuelles supplémentaires et les ajouter à la pile (les "pushpush" jaunes" dans le diagramme). La mise à jour de la pile de fiches modifie l'interface utilisateur du module complémentaire pour afficher la fiche supérieure. Si l'utilisateur quitte le contexte, les cartes contextuelles de la pile sont supprimées et l'affichage passe à la fiche ou à la page d'accueil non contextuelles les plus populaires.

Si l'utilisateur entre dans un contexte pour lequel votre module complémentaire ne définit pas de déclencheur contextuel, aucune nouvelle fiche n'est créée et la carte actuelle reste affichée.

Les actions Navigation décrites ci-dessous ne s'appliquent qu'aux fiches du même contexte. Par exemple, popToRoot() depuis une carte contextuelle ne fait apparaître que toutes les autres fiches contextuelles et n'a aucune incidence sur les fiches de la page d'accueil.

En revanche, le bouton est toujours disponible pour permettre aux utilisateurs de passer de vos fiches contextuelles à vos cartes non contextuelles.

Vous pouvez créer des transitions entre des fiches en ajoutant ou en supprimant des cartes dans les piles. La classe Navigation fournit des fonctions permettant de transférer et d'envoyer des cartes à partir des piles. Pour créer une navigation par carte efficace, vous devez configurer vos widgets afin d'utiliser les actions de navigation. Vous pouvez pousser ou faire apparaître plusieurs fiches simultanément, mais vous ne pouvez pas supprimer la première page de la page d'accueil qui est initialement insérée dans la pile au démarrage du module complémentaire.

Pour accéder à une nouvelle fiche en réponse à une interaction de l'utilisateur avec un widget, procédez comme suit:

  1. Créez un objet Action et associez-le à une fonction de rappel que vous définissez.
  2. Appelez la fonction de gestionnaire de widgets appropriée pour définir le Action sur ce widget.
  3. Implémentez la fonction de rappel qui effectue la navigation. Un objet d'événement d'action est attribué à cette fonction en tant qu'argument. Elle doit respecter les conditions suivantes :
    1. Créez un objet Navigation pour définir la modification de la fiche. Un seul objet Navigation peut contenir plusieurs étapes de navigation, qui sont exécutées dans l'ordre dans lequel elles ont été ajoutées à l'objet.
    2. Créez un objet ActionResponse à l'aide de la classe ActionResponseBuilder et de l'objet Navigation.
    3. Renvoyez le ActionResponse compilé.

Lorsque vous créez des commandes de navigation, vous utilisez les fonctions d'objet Navigation suivantes:

Function Description
Navigation.pushCard(Card) Transférer une carte vers la pile actuelle Pour cela, vous devez d'abord créer la carte.
Navigation.popCard() Supprime une carte du haut de la pile. Cela équivaut à cliquer sur la flèche de retour dans la ligne d'en-tête du module complémentaire. Cette action ne supprime pas les cartes racine.
Navigation.popToRoot() Supprime toutes les cartes de la pile, à l'exception de la carte racine. En bref, cette pile de cartes est réinitialisée.
Navigation.popToNamedCard(String) Fait sortir les cartes de la pile jusqu'à atteindre une carte portant le nom indiqué ou la carte racine de la pile. Vous pouvez attribuer des noms aux fiches à l'aide de la fonction CardBuilder.setName(String).
Navigation.updateCard(Card) Remplacement de la carte actuelle en cours, qui s'actualise dans l'interface utilisateur.

Si une interaction ou un événement d'un utilisateur doit entraîner un nouveau rendu de fiches dans le même contexte, remplacez les fiches existantes par les méthodes Navigation.pushCard(), Navigation.popCard() et Navigation.updateCard(). Si une interaction ou un événement de l'utilisateur doit entraîner le réaffichage des fiches dans un autre contexte, utilisez ActionResponseBuilder.setStateChanged() pour forcer la réexécution de votre module complémentaire dans ces contextes.

Voici des exemples de navigation:

  • Si une interaction ou un événement modifie l'état de la fiche actuelle (par exemple, l'ajout d'une tâche à une liste de tâches), utilisez updateCard().
  • Si une interaction ou un événement fournit des détails supplémentaires ou invite l'utilisateur à effectuer une autre action (par exemple, cliquer sur le titre d'un élément pour afficher plus de détails ou appuyer sur un bouton pour créer un événement d'agenda), utilisez pushCard() pour afficher la nouvelle page tout en permettant à l'utilisateur de quitter la nouvelle page à l'aide du bouton de retour.
  • Si une interaction ou un événement met à jour l'état d'une fiche précédente (par exemple, si vous mettez à jour le titre d'un élément dans la vue détaillée), utilisez popCard(), popCard(), pushCard(previous) ou pushCard(current) pour mettre à jour la carte précédente et la carte actuelle.

Actualisation des fiches...

Google Workspace Les modules complémentaires permettent aux utilisateurs d'actualiser votre carte en exécutant à nouveau la fonction de déclenchement d'Apps Script enregistrée dans votre fichier manifeste. Les utilisateurs déclenchent cette actualisation via un élément de menu complémentaire:

 l10n-placeholder39=  l10n-placeholder40=





Cette action est automatiquement ajoutée aux fiches générées par les fonctions de déclenchement de homepageTrigger ou contextualTrigger, comme spécifié dans le fichier manifeste de votre module complémentaire (racines 'racines des cartes contextuelles et non contextuelles).

Retour de plusieurs cartes

Exemple de fiche complémentaire

Les fonctions de page d'accueil ou de déclencheurs contextuels permettent de créer et de renvoyer un seul objet Card ou un tableau d'objets Card que l'interface utilisateur de l'application affiche.

S'il n'y a qu'une seule carte, celle-ci est ajoutée à la pile contextuelle ou non contextuelle en tant que carte racine et affichée dans l'interface utilisateur de l'application hôte.

Si le tableau renvoyé inclut plusieurs objets Card, l'application hôte affiche une nouvelle fiche contenant une liste de l'en-tête de chaque carte. Lorsque l'utilisateur clique sur l'un de ces en-têtes, l'interface utilisateur affiche la fiche correspondante.

Lorsque l'utilisateur sélectionne une fiche dans la liste, celle-ci est transférée dans la pile actuelle, et l'application hôte l'affiche. Le bouton renvoie l'utilisateur à la liste d'en-têtes de la fiche.

L'organisation de cette carte peut s'avérer efficace si votre module complémentaire n'a pas besoin de passer d'une fiche à une autre. Toutefois, dans la plupart des cas, il est préférable de définir directement les transitions de carte, et de faire en sorte que votre page d'accueil et vos fonctions de déclenchement contextuel renvoient un objet de carte unique.

Exemple

Voici un exemple montrant comment créer plusieurs fiches avec des boutons de navigation permettant de passer de l'une à l'autre. Ces fiches peuvent être ajoutées à la pile contextuelle ou non contextuelle en envoyant la carte renvoyée par createNavigationCard() dans un contexte particulier ou en dehors.

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