Actions complémentaires

Les actions complémentaires fournissent 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 complémentaires à l'aide d'objets Action fournis par le service Card d'Apps Script. Chaque Action est associé à une fonction de rappel lorsque vous la créez. Vous implémentez la fonction de rappel pour effectuer les étapes souhaitées lorsque l'utilisateur interagit avec le widget. Vous devez également associer Action au widget à l'aide d'une fonction de gestionnaire de widgets appropriée qui définit le type d'interaction qui déclenche le rappel Action.

Configurez un widget avec un Action en suivant ce processus général:

1. Créez l'objet Action 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 widgets appropriée sur le widget à l'aide de l'objet Action.
3. Implémentez la fonction de rappel pour appliquer le comportement requis.

Remarque :Ne confondez pas les objets Action avec les objets CardAction. Les objets CardAction sont des éléments de menu de l'en-tête de fiche, tandis que les objets Action définissent les réponses aux interactions des utilisateurs avec l'UI.

Fonctions de gestionnaire de widgets

Pour associer un widget à un Action spécifique ou à un autre comportement, utilisez une fonction de gestionnaire de widgets. La fonction de gestionnaire détermine le type d'interaction (par exemple, un clic sur le widget ou la modification d'un champ de texte) qui déclenche le comportement de l'action. La fonction handler définit également les étapes effectuées 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 de widgets et les widgets avec lesquels ils sont utilisés:

Fonction du gestionnaire	Déclenche une action	Widgets concernés	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 n'est plus sélectionné, par exemple lorsque l'utilisateur saisit du texte dans une entrée 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 d'autres informations de paramètre dans cet objet événement.
setOnClickAction()	L'utilisateur clique sur le widget.	CardAction Image ImageButton DecoratedText TextButton	Définit un 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 é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 dans l'interface utilisateur de Gmail. Vous pouvez créer le brouillon en tant que nouveau message ou en réponse au message ouvert dans Gmail. Lorsque le gestionnaire appelle la fonction de rappel du bâtiment de brouillon, il transmet un objet d'événement à la fonction de rappel. Pour en savoir plus, consultez la section Rédiger des brouillons.
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. Dans le cas contraire, il est généralement plus simple d'utiliser setOpenLink(). Vous ne pouvez ouvrir l'URL que dans une nouvelle fenêtre. Lorsqu'il est fermé, l'UI peut actualiser 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 avez seulement besoin de l'ouvrir. Sinon, utilisez setOnClickOpenLinkAction(). Vous pouvez ouvrir l'URL dans une nouvelle fenêtre ou en superposition. Lorsqu'il est fermé, l'UI peut actualiser le module complémentaire.
setSuggestionsAction()	L'utilisateur saisit du texte dans une entrée.	TextInput	Définit un 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 Suggestions de saisie semi-automatique pour les entrées de texte.

Fonctions de rappel

Les fonctions de rappel s'exécutent lorsqu'un Action se déclenche. Les fonctions de rappel étant des fonctions Apps Script, elles peuvent faire presque n'importe quelle autre fonction de script.

Avertissement :Le service de cartes Apps Script limite les fonctions de rappel à un temps d'exécution maximal de 30 secondes. Si l'exécution prend plus de temps, l'interface utilisateur de votre module complémentaire risque de ne pas mettre à jour correctement l'affichage de sa fiche en réponse à la réponse Action.

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 être effectuées 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 pouvez utiliser une classe de compilateur dans le service de carte pour construire cet objet.

Le tableau suivant indique à quel moment 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 étendue par le module complémentaire:

Tentative d'action	La fonction de rappel doit renvoyer
Parcourir les fiches	ActionResponse
Afficher un Notification	ActionResponse
Ouvrir un lien avec setOnClickOpenLinkAction()	ActionResponse
Afficher des suggestions de saisie semi-automatique	SuggestionResponse
Utiliser une action universelle	UniversalActionResponse
Autres actions	Nothing

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

• Actions d'agenda
• Actions de type Drive
• Actions dans Gmail
• Actions de l'éditeur

Remarque :Lorsque vous utilisez les classes du compilateur de réponse, veillez à appeler build() pour générer les objets de réponse. Si vous ne le faites pas, une erreur se produit.

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

Objets d'événements d'action

Lorsque votre module complémentaire déclenche une Action, l'UI construit 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 fiche 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 s'exécute pour créer une page d'accueil, ou lorsqu'un déclencheur contextuel se déclenche pour mettre à jour l'affichage du module complémentaire.

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

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