Cómo extender la IU de Compose con acciones de redacción

Además de proporcionar una interfaz basada en tarjetas cuando un usuario lee un los complementos de Google Workspace que extienden Gmail puede proporcionar otra interfaz cuando el usuario redacta nuevos mensajes o responder a los existentes. Esto permite que los complementos de Google Workspace automaticen la tarea de redactar correos electrónicos para el usuario.

Cómo acceder a la IU de Compose para complementos

Hay dos maneras de ver la IU de Compose de un complemento. La primera es empezar Puedes redactar un nuevo borrador o una respuesta mientras el complemento ya esté abierto. El segundo es iniciar el complemento mientras redactas un borrador.

Cualquiera de los casos hace que el complemento ejecute el comando función de activador de Compose, definida en el complemento manifiesto. La función de activador de Compose compila la IU de Compose para esa composición. , que Gmail luego le muestra al usuario.

Cómo compilar un complemento de Compose

Para agregar la funcionalidad de redacción a un complemento, sigue estos pasos generales:

  1. Agrega el elemento gmail.composeTrigger. al proyecto de secuencia de comandos del complemento manifiesto y actualiza el manifiesto alcances para incluir los necesarios para las acciones de redacción.
  2. Implementa una función de activador de Compose que compile una IU de Compose cuando desencadenar disparos. Las funciones de activador de Compose muestran un Card o un array de Objetos Card que comprenden la IU de Compose para la acción de redacción.
  3. Implementar funciones de devolución de llamada asociadas necesarias para reaccionar a la respuesta del usuario componer interacciones de la IU. Estas funciones no son la acción de Compose en sí (que solo hace que aparezca la IU de Compose); más bien, estas son las funciones individuales que rigen lo que sucede cuando diferentes elementos del de Compose. Por ejemplo, una tarjeta de IU que contiene un botón generalmente tiene una función de devolución de llamada asociada que se ejecuta cuando un usuario hace clic ese botón. La función de devolución de llamada para widgets que actualizan el borrador del mensaje el contenido debe mostrar un UpdateDraftActionResponse .

Función de activador de Compose

La IU de redacción de un complemento se compila de la misma manera que el mensaje del complemento. IU: Usa el servicio de tarjetas de Apps Script para crear tarjetas y rellenarlas con widgets.

Debes implementar el gmail.composeTrigger.selectActions[].runFunction que defines en tu manifiesto. La función de activador de Compose debe mostrar un solo objeto Card o un array de objetos Card que componen la IU de Compose para esa acción. Estas funciones son muy similares a las funciones de activación contextuales y deberían crear las tarjetas de la misma manera.

Objetos de eventos de activador de Compose

Cuando se selecciona una acción de composición, ejecuta el activador de composición correspondiente. y pasa la función a un objeto de evento como parámetro. El objeto de evento puede contener información sobre el contexto del complemento y el borrador que se está redactando en la función activadora.

Consulta Estructura de objetos del evento. para obtener detalles sobre cómo se organiza la información en el objeto event. La información contenido en el objeto de evento está controlado parcialmente por el valor de la gmail.composeTrigger.draftAccess manifiesto:

  • Si el elemento gmail.composeTrigger.draftAccess manifiesto es NONE o no está incluido, el objeto de evento solo tiene información mínima.

  • Si es gmail.composeTrigger.draftAccess se establece en METADATA, el objeto del evento que se pasa a la función de activación de Compose Se completa con listas de destinatarios del correo electrónico que se está redactando.

Insertar contenido en borradores activos

Por lo general, una IU de Compose para complementos de Google Workspace proporciona las opciones y los controles de usuario que ayudan a redactar un mensaje. Para estos casos de uso, Una vez que el usuario realiza selecciones en la IU, el complemento las interpreta. y actualiza el borrador de correo electrónico actual de trabajo según corresponda.

Para facilitar la actualización del borrador actual de correo electrónico, el servicio de tarjetas se extendió con las siguientes clases:

Por lo general, una IU de redacción complementaria incluye el botón "Guardar". o "Insertar" widget que un usuario puede hacer clic para indicar que terminó de realizar selecciones en la IU y que desea que opciones que se agregarán al correo electrónico que esté redactando. Para agregar esto, sigue estos pasos: interactividad, el widget debe tener un objeto Action asociado que le indica al complemento que ejecute una función de devolución de llamada específica cuando el widget se se hizo clic. Debes implementar estas funciones de devolución de llamada. Cada función de devolución de llamada debe devolver una compilación UpdateDraftActionResponse que detalla los cambios que se realizarán en el borrador actual de correo electrónico.

Ejemplo 1

En el siguiente fragmento de código, se muestra cómo compilar una IU de Compose que actualice el asunto y los destinatarios Para, Cc y Cco del borrador de correo electrónico actual.

    /**
     * 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;
    }

Ejemplo 2

En el siguiente fragmento de código, se muestra cómo compilar una IU de Compose que inserta imágenes. en el borrador actual del correo electrónico.

    /**
     * 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;
    }