Navigation dans les fiches

La plupart des modules complémentaires basés sur des cartes sont conçus Des fiches représentant différentes "pages" des de ce module complémentaire. Pour avoir une expérience utilisateur efficace, utilisez une navigation simple et naturelle entre les cartes de votre module complémentaire.

À l'origine dans les modules complémentaires Gmail, les transitions entre les différentes cartes de l'interface utilisateur en poussant et en faisant glisser des cartes vers et depuis une seule pile de cartes, avec le carte supérieure de la pile affichée par Gmail.

Fiche de navigation de la page d'accueil

Lancement des modules complémentaires Google Workspace pages d'accueil et les fiches sans contexte. Pour intégrer les fiches contextuelles et non contextuelles, Les modules complémentaires Google Workspace disposent d'une pile de cartes interne pour chacune d'entre elles. Lorsqu'un module complémentaire est ouvert dans un hôte, le homepageTrigger correspondant se déclenche pour créer la première carte de la page d'accueil sur la pile (la carte "page d'accueil" bleu foncé dans le diagramme ci-dessous). Si aucun homepageTrigger n'est défini, une carte par défaut est créée et affichée, et transféré vers la pile non contextuelle. Cette première carte est une carte racine.

Votre module complémentaire peut créer d'autres fiches non contextuelles et les placer sur (les "cartes push" bleues sur le diagramme) lorsque l'utilisateur la fait défiler votre module complémentaire. L'interface utilisateur du module complémentaire affiche la carte du haut de la pile. dans la pile, l'affichage change, et le fait de faire sortir les cartes de la pile revient à l'affichage aux cartes précédentes.

Si votre module complémentaire dispose d'un déclencheur contextuel, lorsque l'utilisateur entre dans ce contexte, le déclencheur s'active. La fonction de déclencheur crée la fiche contextuelle, mais l'affichage de l'interface utilisateur est mis à jour en fonction DisplayStyle de la nouvelle fiche:

  • Si le DisplayStyle est REPLACE (valeur par défaut), la fiche contextuelle (en orange foncé) "contextuel" dans le diagramme) remplace les composants actuellement s'affiche. Cela lance efficacement une nouvelle pile de cartes contextuelles en haut de la pile de fiches non contextuelles. Cette fiche contextuelle est la racine de la pile contextuelle.
  • Si le DisplayStyle est PEEK, l'interface utilisateur crée un en-tête qui apparaît à la place en bas de la barre latérale du module complémentaire, par-dessus la fiche actuelle. En-tête de l'aperçu affiche le titre de la nouvelle fiche et fournit aux utilisateurs des boutons permettant peuvent décider d'afficher ou non la nouvelle fiche. S'il clique sur le bouton Afficher , la carte remplace la carte actuelle (comme décrit ci-dessus par REPLACE).

Vous pouvez créer des fiches contextuelles supplémentaires et placez-les sur la pile (les "cartes insérées" jaunes sur le diagramme). Mise à jour... la pile de cartes modifie l'UI du module complémentaire pour afficher la carte la plus élevée. Si l'utilisateur laisse un contexte, les fiches contextuelles de la pile sont supprimées et l'affichage des mises à jour de la fiche ou de la page d'accueil non contextuelle principale.

Si l'utilisateur saisit un contexte que votre module complémentaire ne définit pas sur le déclencheur contextuel, aucune fiche n'est créée et la carte actuelle reste affichée.

Les actions Navigation décrits ci-dessous, n'interviennent que sur les cartes s'apparentant au même contexte. Exemple : popToRoot() À partir d'une fiche contextuelle, seules les autres fiches contextuelles s'affichent. sans aucune incidence sur les fiches de la page d'accueil.

En revanche, le bouton toujours à la disposition de l'utilisateur pour qu'il puisse naviguer de vos fiches contextuelles les fiches sans contexte.

