Actions complémentaires

Les actions des modules complémentaires offrent un comportement interactif 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 Action fournis par le service Card d'Apps Script. Chaque Action est associé à une fonction de rappel lorsque vous la créez. Vous implémenterez la fonction de rappel d'effectuer les actions 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, définit le type d'interaction qui déclenche Rappel de Action.

Configurer un widget avec un Action en procédant comme suit:

1. Créez l'objet Action. spécifiant la fonction de rappel à utiliser s’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 la commande Action .
3. Implémentez la fonction de rappel pour appliquer le comportement requis.

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

Fonctions du gestionnaire de widgets

Associer un widget à un Action spécifique ou tout autre comportement, utilisez un widget . La fonction "handler" détermine le type d'interaction (par exemple, si vous cliquez sur le widget ou modifiez un champ de texte) déclenche le comportement de l'utilisateur. La fonction de gestionnaire définit également les étapes suivies 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 quels widgets avec lesquels ils sont utilisés:

Fonction de gestionnaire	Déclenche une 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 n'est plus sélectionné, comme lorsque l'utilisateur saisit du texte et appuie sur Entrée. La transmet automatiquement un objet event à la fonction qu'il appelle. Vous pouvez insérer d'autres informations sur les paramètres 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. La transmet automatiquement un objet event à la fonction qu'il appelle. Vous pouvez insérer des informations sur les paramètres facultatifs 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 Fenêtre de rédaction de l'interface utilisateur de Gmail. Vous pouvez créer le brouillon sous la forme d'un nouveau message répondre au message ouvert dans Gmail. Lorsque le gestionnaire appelle la méthode de création de brouillons, elle transmet objet event à la fonction de rappel. Voir Rédiger des brouillons pour en savoir plus.
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 doit construire l'URL ou que d'autres actions doivent avoir lieu avant que le lien ouvre ; sinon il est généralement plus simple d'utiliser setOpenLink(). Vous ne pouvez ouvrir l'URL que dans une nouvelle fenêtre. Lorsqu'elle est fermée, UI pour 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. Utiliser ceci 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. Une fois fermé, vous peut amener l'UI à recharger 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 une objet event à la fonction qu'il appelle. Voir Suggestions de saisie semi-automatique pour les entrées de texte.

Fonctions de rappel

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

Avertissement :Le service Card d'Apps Script limite les fonctions de rappel à un maximum de 30 secondes de temps d'exécution. Si l'exécution dure plus longtemps, l'UI du module complémentaire risque de ne pas mettre à jour la carte s'affiche correctement 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 se produire après L'exécution du rappel se termine, par exemple l'affichage d'une nouvelle carte ou la présentation des suggestions de saisie semi-automatique. Lorsque votre fonction de rappel doit renvoyer une valeur vous utilisez une classe "Builder" dans le service Card pour construire cet objet.

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

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

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

• Actions d'agenda
• Inciter à des actions
• Actions Gmail
• Actions de l'éditeur

Remarque :Lorsque vous utilisez les classes du compilateur de réponses, veillez à appeler build() pour génèrent 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 de l'option Action mais leurs fonctions de rappel doivent renvoyer UniversalActionResponse.

Objets d'événement 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 que un argument au rappel Action . Cet objet "événement" contient des informations sur l'événement le contexte côté client, comme les valeurs actuelles de toutes les tables interactives widgets dans la fiche qui s'affiche.

Les objets d'événement d'action ont une structure JSON spécifique qui organise les les informations qu'ils contiennent. La même structure est utilisée lorsqu'un déclencheur de la 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.

Consultez la section Objets "Événement" pour en savoir plus de la structure de l'objet é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é, toutes les versions Les champs d'objet d'événement des modules complémentaires Gmail sont toujours contenus dans le nouvel événement structure d'objet d'événement (voir Structure des objets d'événement). Cependant, les mêmes informations sont reproduites dans le événement commun et événement Gmail sous-structures d'objets. Si vous convertissez un module complémentaire Gmail en module complémentaire Google Workspace, vous devez ajuster votre code à utiliser les champs d'objet d'événement mis à jour, à terme les champs Gmail d'origine les champs d'objet d'événement seront supprimés.