Dodatki do Google Workspace, które rozszerzają Gmaila, nie tylko udostępniają interfejs oparty na kartach, ale też interfejs oparty na kartach, gdy użytkownik czyta wiadomość w Gmailu. Dzięki temu dodatki do Google Workspace mogą zautomatyzować tworzenie e-maili dla użytkownika.
Uzyskiwanie dostępu do interfejsu tworzenia dodatku
Interfejs tworzenia dodatku można wyświetlić na 2 sposoby. Pierwszym sposobem jest rozpoczęcie tworzenia nowej wersji roboczej lub odpowiedzi, gdy dodatek jest już otwarty. Drugi sposób to uruchamianie dodatku podczas tworzenia wersji roboczej.
W obu przypadkach dodatek wykonuje odpowiednią funkcję aktywatora tworzenia zdefiniowaną w pliku manifestu dodatku. Funkcja aktywatora tworzenia wiadomości tworzy interfejs tworzenia wiadomości, który Gmail wyświetla użytkownikowi.
Tworzenie dodatku do tworzenia wiadomości
Aby dodać funkcję tworzenia wiadomości do dodatku, wykonaj te ogólne kroki:
- Dodaj pole
gmail.composeTrigger
do pliku manifestu projektu dodatku i zaktualizuj zakresy pliku manifestu, aby uwzględnić te elementy wymagane do tworzenia treści. - Zaimplementuj funkcję aktywatora tworzenia, która tworzy interfejs tworzenia po uruchomieniu reguły. Funkcje aktywatora tworzenia wiadomości zwracają pojedynczy obiekt
Card
lub tablicę obiektówCard
, które składają się na interfejs tworzenia, dla działania tworzenia wiadomości. - Zaimplementuj powiązane funkcje wywołania zwrotnego niezbędne do reagowania na interakcje użytkownika w interfejsie tworzenia wiadomości. Te funkcje nie są działaniem tworzenia (które powoduje tylko wyświetlenie interfejsu tworzenia), a raczej indywidualnymi funkcjami, które określają, co się dzieje, gdy wybrane są różne elementy tego interfejsu. Na przykład karta interfejsu zawierająca przycisk ma zwykle powiązaną funkcję wywołania zwrotnego, która jest wykonywana, gdy użytkownik kliknie ten przycisk. Funkcja wywołania zwrotnego widżetów, które aktualizują treść wersji roboczej wiadomości, powinna zwracać obiekt
UpdateDraftActionResponse
.
Utwórz funkcję aktywatora
Interfejs tworzenia dodatku został stworzony w taki sam sposób jak interfejs wiadomości dodatku, czyli przy użyciu usługi karty Apps Script, która pozwala tworzyć karty i wypełniać je widżetami.
Musisz zaimplementować gmail.composeTrigger.selectActions[].runFunction
zdefiniowany w pliku manifestu. Funkcja aktywatora tworzenia wiadomości musi zwracać pojedynczy obiekt Card
lub tablicę obiektów Card
, które składają się na interfejs tworzenia dla danego działania. Te funkcje są bardzo podobne do funkcji aktywatorów kontekstowych i powinny tworzyć karty w ten sam sposób.
Tworzenie obiektów zdarzeń aktywatora
Po wybraniu działania tworzenia wiadomości wykonywana jest odpowiednia funkcja wyzwalacza tworzenia i przekazuje tę funkcję jako parametr obiekt zdarzenia. Obiekt zdarzenia może zawierać informacje o kontekście dodatku i wersji roboczej tworzonej dla funkcji aktywującej.
Szczegółowe informacje o rozmieszczeniu informacji w obiekcie zdarzenia znajdziesz w sekcji Struktura obiektu zdarzenia. Informacje zawarte w obiekcie zdarzenia zależą częściowo od wartości pola manifestu gmail.composeTrigger.draftAccess
:
Jeśli pole manifestu
gmail.composeTrigger.draftAccess
zawiera wartośćNONE
lub go nie zawiera, obiekt zdarzenia zawiera tylko znikome informacje.Jeśli właściwość
gmail.composeTrigger.draftAccess
ma wartośćMETADATA
, obiekt zdarzenia przekazywany do funkcji aktywatora tworzenia wiadomości jest zapełniany listami odbiorców tworzonego e-maila.
Wstawianie treści do aktywnych wersji roboczych
Zwykle interfejs tworzenia wiadomości dodatku Google Workspace udostępnia użytkownikom opcje i elementy sterujące, które pomagają w tworzeniu wiadomości. W takich przypadkach, gdy użytkownik dokona wyborów w interfejsie, dodatek zinterpretuje je i odpowiednio zaktualizuje bieżącą wersję roboczą e-maila.
Aby ułatwić aktualizowanie bieżącej wersji roboczej e-maila, rozszerzyliśmy usługę kart o te klasy:
ContentType
– wyliczenie określające, czy dodać zmienny kod HTML, stały kod HTML (który nie może być edytowany przez użytkowników Gmaila), czy zwykły tekst.UpdateDraftActionResponse
– reprezentuje odpowiedź na działanie, które powoduje zaktualizowanie bieżącej wersji roboczej e-maila.UpdateDraftActionResponseBuilder
– kreator obiektówUpdateDraftActionResponse
.UpdateDraftBodyAction
– oznacza działanie, które powoduje zaktualizowanie treści bieżącej wersji roboczej e-maila.UpdateDraftBodyType
– wyliczenie określające sposób zmiany treści.UpdateDraftSubjectAction
– oznacza działanie, które powoduje zaktualizowanie pola tematu bieżącej wersji roboczej e-maila.UpdateDraftToRecipientsAction
– oznacza działanie powodujące aktualizację pola Do odbiorców bieżącej wersji roboczej e-maila.UpdateDraftCcRecipientsAction
– oznacza działanie powodujące aktualizację adresatów w polu DW bieżącej wersji roboczej e-maila.UpdateDraftBccRecipientsAction
– oznacza działanie powodujące aktualizację adresatów w polu UDW bieżącej wersji roboczej e-maila.
Zwykle interfejs tworzenia dodatku zawiera widżet „Zapisz” lub „Wstaw”, który użytkownik może kliknąć, aby wskazać, że dany element został już wybrany i dodać wybrany element do tworzonego e-maila. Aby można było dodać tę interaktywność, widżet powinien mieć powiązany obiekt Action
, który instruuje dodatek, by po kliknięciu widżetu uruchomił określoną funkcję wywołania zwrotnego. Musisz wdrożyć te funkcje wywołań zwrotnych. Każda funkcja wywołania zwrotnego powinna zwracać utworzony obiekt UpdateDraftActionResponse
ze szczegółowymi informacjami o zmianach, które należy wprowadzić w bieżącej wersji roboczej e-maila.
Przykład 1
Poniższy fragment kodu pokazuje, jak utworzyć interfejs tworzenia, który aktualizuje temat oraz adresatów Do, DW i UDW bieżącej wersji roboczej e-maila.
/**
* 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;
}
Przykład 2
Poniższy fragment kodu pokazuje, jak utworzyć interfejs tworzenia, który wstawia obrazy do bieżącej wersji roboczej e-maila.
/**
* 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;
}