Extiende la IU de redacción con más acciones

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

Accede a la IU de redacción de complementos de Google Workspace

Existen dos maneras de ver la IU de redacción de un complemento. La primera es comenzar a redactar un borrador nuevo o responder mientras el complemento ya está abierto. La segunda es iniciar el complemento mientras redactas un borrador.

En cualquier caso, el complemento ejecuta la función de activador de redaccióncorrespondiente, definida en el manifiesto del complemento. La función de activador de redacción compila la IU de redacción para esa acción de redacción, que Gmail luego muestra al usuario.

Compila un complemento de redacción

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

  1. Agrega el gmail.composeTrigger campo al proyecto de secuencia de comandos del complemento manifiesto y actualiza los permisos del manifiesto para incluir los que se requieren para las acciones de redacción.
  2. Implementa una función de activador de redacción que compile una IU de redacción cuando se active el activador. Las funciones de activador de redacción muestran un solo Card objeto o un array de Card objetos que forman la IU de redacción para la acción de redacción.
  3. Implementa las funciones de devolución de llamada asociadas necesarias para reaccionar a las interacciones de la IU de redacción del usuario. Estas funciones no son la acción de redacción en sí (que solo hace que aparezca la IU de redacción); más bien, son las funciones individuales que rigen lo que sucede cuando se seleccionan diferentes elementos de la IU de redacción. Por ejemplo, una tarjeta de la IU que contiene un botón suele tener una función de devolución de llamada asociada que se ejecuta cuando un usuario hace clic en ese botón. La función de devolución de llamada para los widgets que actualizan el contenido del mensaje borrador debe mostrar un UpdateDraftActionResponse objeto.

Función de activador de redacción

La IU de redacción de un complemento se compila de la misma manera que la IU de mensajes del complemento: con el servicio de tarjetas de Apps Script Card service para crear tarjetas y completarlas con widgets.

Debes implementar el gmail.composeTrigger.selectActions[].runFunction que definas en tu manifiesto. La función de activador de redacción debe mostrar un solo Card o un array de Card que forman la IU de redacción para esa acción. Estas funciones son muy similares a las funciones de activador contextuales y deben compilar tarjetas de la misma manera.

Objetos de eventos de activador de redacción

Cuando se selecciona una acción de redacción, se ejecuta la función de activador de redacción correspondiente y se pasa un objeto de evento a la función 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 de activador.

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

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

  • Si gmail.composeTrigger.draftAccess se establece en METADATA, el objeto de evento que se pasa a la función de activador de redacción se propaga con listas de destinatarios del correo electrónico que se está redactando. El uso del acceso al borrador METADATA requiere que el manifiesto del complemento incluya el https://www.googleapis.com/auth/gmail.addons.current.message.metadata permiso de Gmail.

Inserta contenido en borradores activos

Por lo general, una IU de redacción de complementos proporciona al usuario opciones y control que ayudan a redactar un mensaje. Para estos casos de uso, una vez que el usuario realiza selecciones en la IU, el complemento interpreta las selecciones y actualiza el borrador de correo electrónico actual en consecuencia.

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

Por lo general, una IU de redacción de complementos incluye un widget "Guardar" o "Insertar" en el que un usuario puede hacer clic para indicar que terminó de realizar selecciones en la IU y que desea que sus opciones se agreguen al correo electrónico que está redactando. Para agregar esta interactividad, el widget debe tener un objeto Action asociado que le indique al complemento que ejecute una función de devolución de llamada específica cuando se haga clic en el widget. Debes implementar estas funciones de devolución de llamada. Cada función de devolución de llamada debe mostrar un objeto UpdateDraftActionResponse compilado que detalle los cambios que se deben realizar en el correo electrónico borrador actual.

Ejemplo 1

En el siguiente fragmento de código, se muestra cómo compilar una IU de redacción que actualiza el asunto y los destinatarios Para, Con copia y Con copia oculta 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 redacción que inserta imágenes en el correo electrónico borrador 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 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;
}