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

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

En plus de fournir une interface basée sur une carte lorsqu'un utilisateur lit un message Gmail, Google Workspace des modules complémentaires qui étendent Gmail peuvent fournir une autre interface lorsque l'utilisateur rédige de nouveaux messages ou répond à des messages existants. Cela permet aux modules complémentaires Google Workspace d'automatiser la rédaction des e-mails.

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

Il existe deux façons d'afficher l'interface utilisateur de rédaction d'un module complémentaire. La première consiste à rédiger un nouveau brouillon ou à répondre tant que le module complémentaire est déjà ouvert. La seconde consiste à démarrer le module complémentaire lorsque vous rédigez un brouillon.

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

Créer un module complémentaire Compose

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

  1. Ajoutez le champ gmail.composeTrigger au fichier manifeste du projet de script du module complémentaire, puis 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éclenchement de composition qui crée une interface utilisateur de rédaction lors de l'exécution du déclencheur. Les fonctions de déclenchement de Compose renvoient un seul objet Card ou un tableau d'objets Card comprenant l'UI de Compose pour l'action de composition.
  3. Implémentez les fonctions de rappel associées nécessaires pour réagir aux interactions de l'utilisateur dans l'interface utilisateur. Il ne s'agit pas de l'action de composition proprement dite (qui entraîne uniquement l'affichage de l'interface utilisateur de rédaction). Il s'agit des fonctions individuelles qui régissent ce qui se passe lorsque différents éléments de l'interface utilisateur de composition sont sélectionnés. Par exemple, une fiche d'interface utilisateur contenant un bouton est généralement associée à une fonction de rappel qui s'exécute lorsqu'un utilisateur clique sur ce bouton. La fonction de rappel pour les widgets qui mettent à jour le contenu du brouillon du message doit renvoyer un objet UpdateDraftActionResponse.

Fonction de déclenchement de la rédaction

L'interface utilisateur de rédaction d'un module complémentaire est construite de la même manière que l'interface utilisateur de message du module complémentaire, à l'aide du service de cartes Apps Script pour construire des fiches et les remplir avec des widgets.

Vous devez implémenter l'élément gmail.composeTrigger.selectActions[].runFunction que vous définissez dans votre fichier manifeste. La fonction de déclenchement de la composition doit renvoyer un seul objet Card ou un tableau d'objets Card comprenant l'UI de composition pour cette action. Ces fonctions sont très semblables aux fonctions de déclenchement contextuel et doivent créer des fiches de la même manière.

Créer des objets d'événement de déclencheur

Lorsqu'une action de composition est sélectionnée, elle exécute la fonction de déclenchement de la composition correspondante et lui transmet 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 le brouillon en cours de composition dans la fonction déclencheur.

Consultez la section Structure des objets d'événement pour en savoir plus sur la manière dont les informations sont organisées dans l'objet d'événement. Les informations contenues dans l'objet événement sont partiellement contrôlées par la valeur du champ manifeste gmail.composeTrigger.draftAccess:

  • Si le champ 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 du déclencheur de rédaction est renseigné avec les listes des destinataires de l'e-mail en cours de rédaction.

Insérer du contenu dans des brouillons actifs

En général, l'interface utilisateur Google Workspace d'un module complémentaire de composition offre les options et le contrôle permettant de rédiger un message. Pour ces cas d'utilisation, une fois que l'utilisateur a effectué des sélections dans l'interface utilisateur, le module complémentaire interprète les sélections et met à jour le brouillon d'e-mail actuel en conséquence.

Pour faciliter la mise à jour du brouillon d'e-mail, le service Card a été étendu aux classes suivantes:

En règle générale, l'interface utilisateur d'un module complémentaire comprend 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 souhaite que ses choix soient ajoutés à l'e-mail qu'il compose. Pour ajouter cette interactivité, le widget doit être associé à un objet Action qui indique 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 compilé décrivant en détail les modifications à apporter au brouillon actuel de l'e-mail.

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 "À", "Cc" et "Cci" du brouillon d'e-mail 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 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 UI de rédaction qui insère des images dans le brouillon de l'e-mail.

    /**
     * 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;
    }