Extension de l'interface utilisateur de Compose avec des actions de rédaction

En plus de fournir une interface basée sur des cartes pour les utilisateurs qui consultent un compte Gmail des modules complémentaires Google Workspace qui étendent peuvent fournir une autre interface lorsque l'utilisateur rédige de nouveaux messages ou en répondant à ceux qui existent déjà. Cela permet aux modules complémentaires Google Workspace d'automatiser la rédaction des e-mails pour l'utilisateur.

Accéder à l'UI du module complémentaire Compose

Il existe deux façons d'afficher l'interface utilisateur Compose d'un module complémentaire. La première consiste à commencer rédiger un brouillon ou une réponse alors que le module complémentaire est déjà ouvert ; Le deuxième consiste à démarrer le module complémentaire en composant un brouillon.

Dans les deux cas, le module complémentaire exécute la requête Fonction de déclencheur Compose, définie dans le module complémentaire fichier manifeste. La fonction de déclencheur Compose crée l'interface utilisateur de Compose que Gmail présente 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. Ajouter la gmail.composeTrigger au projet de script du module complémentaire fichier manifeste et mettre à jour le fichier manifeste habilitations à inclure requises pour les actions de rédaction.
2. Implémentez une fonction de déclencheur Compose qui crée une interface utilisateur Compose lorsque le déclencheurs. Les fonctions de déclencheur Compose renvoient soit un seul un objet Card ou un tableau de Objets Card comprenant l'UI de composition pour l'action de rédaction.
3. Implémentez les fonctions de rappel associées nécessaires pour réagir aux réactions de l'utilisateur Compose des interactions avec l'UI. Ces fonctions ne sont pas l'action de composition elle-même. (ce qui permet uniquement d'afficher l'interface utilisateur de Compose) Ce sont plutôt les fonctions individuelles qui régissent ce qui se passe lorsque différents éléments Compose UI sont sélectionnées. 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 sur ce bouton. Fonction de rappel pour les widgets qui mettent à jour le brouillon du message doit renvoyer une UpdateDraftActionResponse .

Fonction de déclencheur Compose

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

Vous devez mettre en œuvre gmail.composeTrigger.selectActions[].runFunction que vous définissez dans votre fichier manifeste. La fonction de déclencheur Compose doit renvoyer soit un seul objet Card, soit Un tableau d'objets Card qui composent l'interface utilisateur de Compose pour cette action. Ces fonctions sont très similaires aux fonctions de déclenchement contextuel et devez créer les cartes de la même manière.

Avertissement :Pour des raisons de sécurité, les modules complémentaires vous ne pouvez pas modifier automatiquement les paramètres autorisations d'accès aux fichiers. Par exemple, un module complémentaire ne peut pas ajouter des destinataires d'e-mails à l'ensemble des comptes autorisés à afficher un fichier Dropbox. Au lieu de cela, le module complémentaire doit informer les utilisateurs que la modification de l'autorisation est en cours. les modules complémentaires qui n'en informent pas les utilisateurs ne peuvent pas transmettre avis sur le module complémentaire.

Objets d'événement déclencheur Compose

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

Consultez Structure des objets liés aux événements. pour en savoir plus sur la façon dont les informations sont organisées dans l'objet événement. Les informations contenu dans l'objet événement est partiellement contrôlé par la valeur du paramètre gmail.composeTrigger.draftAccess manifeste:

• Si le gmail.composeTrigger.draftAccess est NONE ou n'est pas inclus, l'objet événement ne contient un minimum d'informations.

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

Remarque :L'utilisation de l'accès brouillon METADATA nécessite que le fichier manifeste du module complémentaire comprenne le https://www.googleapis.com/auth/gmail.addons.current.message.metadata Champ d'application Gmail.

Insérer du contenu dans les brouillons actifs

Généralement, l'UI Compose de module complémentaire Google Workspace fournit les options et commandes utilisateur qui permettent de rédiger un message. Pour ces cas d'utilisation, Une fois que l'utilisateur a fait une sélection dans l'interface utilisateur, le module complémentaire les interprète et met à jour le brouillon de l'e-mail de travail actuel en conséquence.

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

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

Généralement, l'UI d'un module complémentaire Compose inclut un bouton "Enregistrer" ou "Insérer" widget qu'un utilisateur peuvent cliquer pour indiquer qu'ils ont terminé de faire des sélections dans l'interface utilisateur et qu'ils souhaitent des choix à ajouter à l'e-mail qu'il rédige. Pour l'ajouter interactivity, le widget doit comporter un objet Action associé qui demande au module complémentaire d'exécuter une fonction de rappel spécifique lorsque le widget est sur lesquels l'utilisateur a cliqué. Vous devez implémenter ces fonctions de rappel. Chaque fonction de rappel renvoyer un modèle UpdateDraftActionResponse qui détaille les modifications à apporter au brouillon actuel.

Exemple 1

L'extrait de code suivant montre comment créer une interface utilisateur Compose qui met à jour l'objet, ainsi que les destinataires du brouillon actuel de l'e-mail à l'aide des champs "À", "Cc" et "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 UI 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;
    }