Memperluas UI compose dengan tindakan compose

Selain menyediakan antarmuka berbasis kartu saat pengguna membaca Gmail Add-on Google Workspace yang memperluas fungsi Gmail dapat menyediakan antarmuka lain ketika pengguna menulis pesan baru atau membalas email yang sudah ada. Hal ini memungkinkan Add-on Google Workspace mengotomatiskan tugas penulisan email bagi pengguna.

Mengakses UI compose add-on

Ada dua cara untuk melihat UI compose add-on. Cara pertama adalah dengan memulai membuat draf atau balasan baru saat add-on sudah dibuka. Yang kedua adalah memulai {i>add-on<i} saat membuat draf.

Kedua kasus tersebut menyebabkan add-on mengeksekusi fungsi pemicu compose, yang ditentukan dalam add-on manifes. Fungsi pemicu compose membangun UI compose untuk penulisan tersebut tindakan, yang kemudian ditampilkan Gmail kepada pengguna.

Membuat add-on Compose

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

1. Menambahkan gmail.composeTrigger ke project skrip add-on manifes dan mengupdate manifes cakupan yang perlu disertakan yang diperlukan untuk tindakan compose.
2. Implementasikan fungsi pemicu compose yang membangun UI compose saat pemicu diaktifkan. Fungsi pemicu Compose menampilkan satu Objek Card atau array Objek Card yang menyusun UI compose untuk tindakan compose.
3. Implementasikan fungsi callback terkait yang diperlukan untuk bereaksi terhadap membuat interaksi UI. Fungsi ini bukan tindakan compose itu sendiri (yang hanya menyebabkan UI compose muncul); tapi ini adalah fungsi individu yang mengatur apa yang terjadi ketika elemen yang berbeda dari UI compose dipilih. Misalnya, kartu UI yang berisi tombol biasanya memiliki fungsi callback terkait yang dijalankan saat pengguna mengklik untuk tombol tersebut. Fungsi callback untuk widget yang memperbarui pesan draf konten harus mengembalikan UpdateDraftActionResponse .

Fungsi pemicu Compose

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

Anda harus menerapkan gmail.composeTrigger.selectActions[].runFunction yang ditentukan dalam manifes. Fungsi pemicu compose harus ditampilkan satu objek Card atau array objek Card yang membentuk UI compose untuk tindakan tersebut. Fungsi-fungsi ini sangat mirip ke fungsi pemicu kontekstual dan harus membuat kartu dengan cara yang sama.

Peringatan: Untuk alasan keamanan, add-on tidak dapat mengubah Google Workspace atau pihak ketiga secara otomatis izin akses file. Misalnya, add-on tidak dapat otomatis menambahkan penerima email ke kumpulan akun yang dapat melihat file Dropbox. Sebagai gantinya, add-on harus memberi tahu pengguna bahwa perubahan izin terjadi. add-on yang tidak menginformasikan pengguna bahwa perubahan tersebut tidak dapat diteruskan ulasan add-on.

Objek peristiwa pemicu Compose

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

Lihat Struktur objek peristiwa untuk detail tentang cara mengatur informasi dalam objek peristiwa. Informasi yang ada dalam objek peristiwa dikontrol sebagian oleh nilai gmail.composeTrigger.draftAccess manifes:

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

• Jika gmail.composeTrigger.draftAccess disetel ke METADATA, objek peristiwa yang diteruskan ke fungsi pemicu compose diisi dengan daftar penerima email yang sedang ditulis.

Catatan: Untuk menggunakan akses draf METADATA, manifes add-on harus menyertakan https://www.googleapis.com/auth/gmail.addons.current.message.metadata Cakupan Gmail.

Menyisipkan konten ke dalam draf aktif

Biasanya, UI compose Add-on Google Workspace menyediakan opsi pengguna dan kontrol yang membantu menulis pesan. Untuk kasus penggunaan ini, setelah pengguna membuat pilihan di UI, add-on akan menafsirkan pilihan tersebut dan memperbarui draf email yang saat ini berfungsi sebagaimana mestinya.

Untuk mempermudah pembaruan email draf saat ini, Layanan kartu telah diperluas dengan class berikut:

• ContentType— enum yang menentukan apakah akan menambahkan HTML yang dapat berubah, HTML yang tidak dapat diubah (yang tidak dapat diedit pengguna), atau konten teks biasa.
• UpdateDraftActionResponse—Merepresentasikan respons terhadap tindakan yang memperbarui draf email saat ini.
• UpdateDraftActionResponseBuilder—A pembuat untuk UpdateDraftActionResponse objek terstruktur dalam jumlah besar.
• UpdateDraftBodyAction—Merepresentasikan tindakan yang memperbarui isi draf email saat ini.
• UpdateDraftBodyType— enum yang menentukan bagaimana isi diubah.
• UpdateDraftSubjectAction—Merepresentasikan tindakan yang memperbarui kolom subjek email draf saat ini.
• UpdateDraftToRecipientsAction—Merepresentasikan tindakan yang memperbarui Kepada penerima email draf saat ini.
• UpdateDraftCcRecipientsAction—Merepresentasikan tindakan yang memperbarui penerima Cc email draf saat ini.
• UpdateDraftBccRecipientsAction—Merepresentasikan tindakan yang memperbarui penerima Bcc email draf saat ini.

Biasanya, UI Compose add-on menyertakan tombol 'Simpan' atau 'Sisipkan' yang digunakan pengguna dapat diklik untuk menunjukkan bahwa mereka telah selesai membuat pilihan di UI dan ingin pilihan untuk 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 menerapkan fungsi callback ini. Setiap fungsi callback harus mengembalikan UpdateDraftActionResponse yang merinci perubahan yang akan dilakukan pada draf email saat ini.

Contoh 1

Cuplikan kode berikut menunjukkan cara membuat UI penulisan yang memperbarui subjek, dan Kepada, Cc, penerima Bcc dari 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 membangun UI compose 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;
    }