Google Workspace-Add-ons, die Gmail erweitern, bieten nicht nur eine kartenbasierte Benutzeroberfläche, wenn Nutzer eine Gmail-Nachricht lesen, sondern können auch eine andere Benutzeroberfläche bereitstellen, wenn Nutzer neue Nachrichten verfassen oder auf vorhandene antworten. So können Google Workspace-Add-ons das Verfassen von E-Mails für den Nutzer automatisieren.
Auf die Benutzeroberfläche zum Erstellen von Add-ons zugreifen
Es gibt zwei Möglichkeiten, die Benutzeroberfläche zum Erstellen eines Add-ons aufzurufen. Die erste Möglichkeit besteht darin, einen neuen Entwurf zu verfassen oder zu antworten, 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 verfassen.
In beiden Fällen führt das Add-on die entsprechende Triggerfunktion zum Zusammenstellen aus, die im Manifest des Add-ons definiert ist. Die Triggerfunktion „compose“ erstellt die Benutzeroberfläche für die Aktion „compose“, die dann in Gmail angezeigt wird.
Add-on für die Erstellung von E-Mails erstellen
So fügen Sie einem Add-on eine Funktion zum Erstellen von Inhalten hinzu:
- Fügen Sie das Feld
gmail.composeTriggerdem Manifest des Add-on-Scripts hinzu und aktualisieren Sie die Scopes des Manifests, um die für die Erstellung von Aktionen erforderlichen zu berücksichtigen. - Implementieren Sie eine Funktion für einen Zusammenstellungstrigger, die eine Zusammenstellungs-UI erstellt, wenn der Trigger ausgelöst wird. Triggerfunktionen für das Erstellen geben entweder ein einzelnes
Card-Objekt oder ein Array vonCard-Objekten zurück, die die Benutzeroberfläche für das Erstellen der Aktion bilden. - Implementieren Sie zugehörige Callback-Funktionen, die auf die UI-Interaktionen des Nutzers reagieren müssen. Diese Funktionen sind nicht die Aktion „Schreiben“, die nur die Benutzeroberfläche zum Schreiben öffnet. Vielmehr sind es die einzelnen Funktionen, die steuern, was passiert, wenn verschiedene Elemente der Benutzeroberfläche zum Schreiben ausgewählt werden. Beispielsweise ist einer UI-Karte mit einer Schaltfläche in der Regel eine Callback-Funktion zugeordnet, die ausgeführt wird, wenn ein Nutzer auf diese Schaltfläche klickt. Die Callback-Funktion für Widgets, die den Inhalt der Entwurfsnachricht aktualisieren, sollte ein
UpdateDraftActionResponse-Objekt zurückgeben.
Triggerfunktion erstellen
Die Bedienoberfläche zum Erstellen von Add-ons wird auf die gleiche Weise erstellt wie die Bedienoberfläche für Nachrichten. Dazu wird der Kartendienst von Apps Script verwendet, um Karten zu erstellen und mit Widgets zu füllen.
Sie müssen die in Ihrem Manifest definierte gmail.composeTrigger.selectActions[].runFunction implementieren. Die Funktion für den Zusammensetzungstrigger muss entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurückgeben, die die Benutzeroberfläche für die Zusammensetzung dieser Aktion bilden. Diese Funktionen ähneln sehr den Funktionen für kontextbezogene Trigger und Karten sollten auf die gleiche Weise erstellt werden.
Triggerereignisobjekte erstellen
Wenn eine Aktion vom Typ „Senden“ ausgewählt wird, wird die entsprechende Funktion für den Trigger „Senden“ ausgeführt und der Funktion wird ein Ereignisobjekt als Parameter übergeben. Das Ereignisobjekt kann Informationen zum Add-on-Kontext und zum verfassten Entwurf an die Triggerfunktion enthalten.
Weitere Informationen dazu, wie Informationen im Ereignisobjekt angeordnet sind, finden Sie unter Struktur des Ereignisobjekts. Die im Ereignisobjekt enthaltenen Informationen werden teilweise durch den Wert des Manifestfelds gmail.composeTrigger.draftAccess gesteuert:
Wenn das Manifest-Feld
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 Triggerfunktion für das Verfassen übergeben wird, mit Listen der Empfänger der gerade verfassten E-Mail gefüllt.
Inhalte in aktive Entwürfe einfügen
Normalerweise bietet die Benutzeroberfläche zum Verfassen einer Nachricht in einem Google Workspace-Add-on die Optionen und Steuerelemente, die beim Verfassen einer Nachricht helfen. Bei diesen Anwendungsfällen werden die Auswahlen des Nutzers vom Add-on interpretiert und der aktuelle E-Mail-Entwurf entsprechend aktualisiert.
Um das Aktualisieren des aktuellen E-Mail-Entwurfs zu erleichtern, wurde der Kartendienst um die folgenden Klassen erweitert:
ContentType: Ein Enum, das festlegt, ob veränderbarer HTML-Code, unveränderlicher HTML-Code (der von Gmail-Nutzern nicht bearbeitet werden kann) oder Nur-Text-Inhalt hinzugefügt werden soll.UpdateDraftActionResponse: Stellt eine Antwort auf eine Aktion dar, durch die die aktuelle E-Mail-Vorlage aktualisiert wird.UpdateDraftActionResponseBuilder: ein Builder fürUpdateDraftActionResponse-Objekte.UpdateDraftBodyAction: Stellt eine Aktion dar, durch die der Textkörper der aktuellen E-Mail-Vorlage aktualisiert wird.UpdateDraftBodyType: Ein Enum, das definiert, wie der Textkörper geändert wird.UpdateDraftSubjectAction: Stellt eine Aktion dar, durch die das Betrefffeld der aktuellen E-Mail-Vorlage aktualisiert wird.UpdateDraftToRecipientsAction: Stellt eine Aktion dar, mit der die Empfänger der aktuellen E-Mail-Vorlage aktualisiert werden.UpdateDraftCcRecipientsAction: Stellt eine Aktion dar, mit der die Cc-Empfänger der aktuellen E-Mail-Vorlage aktualisiert werden.UpdateDraftBccRecipientsAction: Stellt eine Aktion dar, durch die die Bcc-Empfänger der aktuellen E-Mail-Vorlage aktualisiert werden.
In der Regel enthält die Benutzeroberfläche zum Erstellen eines Add-ons ein Widget zum Speichern oder Einfügen, auf das Nutzer klicken können, um anzugeben, dass sie mit der Auswahl auf der Benutzeroberfläche fertig sind und dass ihre Auswahl der gerade verfassten E-Mail hinzugefügt werden soll. Um diese Interaktivität hinzuzufügen, sollte 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 Rückruffunktion sollte ein erstelltes UpdateDraftActionResponse-Objekt zurückgeben, das die Änderungen am aktuellen E-Mail-Entwurf enthält.
Beispiel 1
Das folgende Code-Snippet zeigt, wie Sie eine Benutzeroberfläche zum Verfassen von E-Mails erstellen, mit der der Betreff sowie die Empfänger (An, Cc, Bcc) des aktuellen E-Mail-Entwurfs 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 Erstellen von E-Mails 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;
}