Cette page a été traduite par l'API Cloud Translation.

Actions complémentaires

Les actions de modules 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 de module complémentaire à l'aide d'objets Action fournis par le service Card d'Apps Script. Chaque Action est associé à une fonction de rappel lorsque vous le 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 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.

Configurez un widget avec un Action en suivant cette procédure générale :

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

Pour associer un widget à un Action spécifique ou à un autre comportement, vous 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'UI, 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 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 perd le focus, 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. Vous pouvez insérer des informations de paramètre supplémentaires dans cet objet d'événement si vous le souhaitez.
`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 sur les paramètres facultatifs 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'UI Gmail. Vous pouvez rédiger 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 Rédiger des brouillons de messages Compose.
`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 construire 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. Lorsque vous le fermez, vous pouvez forcer l'UI à recharger 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 uniquement besoin de l'ouvrir. Sinon, utilisez `setOnClickOpenLinkAction()`. Vous pouvez ouvrir l'URL dans une nouvelle fenêtre ou dans un calque. Lorsqu'il est fermé, vous pouvez forcer l'UI à recharger le module complémentaire.
`setSuggestionsAction()`	L'utilisateur saisit du texte dans un champ de saisie.	`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 saisies de texte.

Fonctions de rappel

Les fonctions de rappel s'exécutent lorsqu'un Action se déclenche. Étant donné que les fonctions de rappel sont des fonctions Apps Script, vous pouvez leur faire faire presque tout ce que n'importe quelle autre fonction de script peut faire.

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 après l'exécution du rappel, comme l'affichage d'une nouvelle fiche 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 construire 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
Naviguer entre les fiches	`ActionResponse`
Afficher un `Notification`	`ActionResponse`
Ouvrir un lien à l'aide de `setOnClickOpenLinkAction()`	`ActionResponse`
Afficher les suggestions de saisie semi-automatique	`SuggestionResponse`
Utiliser une action universelle	`UniversalActionResponse`
Autres actions	Nothing

Actions pour les applications hôtes Google Workspace

En plus de 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 :

Objets d'événement d'action

Lorsque votre module complémentaire déclenche un Action, l'interface utilisateur 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 côté client actuel 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 se déclenche 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 Objets d'événement.

Remarque : 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 des modules complémentaires Gmail d'origine sont toujours inclus dans la nouvelle structure d'objet d'événement (voir Structure de l'objet d'événement). Toutefois, les mêmes informations sont reproduites dans les sous-structures d'objets common event (événement commun) et Gmail event (événement Gmail). Si vous mettez à niveau un module complémentaire Gmail en 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 seront supprimés à terme.