Estensione dell'interfaccia utente di scrittura con le azioni di scrittura

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 di Google Workspace possono automatizzare le attività di scrittura di email per l'utente.

Accesso all'interfaccia utente di scrittura del componente aggiuntivo

Esistono due modi per visualizzare l'interfaccia utente di scrittura di un componente aggiuntivo. Il primo modo consiste nel iniziare a comporre una nuova bozza o risposta mentre il componente aggiuntivo è già aperto. La seconda opzione è avviare il componente aggiuntivo mentre scrivi una bozza.

In entrambi i casi, il componente aggiuntivo esegue la funzione di attivazione della scrittura corrispondente, definita nel manifest del componente aggiuntivo. La funzione di attivazione della composizione crea l'UI di scrittura dell'azione di scrittura, che Gmail mostra all'utente.

Creare un componente aggiuntivo di composizione

Per aggiungere una funzionalità di scrittura a un componente aggiuntivo, segui questi passaggi generali:

  1. Aggiungi il campo gmail.composeTrigger al progetto di script del componente aggiuntivo manifest e aggiorna gli ambiti del manifest per includere quelli richiesti per le azioni di scrittura.
  2. Implementare una funzione di attivazione della scrittura che crei una UI di scrittura quando l'attivatore si attiva. Le funzioni di attivazione della composizione restituiscono un singolo oggetto Card o un array di oggetti Card che comprendono la UI di scrittura dell'azione di scrittura.
  3. Implementare le funzioni di callback associate necessarie per reagire alle interazioni dell'interfaccia utente dell'utente. Queste funzioni non sono l'azione di scrittura (che causa solo la visualizzazione dell'interfaccia utente di scrittura); piuttosto, sono le singole funzioni che regolano cosa succede quando vengono selezionati elementi diversi dell'interfaccia utente di composizione. Ad esempio, una scheda UI che contiene 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 i contenuti della bozza del messaggio dovrebbe restituire un oggetto UpdateDraftActionResponse.

Scrivi funzione trigger

L'UI di composizione di un componente aggiuntivo è costruita nello stesso modo dell'UI del messaggio del componente aggiuntivo, utilizzando il servizio di schede di Apps Script per creare schede e riempirle con widget.

Devi implementare l'elemento gmail.composeTrigger.selectActions[].runFunction che definisci nel manifest. La funzione di attivazione della composizione deve restituire un singolo oggetto Card o un array di oggetti Card che costituiscono la UI di composizione dell'azione. Queste funzioni sono molto simili alle funzioni di attivazione contestuale e dovrebbero creare schede nello stesso modo.

Scrivi oggetti evento trigger

Quando viene selezionata un'azione di scrittura, questa esegue la funzione di composizione corrispondente e la trasmette a un oggetto evento come parametro. L'oggetto evento può includere informazioni sul contesto del componente aggiuntivo e sulla bozza composta dalla funzione trigger.

Per maggiori dettagli su come sono organizzate le informazioni nell'oggetto evento, consulta la sezione Struttura degli oggetti evento. Le informazioni contenute nell'oggetto evento sono controllate in parte dal valore del campo manifest gmail.composeTrigger.draftAccess:

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

  • Se gmail.composeTrigger.draftAccess è impostato su METADATA, l'oggetto evento passato alla funzione di attivazione della composizione viene compilato con gli elenchi di destinatari dell'email da scrivere.

Inserire contenuti nelle bozze attive

In genere, un'interfaccia utente di composizione del componente aggiuntivo di Google Workspace fornisce le opzioni e il controllo utente che consentono di scrivere un messaggio. Per questi casi d'uso, una volta che l'utente ha effettuato delle selezioni nella UI, il componente aggiuntivo le interpreta e aggiorna di conseguenza la bozza dell'email di lavoro corrente.

Per semplificare l'aggiornamento dell'attuale bozza della email, il servizio di carte è stato esteso con i seguenti corsi:

In genere, un'interfaccia utente di composizione aggiuntiva include un widget "Salva" o "Inserisci" su cui l'utente può fare clic per indicare che ha completato le selezioni nell'interfaccia utente e che vuole aggiungere le proprie scelte all'email che sta scrivendo. Per aggiungere questa interattività, al widget deve essere associato un oggetto Action che indica al componente aggiuntivo di eseguire una funzione di callback specifica quando fa clic sul widget. Devi implementare queste funzioni di callback. Ogni funzione di callback deve restituire un oggetto UpdateDraftActionResponse creato che dettagli le modifiche da apportare all'attuale bozza della email.

Esempio 1

Il seguente snippet di codice mostra come creare una UI di scrittura che aggiorni l'oggetto e i destinatari A, Cc e Ccn della bozza email attuale.

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

Lo snippet di codice riportato di seguito mostra come creare una UI di scrittura 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;
    }