Étendre l'UI de rédaction avec des actions de rédaction

En plus de fournir une interface basée sur des fiches 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. Cela permet aux modules complémentaires d'automatiser la tâche de rédaction d'e-mails pour l'utilisateur.

Accéder à l'interface utilisateur de rédaction du module complémentaire Google Workspace

Il existe deux façons d'afficher l'interface utilisateur de rédaction d'un module complémentaire. La première consiste à commencer à rédiger un brouillon ou une réponse lorsque le module complémentaire est déjà ouvert. La deuxième consiste à démarrer le module complémentaire lors de la rédaction d'un brouillon.

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

Créer un module complémentaire de rédaction

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

  1. Ajoutez le gmail.composeTrigger champ au fichier manifeste du projet de script du module complémentaire et mettez à jour les champs d'application du fichier manifeste pour inclure ceux requis pour les actions de rédaction.
  2. Implémentez une fonction de déclencheur de rédaction qui crée une interface utilisateur de rédaction lorsque le déclencheur se déclenche. Les fonctions de déclencheur de rédaction renvoient un seul Card objet ou un tableau d' Card objets qui forment l'interface utilisateur de rédaction pour l'action de rédaction.
  3. Implémentez les fonctions de rappel associées nécessaires pour réagir aux interactions de l'utilisateur avec l'interface utilisateur de rédaction. Ces fonctions ne sont pas l'action de rédaction elle-même (qui ne fait qu'afficher l'interface utilisateur de rédaction). Il s'agit plutôt des fonctions individuelles qui régissent ce qui se passe lorsque différents éléments de l'interface utilisateur de rédaction 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 doit renvoyer un objet UpdateDraftActionResponse.

Fonction de déclencheur de rédaction

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

Vous devez implémenter le gmail.composeTrigger.selectActions[].runFunction que vous définissez dans votre fichier manifeste. La fonction de déclencheur de rédaction doit renvoyer un seul Card ou un tableau de Card objets qui forment l'interface utilisateur de rédaction pour cette action. Ces fonctions sont très semblables à des fonctions de déclencheur contextuel et doivent créer des fiches de la même manière.

Objets d'événement de déclencheur de rédaction

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

Pour en savoir plus sur la façon dont les informations sont organisées dans l'objet d'événement, consultez la section Structure de l'objet d'événement. Les informations contenues dans l'objet d'événement sont partiellement contrôlées par la valeur du gmail.composeTrigger.draftAccess champ de fichier manifeste :

  • Si le gmail.composeTrigger.draftAccess champ de fichier manifeste est NONE ou n'est pas inclus, l'objet d'é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 rédaction est rempli de listes de destinataires de l'e-mail en cours de rédaction. L'utilisation de METADATA l'accès au brouillon nécessite que le fichier manifeste du module complémentaire inclue le https://www.googleapis.com/auth/gmail.addons.current.message.metadata champ d'application Gmail.

Insérer du contenu dans des brouillons actifs

En règle générale, l'interface utilisateur de rédaction d'un module complémentaire fournit à l'utilisateur des options et des commandes qui l'aident à 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 les sélections et met à jour le brouillon d'e-mail en cours en conséquence.

Pour faciliter la mise à jour du brouillon d'e-mail actuel, le service de fiche a été étendu avec les classes suivantes :

En règle générale, l'interface utilisateur de rédaction d'un module complémentaire inclut un widget "Enregistrer" ou "Insérer" sur lequel un utilisateur peut cliquer pour indiquer qu'il a terminé d'effectuer des sélections dans l'interface utilisateur et qu'il souhaite que ses choix soient ajoutés à l'e-mail qu'il rédige. Pour ajouter cette interactivité, le widget doit avoir un objet associé 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 créé qui détaille les modifications à apporter au brouillon d'e-mail actuel.

Exemple 1

L'extrait de code suivant montre comment créer une interface utilisateur de rédaction qui met à jour l'objet, ainsi que 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 interface utilisateur de rédaction qui insère des images dans le 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 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;
}