Como estender a interface de escrita com ações de escrita

Além de oferecer uma interface baseada em cards quando um usuário está lendo uma mensagem do Gmail "Complementos do Google Workspace que ampliam os recursos do Gmail" podem fornecer outra interface quando o usuário estiver escrevendo novas mensagens ou respondendo aos que já existem. Isso permite que os Complementos do Google Workspace automatizem a tarefa de escrever e-mails para os usuários.

Como acessar a interface de composição do complemento

Há duas maneiras de ver a interface de composição de um complemento. A primeira é começar escrever um novo rascunho ou resposta enquanto o complemento já estiver aberto. A segunda iniciar o complemento enquanto escreve um rascunho.

Os dois casos fazem com que o complemento execute a função de gatilho do Compose, definida no complemento manifesto. A função de gatilho do Compose cria a interface do Compose para esse Compose. que o Gmail exibe ao usuário.

Como criar um complemento do Compose

Para adicionar a funcionalidade de escrita a um complemento, siga estas etapas gerais:

  1. Adicionar o gmail.composeTrigger para o projeto de script de complemento manifesto e atualizar o manifesto escopos para incluir os necessários para ações de composição.
  2. Implemente uma função de gatilho do Compose que crie uma interface do Compose quando o acionar disparos. As funções de gatilho do Compose retornam um único objeto Card ou uma matriz de objetos Card que compreendem a IU de composição para a ação de composição.
  3. Implementar funções de callback associadas necessárias para reagir ao sistema compor interações de interface. Essas funções não são a ação de composição em si (que só faz com que a interface do Compose apareça); ao contrário, essas são as funções individuais que controlam o que acontece quando diferentes elementos do do Compose estão selecionados. Por exemplo, um card de interface que contém um botão geralmente tem uma função de retorno de chamada associada que é executada quando um usuário clica o botão. Função de callback para widgets que atualizam a mensagem de rascunho. conteúdo deve retornar um UpdateDraftActionResponse objeto.

Função de gatilho do Compose

A interface de composição de um complemento é criada da mesma forma que a mensagem dele. IU: como usar o serviço Card do Apps Script para criar cards e preenchê-los com widgets.

É necessário implementar o gmail.composeTrigger.selectActions[].runFunction definidos no manifesto. A função de gatilho do Compose precisa retornar um único objeto Card ou uma matriz de objetos Card. que compõem a interface do Compose para essa ação. Essas funções são muito semelhantes para funções de acionamento contextual e criar os cards da mesma forma.

Objetos de evento de gatilho do Compose

Quando uma ação de escrita é selecionada, ela executa o gatilho de escrita correspondente. e transmite a ela 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 contido no objeto do evento é parcialmente controlado pelo valor do gmail.composeTrigger.draftAccess manifest:

  • Se o gmail.composeTrigger.draftAccess manifesto for NONE ou não estiver incluído, o objeto de evento terá apenas o mínimo de informações possível.

  • Se gmail.composeTrigger.draftAccess for definido como METADATA, o objeto do evento transmitido para a função de gatilho do Compose é preenchida com listas de destinatários do e-mail que está sendo escrito.

.

Como inserir conteúdo em rascunhos ativos

Normalmente, uma interface de escrita de complementos do Google Workspace oferece as opções do usuário e os controles que ajudam a escrever uma mensagem. Para esses casos de uso, Quando o usuário fizer seleções na interface, o complemento vai interpretar as seleções. e atualiza de acordo com o rascunho de e-mail atual de trabalho.

Para facilitar a atualização do rascunho atual do e-mail, o Serviço de cartão foi estendido com as seguintes classes:

Normalmente, uma interface do Compose como complemento inclui um botão "Salvar" ou "Inserir" que um usuário pode clicar para indicar que terminou de fazer seleções na interface do usuário e deseja que seus opções sejam adicionadas ao e-mail que estão escrevendo. Para adicionar interactivity, o widget deve ter um objeto Action associado que instrui o complemento a executar uma função de retorno de chamada específica quando o widget é clicado. Você precisa implementar essas funções de callback. Cada função de callback precisa retornar um build UpdateDraftActionResponse que detalha as alterações a serem feitas no rascunho de e-mail atual.

Exemplo 1

O snippet de código a seguir mostra como criar uma interface do usuário de escrita que atualize 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 interface do Compose que insere imagens. no rascunho do 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;
    }