Actions complémentaires

Les actions de module complémentaire offrent un comportement interactif aux widgets. En créant une action, vous définissez ce qui se passe lorsque l'utilisateur sélectionne ou met à jour un widget.

Dans la plupart des cas, vous pouvez définir des actions de module complémentaire à l'aide d' Action objets fournis par le service de cartes Google Apps Script. Chaque Action est associée à une fonction de rappel lorsque vous la créez. Vous implémentez la fonction de rappel pour effectuer les étapes sélectionnées lorsque l'utilisateur interagit avec le widget. Vous devez également associer le Action au widget à l'aide d'une fonction de gestionnaire de widget appropriée qui définit le type d'interaction qui déclenche le rappel Action.

Pour configurer un widget avec un Action , procédez comme suit :

  1. Créez l'Action objet, en spécifiant la fonction de rappel qu'il doit exécuter, ainsi que tous les paramètres requis.
  2. Appelez la fonction de gestionnaire de widget appropriée sur le widget à l'aide de l'objet Action.
  3. Implémentez la fonction de rappel pour appliquer le comportement requis.

Ne confondez pas les Action objets avec les CardAction objets. CardAction objets sont des éléments de menu d'en-tête de carte, tandis que Action objets définissent les réponses aux interactions de l'utilisateur avec l'interface utilisateur.

Fonctions de gestionnaire de widget

Pour associer un widget à un Action ou à un autre comportement, utilisez une fonction de gestionnaire de widget. La fonction de gestionnaire détermine le type d'interaction (par exemple, cliquer sur le widget ou modifier un champ de texte) qui déclenche le comportement de l'action. La fonction de gestionnaire définit également les étapes à suivre par l'interface utilisateur, le cas échéant, une fois l'action terminée.

Le tableau suivant répertorie les différents types de gestionnaires pour les widgets et les widgets avec lesquels ils sont utilisés :

Fonction de gestionnaire Déclenche l'action Widgets applicables Description
setOnChangeAction La valeur du widget change DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker 		Définit un Action qui exécute une fonction Apps Script lorsque le widget perd le focus, par exemple lorsque l'utilisateur saisit du texte dans un champ de saisie et appuie sur Entrée. Le gestionnaire transmet automatiquement un objet d'événement à la fonction qu'il appelle. Si vous le souhaitez, vous pouvez insérer des informations de paramètre supplémentaires dans cet objet d'événement si sélectionné.
setOnClickAction L'utilisateur clique sur le widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Définit une Action qui exécute une fonction Apps Script lorsque l'utilisateur clique sur le widget. Le gestionnaire transmet automatiquement un objet d'événement à la fonction qu'il appelle. Vous pouvez insérer des informations de paramètre facultatives dans cet objet d'événement.
setComposeAction L'utilisateur clique sur le widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Spécifique à Gmail. Définit un Action qui crée un brouillon d'e-mail, puis le présente à l'utilisateur dans une fenêtre de rédaction de l'interface utilisateur Gmail. Vous pouvez créer le brouillon sous forme de nouveau message ou de réponse au message ouvert dans Gmail. Lorsque le gestionnaire appelle la fonction de rappel de création de brouillon, il transmet un objet d'événement à la fonction de rappel. Pour en savoir plus, consultez la section Rédiger des brouillons de messages.
setOnClickOpenLinkAction L'utilisateur clique sur le widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Définit un Action pour ouvrir une URL lorsque l'utilisateur clique sur le widget. Utilisez ce gestionnaire lorsque vous devez créer l'URL ou que d'autres actions doivent avoir lieu avant l'ouverture du lien . Sinon, il est généralement plus simple d'utiliser setOpenLink. Vous ne pouvez ouvrir l'URL que dans une nouvelle fenêtre. Une fois fermée, vous pouvez faire en sorte que l' interface utilisateur recharge le module complémentaire.
setOpenLink L'utilisateur clique sur le widget CardAction
Image
ImageButton
DecoratedText
TextButton 		Ouvre directement une URL lorsque l'utilisateur clique sur le widget. Utilisez ce gestionnaire lorsque vous connaissez l'URL et que vous n'avez qu'à l'ouvrir. Sinon, utilisez setOnClickOpenLinkAction. Vous pouvez ouvrir l'URL dans une nouvelle fenêtre ou dans une superposition. Une fois fermée, vous pouvez faire en sorte que l'interface utilisateur recharge le module complémentaire.
setSuggestionsAction L'utilisateur saisit du texte dans un champ de saisie TextInput Définit une Action qui exécute une fonction Apps Script lorsque l'utilisateur saisit du texte dans un widget de saisie de texte. Le gestionnaire transmet automatiquement un objet d'événement à la fonction qu'il appelle. Pour en savoir plus, consultez la section Suggestions de saisie semi-automatique pour les entrées de texte.

