Créer des fiches interactives

Outre la présentation des données, la plupart des modules complémentaires nécessitent que l'utilisateur saisisse des informations. Lorsque vous créez un module complémentaire basé sur une carte, vous pouvez utiliser des widgets interactifs, comme des boutons, des éléments du menu de la barre d'outils ou des cases à cocher pour demander à l'utilisateur des données que votre module complémentaire ou fournissent d'autres contrôles d'interaction.

Ajouter des actions aux widgets

Pour la plupart, vous rendez les widgets interactifs en les liant à actions spécifiques et implémenter le comportement requis dans un rappel . Pour en savoir plus, consultez la section Actions des modules complémentaires.

Dans la plupart des cas, vous pouvez suivre cette procédure générale pour configurer un widget afin que effectuer une action spécifique lorsque cette option est sélectionnée ou mise à jour:

1. Créez un objet Action. spécifier la fonction de rappel à exécuter, ainsi que les paramètres obligatoires.
2. Associez le widget à Action en appelant la méthode fonction de gestionnaire de widgets.
3. Implémenter la fonction de rappel pour adopter le comportement requis.

Exemple

L'exemple suivant définit un bouton qui affiche une notification utilisateur après avoir cliqué dessus. Le clic déclenche la fonction de rappel notifyUser() avec un argument qui spécifie le texte de la notification. Renvoyer un build ActionResponse entraîne l'affichage d'une notification.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText))
        .build();      // Don't forget to build the response!
  }

Concevoir des interactions efficaces

Lorsque vous concevez des fiches interactives, tenez compte des points suivants:

• Les widgets interactifs ont généralement besoin d'au moins une méthode de gestionnaire pour définir leur comportemental.

• Utiliser le widget setOpenLink() lorsque vous avez une URL et que vous souhaitez simplement l'ouvrir dans un onglet. Ainsi, il n'est pas nécessaire de définir Objet et rappel Action . Si vous devez d'abord créer l'URL ou prendre d'autres avant d'ouvrir l'URL, définissez une Action et utilisez setOnClickOpenLinkAction() à la place.

• Lorsque vous utilisez setOpenLink() ou setOnClickOpenLinkAction() fonctions de gestionnaire de widgets, vous devez fournir OpenLink pour définir l'URL à ouvrir. Vous pouvez également utiliser cet objet pour spécifier le comportement d'ouverture et de fermeture à l'aide de la méthode OpenAs et OnClose.

• Plusieurs widgets peuvent utiliser le même objet Action. Cependant, vous devez définir différentes des objets Action si vous souhaitez pour fournir à la fonction de rappel différents paramètres.

• Optez pour des fonctions de rappel simples. Pour que les modules complémentaires restent responsifs, Le service de cartes limite les fonctions de rappel à 30 secondes au maximum le temps d'exécution. Si l'exécution prend plus de temps, l'UI du module complémentaire peut ne met pas correctement à jour l'affichage de sa carte en réponse à Action

• Si l'état des données sur un backend tiers change en raison de la présence d'un utilisateur avec l'interface utilisateur de votre module complémentaire, il est recommandé que celui-ci un "état modifié" le bit sur true afin que tout cache côté client existant soit effacés. Consultez le ActionResponseBuilder.setStateChanged() .