Vous pouvez créer des transitions entre les fiches en ajoutant ou en supprimant des fiches dans piles de cartes. Navigation fournit des fonctions pour transférer et insérer des cartes depuis les piles. Pour compiler une navigation efficace par carte, vous configurez Widgets pour utiliser la navigation actions. Vous pouvez pousser ou appuyer plusieurs fiches simultanément, mais vous ne pouvez pas supprimer la fiche de la page d'accueil initiale qui est d'abord transféré 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 : procédez comme suit:

  1. Créer un objet Action et l'associer à un fonction de rappel que vous définissez.
  2. Appelez la méthode Fonction de gestionnaire de widgets pour définir le Action sur ce widget.
  3. Implémentez la fonction de rappel qui effectue la navigation. Cette fonction reçoit un objet d'événement d'action. en tant qu'argument et doit procéder comme suit: <ph type="x-smartling-placeholder">
      </ph>
    1. Créer un Navigation pour définir le changement de carte. Un seul objet Navigation peut contenir plusieurs étapes de navigation, qui sont réalisées dans l'ordre elles sont ajoutées à l'objet.
    2. Créer une ActionResponse à l'aide de l'objet ActionResponseBuilder et le Navigation .
    3. Renvoyez les ActionResponse

Lorsque vous créez des commandes de navigation, vous utilisez les éléments suivants : Fonctions d'objet Navigation:

Fonction Description
Navigation.pushCard(Card) Ajoute une carte à la pile actuelle. Pour cela, vous devez d'abord créer la carte.
Navigation.popCard() Supprime une carte du haut de la pile. Équivaut à cliquer sur la flèche de retour dans la ligne d'en-tête du module complémentaire. Cela 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'à ce qu'elles atteignent une carte portant le nom donné 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) Effectue un remplacement sur place de la carte actuelle, en rafraîchissant son affichage dans l'interface utilisateur.

Si une interaction ou un événement utilisateur doit entraîner un nouvel affichage des fiches dans le même le contexte, utilisez Navigation.pushCard() Navigation.popCard(), et Navigation.updateCard() pour remplacer les fiches existantes. Si une interaction ou un événement utilisateur doit les cartes s'affichent dans un contexte différent, 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 plus de détails ou invite l'utilisateur à Action supplémentaire (par exemple, cliquer sur le titre d'un élément pour afficher plus de détails) 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 la quitter à l'aide de la méthode bouton retour.
  • Si l'état d'une interaction ou d'un événement est modifié dans une fiche précédente (par exemple, en mettant à jour le titre d'un article en y ajoutant la vue détaillée), utilisez un texte du type popCard() popCard(), pushCard(previous), et pushCard(current) pour mettre à jour la carte précédente et la carte actuelle.

Actualisation des fiches...

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

Barre latérale du module complémentaire Google Workspace

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

Retourner plusieurs cartes

Exemple de carte complémentaire

Les fonctions de page d'accueil ou de déclencheur contextuel sont utilisées pour créer et renvoyer un seul un objet Card ou un tableau de Objets Card que le s'affiche.

S'il n'y a qu'une seule fiche, elle est ajoutée à la pile non contextuelle ou contextuelle en tant que carte racine et l'UI de l'application hôte l'affiche.

Si le tableau renvoyé inclut plusieurs éléments Card l'application hôte affiche à la place une nouvelle carte, qui contient liste des en-têtes de chaque fiche. Lorsque l'utilisateur clique sur l'un de ces en-têtes, l'UI affiche la fiche correspondante.

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

Ce plat l'organisation des cartes peut être efficace si votre module complémentaire n'a pas besoin les transitions entre les fiches que vous créez. Dans la plupart des cas, il vaut mieux entraînez-vous à définir directement les transitions entre les fiches, et à avoir votre page d'accueil et Les fonctions de déclenchement contextuel renvoient un objet Card unique.

Exemple

Voici un exemple qui montre comment créer plusieurs cartes avec la navigation boutons qui passent de l’une à l’autre. Vous pouvez ajouter ces cartes 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();
  }