Fonctions de rappel

Les fonctions de rappel s'exécutent lorsqu'un Action est déclenché. Étant donné que les fonctions de rappel sont des fonctions Apps Script, vous pouvez les utiliser pour effectuer presque toutes les actions qu'une autre fonction de script peut effectuer.

Une fonction de rappel renvoie parfois un objet de réponse spécifique. Ces types de réponses indiquent des opérations supplémentaires qui doivent avoir lieu une fois l'exécution du rappel terminée, comme l'affichage d'une nouvelle carte ou la présentation de suggestions de saisie semi-automatique. Lorsque votre fonction de rappel doit renvoyer un objet de réponse spécifique, vous utilisez une classe de compilateur dans le service de cartes pour créer cet objet.

Le tableau suivant indique quand vos fonctions de rappel doivent renvoyer un objet de réponse spécifique pour des actions spécifiques. Ces actions sont toutes indépendantes de l'application hôte spécifique que le module complémentaire étend :

Action tentée La fonction de rappel doit renvoyer
Navigation ActionResponse
Afficher une Notification ActionResponse
Ouvrir un lien à l'aide de setOnClickOpenLinkAction ActionResponse
Afficher des suggestions de saisie semi-automatique SuggestionResponse
Utiliser une action universelle UniversalActionResponse
Autres actions Nothing

Actions pour les applications hôtes Google Workspace

Outre ces actions, chaque application hôte possède son propre ensemble d'actions qui ne peuvent être effectuées que dans cet hôte. Pour en savoir plus, consultez les guides suivants :

Lorsque vous utilisez les classes de compilateur de réponse, appelez la méthode build pour générer les objets de réponse. Dans le cas contraire, une erreur se produira.

Les actions universelles sont définies dans le fichier manifeste du projet et n'ont pas besoin Action d'objets, mais leurs fonctions de rappel doivent renvoyer une UniversalActionResponse.

Objets d'événement d'action

Lorsque votre module complémentaire déclenche un Action, l'interface utilisateur crée automatiquement un objet d'événement JSON et le transmet en tant qu'argument à la fonction de rappel Action. Cet objet d'événement contient des informations sur le contexte actuel côté client de l'utilisateur, telles que les valeurs actuelles de tous les widgets interactifs de la carte affichée.

Les objets d'événement d'action ont une structure JSON spécifique qui organise les informations qu'ils contiennent. La même structure est utilisée lorsqu'un déclencheur de page d'accueil est activé pour créer une page d'accueil ou lorsqu'un déclencheur contextuel est activé pour mettre à jour l'affichage du module complémentaire.

Pour obtenir une explication complète de la structure de l'objet d'événement, consultez la section Objets d'événement.

Les modules complémentaires Gmail utilisaient une version simplifiée de cette structure d'objet d'événement, qui est désormais obsolète. Pour assurer la rétrocompatibilité, tous les champs d'objet d'événement d'origine des modules complémentaires Gmail sont toujours contenus dans la nouvelle structure d'objet d'événement (voir la structure d'objet d'événement). Toutefois, les mêmes informations sont reproduites dans les commonEventObject et objet d'événement Gmail sous-structures. Si vous mettez à niveau un module complémentaire Gmail vers un module complémentaire Google Workspace, ajustez votre code pour utiliser les champs d'objet d'événement mis à jour. À terme, les champs d'objet d'événement Gmail d'origine seront supprimés.