Actions complémentaires

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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ée à une fonction de rappel lorsque vous la créez. Vous mettez en œuvre 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 à l'aide de 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.

Fonctions du gestionnaire de widgets

Pour associer un widget à un Action spécifique ou à un autre comportement, vous devez utiliser une fonction de gestionnaire de widgets. 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 du gestionnaire définit également les étapes que l'interface utilisateur effectue, 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éclencher 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é, 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 des informations de paramètres supplémentaires dans cet objet d'é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 sur les paramètres facultatifs dans cet objet d'événement.
setComposeAction() L'utilisateur clique sur le widget. CardAction
Image
ImageButton
DecoratedText
TextButton
Fonctionnalités propres à Gmail. Définit un Action pour créer un brouillon d'e-mail, puis le présenter à l'utilisateur dans une fenêtre de rédaction de l'interface utilisateur de Gmail. Vous pouvez créer le brouillon en tant que nouveau message ou réponse au message ouvert dans Gmail. Lorsque le gestionnaire appelle la fonction de rappel de compilation, il transmet un objet d'événement à la fonction de rappel. Pour en savoir plus, consultez 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. Lorsqu'il est fermé, vous pouvez forcer l'UI à actualiser le module complémentaire.
setOpenLink() L'utilisateur clique sur le widget. CardAction
Image
ImageButton
DecoratedText
TextButton
Permet d'ouvrir directement une URL lorsque l'utilisateur clique sur le widget. Utilisez ce gestionnaire lorsque vous connaissez l'URL et que vous ne devez l'ouvrir que. Sinon, utilisez setOnClickOpenLinkAction(). Vous pouvez l'ouvrir dans une nouvelle fenêtre ou dans une superposition. Lorsqu'elle est fermée, l'interface utilisateur 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 la section Suggestions de saisie semi-automatique pour la saisie de texte.

Fonctions de rappel

Les fonctions de rappel s'exécutent lorsqu'un déclencheur Action est déclenché. Étant donné que les fonctions de rappel sont des fonctions Apps Script, vous pouvez leur donner accès à presque toutes les autres fonctions de script.

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, telles que 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 du service Card 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 cartes 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 Non applicable

En plus de ces actions, chaque application hôte dispose 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:

Objets d'événement d'action

Lorsque votre module complémentaire déclenche un objet 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 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 de contexte 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 page Objets d'événement.