Erweiterungs-UI zum Schreiben der Nachricht erweitern

Zusätzlich zur Bereitstellung einer kartenbasierten Oberfläche, wenn ein Nutzer eine Gmail-Nachricht liest, können Google Workspace-Add-ons, die Gmail erweitern, eine weitere Oberfläche bereitstellen, wenn der Nutzer neue Nachrichten schreibt oder auf vorhandene antwortet. Dadurch kann das Verfassen von E-Mails für den Nutzer durch Google Workspace-Add-ons automatisiert werden.

Auf die Add-on-Editor-Benutzeroberfläche zugreifen

Es gibt zwei Möglichkeiten, die Benutzeroberfläche zum Schreiben eines Add-ons aufzurufen. Die erste Möglichkeit besteht darin, mit dem Schreiben eines neuen Entwurfs oder einer neuen Antwort zu beginnen, während das Add-on bereits geöffnet ist. Die zweite Möglichkeit besteht darin, das Add-on zu starten, während Sie einen Entwurf erstellen.

In beiden Fällen führt das Add-on die entsprechende Funktion zum Erstellen von Triggern aus, die im Add-on-Manifest definiert ist. Mit der Trigger-Funktion für die Zusammensetzung wird die Benutzeroberfläche für die Erstellung für diese Aktion erstellt, die Gmail dann dem Nutzer anzeigt.

Add-on zum Schreiben einer E-Mail erstellen

So fügen Sie einem Add-on die Funktion zum Schreiben hinzu:

  1. Fügen Sie dem Manifest des Add-on-Skript-Projekts das Feld gmail.composeTrigger hinzu und aktualisieren Sie die Manifestbereiche so, dass sie die für die Erstellungsaktionen erforderlichen Bereiche enthalten.
  2. Implementieren Sie eine Funktion zum Zusammensetzen von Triggern, die beim Auslösen des Triggers eine Benutzeroberfläche zum Erstellen von Nachrichten erstellt. Erstellungsauslöser-Funktionen geben entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurück, aus denen die Erstellungsoberfläche für die Erstellungsaktion besteht.
  3. Implementieren Sie zugehörige Callback-Funktionen, die erforderlich sind, um auf die Interaktionen der Nutzer mit der UI zu reagieren. Diese Funktionen sind nicht die Zusammensetzungsaktion selbst (wodurch nur die Erstellungs-UI angezeigt wird). Vielmehr sind dies die einzelnen Funktionen, die festlegen, was passiert, wenn verschiedene Elemente der Benutzeroberfläche ausgewählt werden. Beispielsweise hat eine UI-Karte, die eine Schaltfläche enthält, normalerweise eine zugehörige Callback-Funktion, die ausgeführt wird, wenn ein Nutzer auf diese Schaltfläche klickt. Die Callback-Funktion für Widgets, die den Inhalt des Nachrichtenentwurfs aktualisieren, sollte ein UpdateDraftActionResponse-Objekt zurückgeben.

Triggerfunktion erstellen

Die Benutzeroberfläche zum Schreiben eines Add-ons ist genauso aufgebaut wie die Nachrichten-UI des Add-ons. Sie verwendet den Kartendienst von Apps Script, um Karten zu erstellen und sie mit Widgets zu füllen.

Du musst den gmail.composeTrigger.selectActions[].runFunction implementieren, den du in deinem Manifest definierst. Die Triggerfunktion für die Zusammensetzung muss entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurückgeben, aus denen die Erstellungs-UI für diese Aktion besteht. Diese Funktionen sind kontextbasierten Triggerfunktionen sehr ähnlich und sollten Karten auf die gleiche Weise erstellen.

Triggerereignisobjekte erstellen

Wenn eine Zusammensetzungsaktion ausgewählt wird, wird die entsprechende Zusammensetzungs-Triggerfunktion ausgeführt und der Funktion ein Ereignisobjekt als Parameter übergeben. Das Ereignisobjekt kann Informationen zum Add-on-Kontext und zum Entwurf enthalten, der für die Triggerfunktion erstellt wird.

Weitere Informationen dazu, wie Informationen im Ereignisobjekt angeordnet sind, finden Sie unter Struktur des Ereignisobjekts. Die im Ereignisobjekt enthaltenen Informationen werden teilweise über den Wert des Manifestfelds gmail.composeTrigger.draftAccess gesteuert:

  • Wenn das Manifestfeld gmail.composeTrigger.draftAccess NONE ist oder nicht enthalten ist, enthält das Ereignisobjekt nur minimale Informationen.

  • Wenn gmail.composeTrigger.draftAccess auf METADATA gesetzt ist, wird das an die Erstellungs-Trigger-Funktion übergebene Ereignisobjekt mit Listen der Empfänger der erstellten E-Mail gefüllt.

Inhalte in aktive Entwürfe einfügen

In der Regel bietet eine Benutzeroberfläche zum Schreiben eines Google Workspace-Add-ons die Nutzeroptionen und -steuerungen, die beim Schreiben einer Nachricht helfen. Wenn der Nutzer in diesen Anwendungsfällen eine Auswahl in der UI getroffen hat, interpretiert das Add-on die Auswahl und aktualisiert den aktuellen Entwurf der funktionierenden E-Mail entsprechend.

Der Kartendienst wurde um die folgenden Klassen erweitert, um das Aktualisieren des aktuellen E-Mail-Entwurfs zu vereinfachen:

In der Regel enthält eine Add-on-Benutzeroberfläche zum Schreiben einer E-Mail ein „Speichern“- oder „Einfügen“-Widget, auf das ein Nutzer klicken kann, um anzugeben, dass er eine Auswahl in der Benutzeroberfläche getroffen hat und möchte, dass seine Auswahl der E-Mail hinzugefügt wird, die er gerade verfasst. Zum Hinzufügen dieser Interaktivität muss dem Widget ein Action-Objekt zugeordnet sein, das das Add-on anweist, eine bestimmte Callback-Funktion auszuführen, wenn auf das Widget geklickt wird. Sie müssen diese Callback-Funktionen implementieren. Jede Callback-Funktion sollte ein erstelltes UpdateDraftActionResponse-Objekt zurückgeben, das Details zu den Änderungen enthält, die am aktuellen E-Mail-Entwurf vorgenommen werden sollen.

Beispiel 1

Das folgende Code-Snippet zeigt, wie Sie eine Benutzeroberfläche zum Schreiben einer Nachricht erstellen, mit der der Betreff sowie die Empfänger des aktuellen E-Mail-Entwurfs an "An", "Cc" und "Bcc" aktualisiert werden.

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

Beispiel 2

Das folgende Code-Snippet zeigt, wie Sie eine Benutzeroberfläche zum Schreiben von Nachrichten erstellen, mit der Bilder in den aktuellen E-Mail-Entwurf eingefügt werden.

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