Étendre l'interface utilisateur de rédaction avec des actions de rédaction

En plus de fournir une interface sous forme de carte lorsqu'un utilisateur lit un message Gmail, les modules complémentaires Google Workspace qui étendent Gmail peuvent fournir une autre interface lorsque l'utilisateur rédige de nouveaux messages ou répond à des messages existants. Les modules complémentaires Google Workspace peuvent ainsi automatiser la rédaction des e-mails pour l'utilisateur.

Accéder à l'interface utilisateur de Compose du module complémentaire

Il existe deux façons d'afficher l'interface utilisateur de Compose d'un module complémentaire. La première consiste à commencer à rédiger un brouillon ou à répondre alors que le module complémentaire est déjà ouvert. La deuxième façon consiste à démarrer le module complémentaire pendant la rédaction d'un brouillon.

Dans les deux cas, le module complémentaire exécute la fonction de déclencheur de Compose correspondante, définie dans le fichier manifeste du module complémentaire. La fonction de déclencheur Compose crée l'interface utilisateur de Compose pour cette action de rédaction, que Gmail affiche ensuite à l'utilisateur.

Créer un module complémentaire Compose

Pour ajouter la fonctionnalité de rédaction à un module complémentaire, procédez comme suit:

1. Ajoutez le champ gmail.composeTrigger au fichier manifeste du projet de module complémentaire et mettez à jour les champs d'application du fichier manifeste pour inclure ceux requis pour les actions de composition.
2. Implémentez une fonction de déclencheur Compose qui crée une interface utilisateur Compose lorsque le déclencheur est exécuté. Les fonctions de déclenchement de Compose renvoient un seul objet Card ou un tableau d'objets Card qui constituent l'interface utilisateur de Compose pour l'action Compose.
3. Implémentez les fonctions de rappel associées nécessaires pour réagir aux interactions de l'utilisateur avec l'interface utilisateur Compose. Il ne s'agit pas de l'action Compose elle-même (ce qui déclenche uniquement l'affichage de l'UI Compose). Il s'agit de fonctions individuelles qui régissent ce qui se passe lorsque différents éléments de l'UI Compose sont sélectionnés. Par exemple, une carte d'interface utilisateur contenant un bouton est généralement associée à une fonction de rappel qui s'exécute lorsqu'un utilisateur clique dessus. La fonction de rappel des widgets qui mettent à jour le contenu du brouillon du message doit renvoyer un objet UpdateDraftActionResponse.

Saisir une fonction de déclencheur

L'interface utilisateur de Compose d'un module complémentaire est conçue de la même manière que l'UI de message du module complémentaire, à l'aide du service de cartes Apps Script pour créer des fiches et les remplir avec des widgets.

Vous devez implémenter l'élément gmail.composeTrigger.selectActions[].runFunction que vous avez défini dans votre fichier manifeste. La fonction de déclencheur de Compose doit renvoyer un seul objet Card ou un tableau d'objets Card qui composent l'interface utilisateur de Compose pour cette action. Ces fonctions sont très semblables aux fonctions de déclencheur contextuel et devraient créer des fiches de la même manière.

Avertissement :Pour des raisons de sécurité, les modules complémentaires ne peuvent pas modifier silencieusement les autorisations d'accès à Google Workspace ni aux fichiers tiers. Par exemple, un module complémentaire ne peut pas ajouter silencieusement des destinataires d'e-mails à l'ensemble de comptes autorisés à afficher un fichier Dropbox. Au lieu de cela, il doit informer les utilisateurs que la modification des autorisations est en cours. Les modules complémentaires qui n'informent pas les utilisateurs de ces modifications ne peuvent pas être examinés.

Saisir des objets d'événement déclencheur

Lorsqu'une action Compose est sélectionnée, elle exécute la fonction de déclenchement de Compose correspondante et transmet à la fonction un objet d'événement en tant que paramètre. L'objet événement peut contenir des informations sur le contexte du module complémentaire et la composition du brouillon vers la fonction de déclencheur.

