Memperluas UI Compose dengan tindakan Compose

Selain menyediakan antarmuka berbasis kartu saat pengguna membaca pesan Gmail, add-on Google Workspace yang memperluas Gmail dapat menyediakan antarmuka lain saat pengguna menulis pesan baru atau membalas pesan yang ada. Hal ini memungkinkan add-on mengotomatiskan tugas menulis email untuk pengguna.

Mengakses UI tulis add-on Google Workspace

Ada dua cara untuk melihat UI tulis add-on. Cara pertama adalah mulai menulis draf baru atau membalas saat add-on sudah terbuka. Cara kedua adalah memulai add-on saat menulis draf.

Kedua kasus tersebut menyebabkan add-on menjalankan fungsi pemicu tulis yang sesuai, yang ditentukan dalam manifes add-on. Fungsi pemicu tulis membuat UI tulis untuk tindakan tulis tersebut, yang kemudian ditampilkan Gmail kepada pengguna.

Membuat add-on tulis

Anda dapat menambahkan fungsi tulis ke add-on dengan mengikuti langkah-langkah umum berikut:

  1. Tambahkan kolom gmail.composeTrigger ke manifes project skrip add-on dan perbarui cakupan manifes untuk menyertakan cakupan yang diperlukan untuk tindakan tulis.
  2. Implementasikan fungsi pemicu tulis yang membuat UI tulis saat pemicu diaktifkan. Fungsi pemicu tulis menampilkan satu Card objek atau array Card objek yang membentuk UI tulis untuk tindakan tulis.
  3. Implementasikan fungsi callback terkait yang diperlukan untuk bereaksi terhadap interaksi UI tulis pengguna. Fungsi ini bukan tindakan tulis itu sendiri (yang hanya menyebabkan UI tulis muncul); melainkan, fungsi ini adalah fungsi individual yang mengatur apa yang terjadi saat berbagai elemen UI tulis dipilih. Misalnya, kartu UI yang berisi tombol biasanya memiliki fungsi callback terkait yang dijalankan saat pengguna mengklik tombol tersebut. Fungsi callback untuk widget yang memperbarui konten pesan draf harus menampilkan objek UpdateDraftActionResponse.

Fungsi pemicu tulis

UI tulis add-on dibuat dengan cara yang sama seperti UI pesan add-on—menggunakan Apps Script layanan Kartu untuk membuat kartu dan mengisinya dengan widget.

Anda harus mengimplementasikan gmail.composeTrigger.selectActions[].runFunction yang Anda tentukan dalam manifes. Fungsi pemicu tulis harus menampilkan satu Card objek atau array Card objek yang membentuk UI tulis untuk tindakan tersebut. Fungsi ini sangat mirip dengan fungsi pemicu kontekstual dan harus membuat kartu dengan cara yang sama.

Objek peristiwa pemicu tulis

Saat tindakan tulis dipilih, tindakan tersebut akan menjalankan fungsi pemicu tulis yang sesuai dan meneruskan objek peristiwa sebagai parameter ke fungsi tersebut. Objek peristiwa dapat membawa informasi tentang konteks add-on dan draf yang ditulis ke fungsi pemicu.

Lihat Struktur objek peristiwa untuk mengetahui detail tentang cara informasi diatur dalam objek peristiwa. Informasi yang terdapat dalam objek peristiwa sebagian dikontrol oleh nilai kolom manifes gmail.composeTrigger.draftAccess:

  • Jika kolom manifes gmail.composeTrigger.draftAccess adalah NONE atau tidak disertakan, objek peristiwa hanya memiliki informasi minimal.

  • Jika gmail.composeTrigger.draftAccess ditetapkan ke METADATA, objek peristiwa yang diteruskan ke fungsi pemicu tulis akan diisi dengan daftar penerima email yang sedang ditulis. Penggunaan METADATA akses draf mengharuskan manifes add-on menyertakan cakupan https://www.googleapis.com/auth/gmail.addons.current.message.metadata Gmail.

Menyisipkan konten ke dalam draf aktif

Biasanya UI tulis add-on menyediakan opsi dan kontrol pengguna yang membantu menulis pesan. Untuk kasus penggunaan ini, setelah pengguna membuat pilihan di UI, add-on akan menafsirkan pilihan tersebut dan memperbarui draf email kerja saat ini.

Untuk memudahkan pembaruan draf email saat ini, layanan Kartu telah diperluas dengan class berikut:

Biasanya UI tulis add-on menyertakan widget 'Simpan' atau 'Sisipkan' yang dapat diklik pengguna untuk menunjukkan bahwa mereka telah selesai membuat pilihan di UI dan ingin pilihannya ditambahkan ke email yang sedang mereka tulis. Untuk menambahkan interaktivitas, widget harus memiliki objek Action terkait yang menginstruksikan add-on untuk menjalankan fungsi callback tertentu saat widget diklik. Anda harus mengimplementasikan fungsi callback ini. Setiap callback fungsi harus menampilkan objek bawaan UpdateDraftActionResponse yang menjelaskan perubahan yang akan dilakukan pada draf email saat ini.

Contoh 1

Cuplikan kode berikut menunjukkan cara membuat UI tulis yang memperbarui subjek, dan penerima Kepada, Cc, dan Bcc draf email saat ini.

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

Contoh 2

Cuplikan kode berikut menunjukkan cara membuat UI tulis yang menyisipkan gambar ke dalam draf email saat ini.

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