Google Workspace-Add-ons, die Gmail erweitern, können nicht nur eine kartenbasierte Benutzeroberfläche bereitstellen, wenn ein Nutzer eine Gmail-Nachricht liest, sondern auch eine weitere Benutzeroberfläche, wenn der Nutzer neue Nachrichten verfasst oder auf vorhandene antwortet. So können Google Workspace-Add-ons das Verfassen von E-Mails für den Nutzer automatisieren.
Auf die Add-on-Benutzeroberfläche zum Verfassen von E-Mails zugreifen
Es gibt zwei Möglichkeiten, die Benutzeroberfläche zum Verfassen eines Add-ons aufzurufen. Die erste Möglichkeit besteht darin, einen neuen Entwurf oder eine Antwort zu verfassen, 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 wird durch das Add-on die entsprechende Compose-Triggerfunktion ausgeführt, die im Manifest des Add-ons definiert ist. Mit der Compose-Triggerfunktion wird die Benutzeroberfläche für diese Compose-Aktion erstellt, die Gmail dann dem Nutzer anzeigt.
Compose-Add-on erstellen
So fügen Sie einem Add-on die Funktion zum Verfassen von E-Mails hinzu:
- Fügen Sie dem Add-on-Skriptprojekt Manifest das Feld
gmail.composeTriggerhinzu und aktualisieren Sie die Bereichseinstellungen des Manifests, damit sie die für Compose-Vorgänge erforderlichen Bereiche enthalten. - Implementieren Sie eine Compose-Triggerfunktion, die eine Compose-Benutzeroberfläche erstellt, wenn der Trigger ausgelöst wird. Compose-Triggerfunktionen geben entweder ein einzelnes
Card-Objekt oder ein Array vonCard-Objekten zurück, aus denen die Compose-Benutzeroberfläche für die Compose-Aktion besteht. - Implementieren Sie die zugehörigen Callback-Funktionen, die erforderlich sind, um auf die Compose-UI-Interaktionen des Nutzers zu reagieren. Diese Funktionen sind nicht die Compose-Aktion selbst (die nur dazu führt, dass die Compose-Benutzeroberfläche angezeigt wird), sondern die einzelnen Funktionen, die festlegen, was passiert, wenn verschiedene Elemente der Compose-Benutzeroberfläche ausgewählt werden. Eine UI-Karte mit einer Schaltfläche hat beispielsweise in der Regel eine zugehörige Callback-Funktion, die ausgeführt wird, wenn ein Nutzer auf die Schaltfläche klickt. Die Callback-Funktion für Widgets, die den Inhalt der Nachrichtenentwürfe aktualisieren, sollte ein
UpdateDraftActionResponse-Objekt zurückgeben.
Triggerfunktion erstellen
Die Compose-Benutzeroberfläche eines Add-ons wird auf dieselbe Weise wie die Nachrichten-Benutzeroberfläche des Add-ons erstellt. Dazu wird der Apps Script-Kartendienst verwendet, um Karten zu erstellen und mit Widgets zu füllen.
Sie müssen die gmail.composeTrigger.selectActions[].runFunction implementieren, die Sie in Ihrem Manifest definieren. Die Compose-Triggerfunktion muss entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurückgeben, aus denen die Compose-Benutzeroberfläche für diese Aktion besteht. Diese Funktionen ähneln kontextbezogenen Triggerfunktionen sehr und sollten Karten auf dieselbe Weise erstellen.
Trigger-Ereignisobjekte erstellen
Wenn eine Compose-Aktion ausgewählt wird, wird die entsprechende Compose-Triggerfunktion ausgeführt und ein Ereignisobjekt als Parameter an die Funktion übergeben. Das Ereignisobjekt kann Informationen zum Add-on-Kontext und zum verfassten Entwurf an die Triggerfunktion übergeben.
Weitere Informationen zur Anordnung von Informationen im Ereignisobjekt finden Sie unter Struktur des Ereignisobjekts. Die Informationen im Ereignisobjekt werden teilweise durch den Wert des Manifestfelds gmail.composeTrigger.draftAccess gesteuert:
Wenn das Manifestfeld
gmail.composeTrigger.draftAccessNONEist oder nicht enthalten ist, enthält das Ereignisobjekt nur minimale Informationen.Wenn
gmail.composeTrigger.draftAccessaufMETADATAfestgelegt ist, wird das Ereignisobjekt, das an die Compose-Triggerfunktion übergeben wird, mit Listen der Empfänger der E-Mail gefüllt, die erstellt wird.
Inhalte in aktive Entwürfe einfügen
Normalerweise bietet die Benutzeroberfläche zum Verfassen von Google Workspace-Add-ons dem Nutzer Optionen und Steuerelemente, mit denen er eine Nachricht verfassen kann. In diesen Anwendungsfällen interpretiert das Add-on die Auswahl des Nutzers in der Benutzeroberfläche und aktualisiert den aktuellen E-Mail-Entwurf entsprechend.
Um die Aktualisierung der aktuellen E-Mail-Entwürfe zu vereinfachen, wurde der Kartendienst um die folgenden Klassen erweitert:
ContentType: Eine Enumeration, die definiert, ob veränderbarer HTML-Code, unveränderbarer HTML-Code (der von Gmail-Nutzern nicht bearbeitet werden kann) oder Nur-Text-Inhalte hinzugefügt werden sollen.UpdateDraftActionResponse: Stellt eine Antwort auf eine Aktion dar, die die aktuelle E‑Mail im Entwurf aktualisiert.UpdateDraftActionResponseBuilder: Ein Builder fürUpdateDraftActionResponse-Objekte.UpdateDraftBodyAction: Stellt eine Aktion dar, mit der der Text der aktuellen E‑Mail-Nachricht aktualisiert wird.UpdateDraftBodyType: Ein Enum, das definiert, wie der Textkörper geändert wird.UpdateDraftSubjectAction: Stellt eine Aktion dar, mit der das Betrefffeld der aktuellen E‑Mail-Konzept aktualisiert wird.UpdateDraftToRecipientsAction: Stellt eine Aktion dar, mit der die „An“-Empfänger der aktuellen E-Mail-Nachricht aktualisiert werden.UpdateDraftCcRecipientsAction: Stellt eine Aktion dar, mit der die Cc-Empfänger der aktuellen E‑Mail-Nachricht aktualisiert werden.UpdateDraftBccRecipientsAction: Stellt eine Aktion dar, mit der die Bcc-Empfänger der aktuellen E‑Mail-Nachricht aktualisiert werden.
Normalerweise enthält die Compose-Benutzeroberfläche eines Add-ons ein Widget vom Typ „Speichern“ oder „Einfügen“, auf das ein Nutzer klicken kann, um anzugeben, dass er die Auswahl in der Benutzeroberfläche abgeschlossen hat und seine Auswahl in die E-Mail eingefügt werden soll, die er gerade verfasst. Um diese Interaktivität hinzuzufügen, 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, in dem die Änderungen beschrieben werden, die am aktuellen E-Mail-Entwurf vorgenommen werden sollen.
Beispiel 1
Das folgende Code-Snippet zeigt, wie Sie eine Compose-Benutzeroberfläche erstellen, die die Betreffzeile sowie die Empfänger in den Feldern „An“, „Cc“ und „Bcc“ des aktuellen E‑Mail-Entwurfs aktualisiert.
/**
* 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 Compose-Benutzeroberfläche erstellen, mit der Bilder in die aktuelle E-Mail-Nachricht 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;
}