Pour en savoir plus sur la disposition des informations dans l'objet événement, consultez Structure de l'objet événement. Les informations contenues dans l'objet événement sont partiellement contrôlées par la valeur du champ gmail.composeTrigger.draftAccess du fichier manifeste:

• Si le champ du fichier manifeste gmail.composeTrigger.draftAccess est NONE ou n'est pas inclus, l'objet événement ne contient que des informations minimales.

• Si gmail.composeTrigger.draftAccess est défini sur METADATA, l'objet d'événement transmis à la fonction de déclencheur de Compose est renseigné avec les listes des destinataires de l'e-mail en cours de composition.

Remarque :Pour utiliser l'accès au brouillon de METADATA, le fichier manifeste du module complémentaire doit inclure le champ d'application Gmail de https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

Insérer du contenu dans les brouillons actifs

Généralement, l'interface utilisateur de rédaction d'un module complémentaire Google Workspace fournit les options et les commandes qui permettent à l'utilisateur de rédiger un message. Dans ces cas d'utilisation, une fois que l'utilisateur a effectué des sélections dans l'interface utilisateur, le module complémentaire interprète ces sélections et met à jour le brouillon d'e-mail fonctionnel en conséquence.

Pour faciliter la mise à jour du brouillon actuel, le service de cartes a été étendu avec les classes suivantes:

• ContentType : énumération qui définit s'il faut ajouter du code HTML modifiable, du code HTML immuable (que les utilisateurs de Gmail ne peuvent pas modifier) ou du contenu en texte brut.
• UpdateDraftActionResponse : représente une réponse à une action qui met à jour le brouillon actuel.
• UpdateDraftActionResponseBuilder : compilateur pour les objets UpdateDraftActionResponse.
• UpdateDraftBodyAction : représente une action qui met à jour le corps du brouillon actuel.
• UpdateDraftBodyType : énumération qui définit la manière dont le corps est modifié.
• UpdateDraftSubjectAction : représente une action qui met à jour le champ d'objet du brouillon actuel.
• UpdateDraftToRecipientsAction : représente une action qui met à jour le champ "À" du brouillon actuel.
• UpdateDraftCcRecipientsAction : représente une action qui met à jour les destinataires en copie du brouillon actuel.
• UpdateDraftBccRecipientsAction : représente une action qui met à jour les destinataires en Cci du brouillon actuel.

Généralement, l'interface utilisateur de Compose d'un module complémentaire inclut un widget "Enregistrer" ou "Insérer" sur lequel l'utilisateur peut cliquer pour indiquer qu'il a terminé ses sélections dans l'interface utilisateur et que ses choix sont ajoutés à l'e-mail qu'il est en train de rédiger. Pour ajouter cette interactivité, le widget doit être associé à un objet Action qui demande au module complémentaire d'exécuter une fonction de rappel spécifique lorsque l'utilisateur clique sur le widget. Vous devez implémenter ces fonctions de rappel. Chaque fonction de rappel doit renvoyer un objet UpdateDraftActionResponse créé qui détaille les modifications à apporter au brouillon actuel.

Exemple 1

