Estendere la UI di composizione con le azioni di composizione

Oltre a fornire un'interfaccia basata su schede quando un utente legge un messaggio di Gmail, i componenti aggiuntivi di Google Workspace che estendono Gmail possono fornire un'altra interfaccia quando l'utente compone nuovi messaggi o risponde a quelli esistenti. In questo modo, i componenti aggiuntivi possono automatizzare l'attività di composizione delle email per l'utente.

Accedere all'interfaccia utente di composizione dei componenti aggiuntivi di Google Workspace

Esistono due modi per visualizzare l'interfaccia utente di composizione di un componente aggiuntivo. Il primo consiste nell'iniziare a comporre una nuova bozza o a rispondere mentre il componente aggiuntivo è già aperto. Il secondo consiste nell'avviare il componente aggiuntivo durante la composizione di una bozza.

In entrambi i casi, il componente aggiuntivo esegue la corrispondente funzione di trigger di composizione, definita nel file manifest del componente aggiuntivo. La funzione di trigger di composizione crea l'interfaccia utente di composizione per l'azione di composizione, che Gmail mostra all'utente.

Creare un componente aggiuntivo di composizione

Puoi aggiungere la funzionalità di composizione a un componente aggiuntivo seguendo questi passaggi generali:

  1. Aggiungi il gmail.composeTrigger campo al file manifest del progetto di script del componente aggiuntivo e aggiorna gli ambiti del file manifest in modo da includere quelli richiesti per le azioni di composizione.
  2. Implementa una funzione di trigger di composizione che crea un'interfaccia utente di composizione quando viene attivato il trigger. Le funzioni di trigger di composizione restituiscono un singolo Card oggetto o un array di Card oggetti che formano l'interfaccia utente di composizione per l'azione di composizione.
  3. Implementa le funzioni di callback associate necessarie per reagire alle interazioni dell'utente con l'interfaccia utente di composizione. Queste funzioni non sono l'azione di composizione stessa (che fa apparire solo l'interfaccia utente di composizione), ma sono le singole funzioni che regolano ciò che accade quando vengono selezionati diversi elementi dell'interfaccia utente di composizione. Ad esempio, una scheda dell'interfaccia utente contenente un pulsante di solito ha una funzione di callback associata che viene eseguita quando un utente fa clic sul pulsante. La funzione di callback per i widget che aggiornano il contenuto del messaggio in bozza deve restituire un oggetto.UpdateDraftActionResponse

Funzione di trigger di composizione

L'interfaccia utente di composizione di un componente aggiuntivo viene creata nello stesso modo dell' interfaccia utente dei messaggi del componente aggiuntivo, utilizzando il servizio Card di Apps Script per creare le schede e riempirle con i widget.

Devi implementare il gmail.composeTrigger.selectActions[].runFunction che definisci nel file manifest. La funzione di trigger di composizione deve restituire un singolo Card oggetto o un array di Card oggetti che formano l'interfaccia utente di composizione per l'azione. Queste funzioni sono molto simili a funzioni di trigger contestuali e devono creare le schede nello stesso modo.

Oggetti evento di trigger di composizione

Quando viene selezionata un'azione di composizione, viene eseguita la funzione di trigger di composizione corrispondente e viene passato un oggetto evento alla funzione come parametro. L'oggetto evento può contenere informazioni sul contesto del componente aggiuntivo e sulla bozza in fase di composizione alla funzione di trigger.

Per informazioni dettagliate su come sono disposte le informazioni nell'oggetto evento, consulta Struttura dell'oggetto evento. Le informazioni contenute nell'oggetto evento sono parzialmente controllate dal valore del gmail.composeTrigger.draftAccess campo del file manifest:

  • Se il gmail.composeTrigger.draftAccess campo del file manifest è NONE o non è incluso, l'oggetto evento contiene solo informazioni minime.

  • Se gmail.composeTrigger.draftAccess è impostato su METADATA, l'oggetto evento passato alla funzione di trigger di composizione viene compilato con gli elenchi dei destinatari dell'email in fase di composizione. L'utilizzo dell'accesso alla bozza METADATA richiede che il file manifest del componente aggiuntivo includa l' https://www.googleapis.com/auth/gmail.addons.current.message.metadata ambito Gmail.

Inserire contenuti nelle bozze attive

In genere, l'interfaccia utente di composizione dei componenti aggiuntivi fornisce all'utente opzioni e controlli che lo aiutano a comporre un messaggio. Per questi casi d'uso, una volta che l'utente ha effettuato le selezioni nell'interfaccia utente, il componente aggiuntivo interpreta le selezioni e aggiorna di conseguenza la bozza dell'email corrente.

Per semplificare l'aggiornamento della bozza dell'email corrente, il servizio Card è stato esteso con le seguenti classi:

In genere, l'interfaccia utente di composizione dei componenti aggiuntivi include un widget "Salva" o "Inserisci" su cui un utente può fare clic per indicare di aver terminato le selezioni nell'interfaccia utente e di voler aggiungere le proprie scelte all'email che sta componendo. Per aggiungere questa interattività, il widget deve avere un oggetto associato Action che indica al componente aggiuntivo di eseguire una funzione di callback specifica quando si fa clic sul widget. Devi implementare queste funzioni di callback. Ogni funzione di callback deve restituire un oggetto creato UpdateDraftActionResponse che descrive in dettaglio le modifiche da apportare alla bozza dell'email corrente.

Esempio 1

Il seguente snippet di codice mostra come creare un'interfaccia utente di composizione che aggiorna l'oggetto e i destinatari A, Cc e Ccn della bozza dell'email corrente.

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

Esempio 2

Il seguente snippet di codice mostra come creare un'interfaccia utente di composizione che inserisce immagini nella bozza dell'email corrente.

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