Além de fornecer uma interface baseada em cards quando um usuário está lendo uma mensagem do Gmail, os complementos do Google Workspace que ampliam o Gmail podem oferecer outra interface quando o usuário está escrevendo novas mensagens ou respondendo às atuais. Isso permite que os complementos do Google Workspace automatizem a tarefa de escrever e-mails para o usuário.
Acessar a IU do complemento para escrever
Há duas maneiras de ver a IU do Compose de um complemento. A primeira maneira é começar a escrever um novo rascunho ou resposta enquanto o complemento já está aberto. A segunda maneira é iniciar o complemento enquanto cria um rascunho.
Ambos os casos fazem com que o complemento execute a função de gatilho do Compose correspondente, definida no manifesto do complemento. A função de gatilho de composição cria a IU de escrita para essa ação de escrita, que o Gmail exibe ao usuário.
Como criar um complemento do Compose
Para adicionar a funcionalidade de escrever a um complemento, siga estas etapas gerais:
- Adicione o campo
gmail.composeTrigger
ao manifesto do projeto de script de complemento e atualize os escopos do manifesto para incluir os necessários para as ações de composição. - Implemente uma função de gatilho do Compose que crie uma IU do Compose quando o
acionador for disparado. As funções de gatilho do Compose retornam um único objeto
Card
ou uma matriz de objetosCard
que compõem a IU do Compose para a ação de composição. - Implemente as funções de callback associadas necessárias para reagir às interações
da IU do Compose do usuário. Essas funções não são a ação de composição
em si, que apenas faz com que a IU do Compose apareça. Na verdade, elas são as
funções individuais que regem o que acontece quando diferentes elementos da
IU do Compose são selecionados. Por exemplo, um cartão de IU que contém um botão
geralmente tem uma função de callback associada que é executada quando um usuário clica
nesse botão. A função de callback para widgets que atualizam o conteúdo da mensagem de rascunho precisa retornar um objeto
UpdateDraftActionResponse
.
Função de gatilho do Compose
A IU do Compose de um complemento é criada da mesma forma que a IU de mensagens do complemento, usando o serviço Card do Apps Script para criar cards e preenchê-los com widgets.
Implemente o
gmail.composeTrigger.selectActions[].runFunction
definido no manifesto. A função de gatilho de composição precisa retornar
um único objeto Card
ou
uma matriz de objetos Card
que compõem a IU do Compose para essa ação. Essas funções são muito semelhantes
às funções de gatilho contextuais
e precisam criar cards da mesma maneira.
Objetos de evento de gatilho do Compose
Quando uma ação de composição é selecionada, ela executa a função de gatilho de composição correspondente e transmite um objeto de evento como parâmetro. O objeto de evento pode transportar informações sobre o contexto do complemento e o rascunho que está sendo composto para a função de gatilho.
Consulte Estrutura do objeto de evento para detalhes sobre como as informações são organizadas no objeto de evento. As informações
contidas no objeto de evento são parcialmente controladas pelo valor do
campo de manifesto
gmail.composeTrigger.draftAccess
:
Se o campo de manifesto
gmail.composeTrigger.draftAccess
forNONE
ou não estiver incluído, o objeto de evento terá apenas informações mínimas.Se
gmail.composeTrigger.draftAccess
for definido comoMETADATA
, o objeto do evento transmitido para a função do gatilho de escrita será preenchido com listas de destinatários do e-mail que está sendo composto.
Como inserir conteúdo em rascunhos ativos
Normalmente, uma IU de escrita de complementos do Google Workspace oferece as opções e o controle do usuário que ajudam a escrever uma mensagem. Nesses casos de uso, quando o usuário faz seleções na IU, o complemento interpreta as escolhas e atualiza o rascunho de e-mail de trabalho atual conforme necessário.
Para facilitar a atualização do rascunho atual do e-mail, o serviço de cards foi estendido com as seguintes classes:
ContentType
: um tipo enumerado que define se é necessário adicionar HTML mutável, HTML imutável (que os usuários do Gmail não podem editar) ou conteúdo de texto simples.UpdateDraftActionResponse
: representa uma resposta a uma ação que atualiza o rascunho de e-mail atual.UpdateDraftActionResponseBuilder
: um builder para objetosUpdateDraftActionResponse
.UpdateDraftBodyAction
: representa uma ação que atualiza o corpo do rascunho de e-mail atual.UpdateDraftBodyType
: um tipo enumerado que define como o corpo é modificado.UpdateDraftSubjectAction
: representa uma ação que atualiza o campo de assunto do rascunho de e-mail.UpdateDraftToRecipientsAction
: representa uma ação que atualiza os destinatários "Para" do rascunho de e-mail atual.UpdateDraftCcRecipientsAction
: representa uma ação que atualiza os destinatários "Cc" do rascunho atual do e-mail.UpdateDraftBccRecipientsAction
: representa uma ação que atualiza os destinatários Cco do rascunho atual do e-mail.
Normalmente, uma IU de composição de complemento inclui um widget "Salvar" ou "Inserir" em que um usuário
pode clicar para indicar que terminou as seleções na IU e quer que as
escolhas sejam adicionadas ao e-mail que está redigindo. Para adicionar essa
interatividade, o widget precisa ter
um objeto Action
associado que
instrua o complemento a executar uma função de callback específica quando o widget for
clicado. Implemente essas funções de callback. Cada função de callback precisa
retornar um objeto
UpdateDraftActionResponse
criado que detalha as alterações a serem feitas no rascunho atual do e-mail.
Exemplo 1
O snippet de código a seguir mostra como criar uma IU de escrita que atualiza o assunto e os destinatários "Para", "Cc" e "Cco" do rascunho de e-mail atual.
/**
* 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;
}
Exemplo 2
O snippet de código a seguir mostra como criar uma IU do Compose que insere imagens no rascunho de e-mail atual.
/**
* 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;
}