L'extrait de code suivant montre comment créer une interface utilisateur de rédaction qui met à jour l'objet et les destinataires du brouillon d'e-mail actuel, ainsi que les destinataires en Cc et en Cci.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getComposeUI(e) {
      return [buildComposeCard()];
    }

    /**
     * Build a card to display interactive buttons to allow the user to
     * update the subject, and To, Cc, Bcc recipients.
     *
     * @return {Card}
     */
    function buildComposeCard() {

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('Update email');
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update subject')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('applyUpdateSubjectAction')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update To recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateToRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Cc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateCcRecipients')));
      cardSection.addWidget(
          CardService.newTextButton()
              .setText('Update Bcc recipients')
              .setOnClickAction(CardService.newAction()
                  .setFunctionName('updateBccRecipients')));
      return card.addSection(cardSection).build();
    }

    /**
     * Updates the subject field of the current email when the user clicks
     * on "Update subject" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateSubjectAction() {
      // Get the new subject field of the email.
      // This function is not shown in this example.
      var subject = getSubject();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftSubjectAction(CardService.newUpdateDraftSubjectAction()
              .addUpdateSubject(subject))
          .build();
      return response;
    }

    /**
     * Updates the To recipients of the current email when the user clicks
     * on "Update To recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateToRecipientsAction() {
      // Get the new To recipients of the email.
      // This function is not shown in this example.
      var toRecipients = getToRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftToRecipientsAction(CardService.newUpdateDraftToRecipientsAction()
              .addUpdateToRecipients(toRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Cc recipients  of the current email when the user clicks
     * on "Update Cc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateCcRecipientsAction() {
      // Get the new Cc recipients of the email.
      // This function is not shown in this example.
      var ccRecipients = getCcRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftCcRecipientsAction(CardService.newUpdateDraftCcRecipientsAction()
              .addUpdateToRecipients(ccRecipients))
          .build();
      return response;
    }

    /**
     * Updates the Bcc recipients  of the current email when the user clicks
     * on "Update Bcc recipients" in the compose UI.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @return {UpdateDraftActionResponse}
     */
    function applyUpdateBccRecipientsAction() {
      // Get the new Bcc recipients of the email.
      // This function is not shown in this example.
      var bccRecipients = getBccRecipients();
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBccRecipientsAction(CardService.newUpdateDraftBccRecipientsAction()
              .addUpdateToRecipients(bccRecipients))
          .build();
      return response;
    }

Exemple 2

L'extrait de code suivant montre comment créer une interface utilisateur Compose qui insère des images dans le brouillon actuel.

    /**
     * Compose trigger function that fires when the compose UI is
     * requested. Builds and returns a compose UI for inserting images.
     *
     * @param {event} e The compose trigger event object. Not used in
     *         this example.
     * @return {Card[]}
     */
    function getInsertImageComposeUI(e) {
      return [buildImageComposeCard()];
    }

    /**
     * Build a card to display images from a third-party source.
     *
     * @return {Card}
     */
    function buildImageComposeCard() {
      // Get a short list of image URLs to display in the UI.
      // This function is not shown in this example.
      var imageUrls = getImageUrls();

      var card = CardService.newCardBuilder();
      var cardSection = CardService.newCardSection().setHeader('My Images');
      for (var i = 0; i < imageUrls.length; i++) {
        var imageUrl = imageUrls[i];
        cardSection.addWidget(
            CardService.newImage()
                .setImageUrl(imageUrl)
                .setOnClickAction(CardService.newAction()
                      .setFunctionName('applyInsertImageAction')
                      .setParameters({'url' : imageUrl})));
      }
      return card.addSection(cardSection).build();
    }

    /**
     * Adds an image to the current draft email when the image is clicked
     * in the compose UI. The image is inserted at the current cursor
     * location. If any content of the email draft is currently selected,
     * it is deleted and replaced with the image.
     *
     * Note: This is not the compose action that builds a compose UI, but
     * rather an action taken when the user interacts with the compose UI.
     *
     * @param {event} e The incoming event object.
     * @return {UpdateDraftActionResponse}
     */
    function applyInsertImageAction(e) {
      var imageUrl = e.parameters.url;
      var imageHtmlContent = '<img style=\"display: block\" src=\"'
           + imageUrl + '\"/>';
      var response = CardService.newUpdateDraftActionResponseBuilder()
          .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
              .addUpdateContent(
                  imageHtmlContent,
                  CardService.ContentType.MUTABLE_HTML)
              .setUpdateType(
                  CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
          .build();
      return response;
    }