Selain menyediakan antarmuka berbasis kartu saat pengguna membaca pesan Gmail, Add-on Google Workspace yang memperluas Gmail dapat menyediakan antarmuka lain ketika pengguna menulis pesan baru atau membalas pesan yang sudah ada. Hal ini memungkinkan Add-on Google Workspace mengotomatiskan tugas menulis email bagi pengguna.
Mengakses UI Compose add-on
Ada dua cara untuk melihat UI compose add-on. Cara pertama adalah mulai menulis draf baru atau membalas saat add-on sudah terbuka. Cara kedua adalah memulai add-on saat membuat draf.
Kedua kasus tersebut akan menyebabkan add-on menjalankan fungsi pemicu compose yang sesuai, yang ditentukan dalam manifes add-on. Fungsi pemicu compose mem-build UI compose untuk tindakan compose tersebut, yang kemudian ditampilkan oleh Gmail kepada pengguna.
Membuat add-on Compose
Anda dapat menambahkan fungsi penulisan ke add-on dengan mengikuti langkah-langkah umum berikut:
- Tambahkan kolom
gmail.composeTrigger
ke manifes project skrip add-on dan perbarui cakupan manifes untuk menyertakan cakupan yang diperlukan untuk tindakan Compose. - Implementasikan fungsi pemicu compose yang mem-build UI compose saat
pemicu diaktifkan. Fungsi pemicu Compose menampilkan satu
objek
Card
atau array objekCard
yang membentuk UI compose untuk tindakan compose. - Implementasikan fungsi callback terkait yang diperlukan untuk bereaksi terhadap interaksi UI Compose pengguna. Fungsi ini bukanlah tindakan compose itu sendiri
(yang hanya menyebabkan UI Compose muncul); fungsi ini adalah
fungsi individual yang mengatur apa yang terjadi saat berbagai elemen
UI Compose 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 akan menampilkan objek
UpdateDraftActionResponse
.
Fungsi pemicu Compose
UI Compose add-on dibuat dengan cara yang sama seperti UI pesan add-on—menggunakan Layanan Kartu Apps Script untuk membuat kartu dan mengisinya dengan widget.
Anda harus mengimplementasikan
gmail.composeTrigger.selectActions[].runFunction
yang Anda tentukan dalam manifes. Fungsi pemicu compose harus menampilkan
satu objek Card
atau
array objek Card
yang membentuk UI compose untuk tindakan tersebut. Fungsi ini sangat mirip dengan fungsi pemicu kontekstual dan akan membuat kartu dengan cara yang sama.
Objek peristiwa pemicu Compose
Jika dipilih, tindakan compose akan menjalankan fungsi pemicu compose yang sesuai dan meneruskan objek peristiwa sebagai parameter ke fungsi. Objek peristiwa dapat membawa informasi tentang konteks add-on dan draf yang sedang disusun ke fungsi pemicu.
Lihat Struktur objek peristiwa untuk mengetahui detail tentang cara pengaturan informasi dalam objek peristiwa. Informasi
yang terdapat dalam objek peristiwa dikontrol sebagian oleh nilai
kolom manifes
gmail.composeTrigger.draftAccess
:
Jika kolom manifes
gmail.composeTrigger.draftAccess
adalahNONE
atau tidak disertakan, objek peristiwa hanya memiliki informasi minimal.Jika
gmail.composeTrigger.draftAccess
ditetapkan keMETADATA
, objek peristiwa yang diteruskan ke fungsi pemicu penulisan akan diisi dengan daftar penerima email yang sedang ditulis.
Menyisipkan konten ke draf aktif
Biasanya, UI tulis Add-on Google Workspace memberikan opsi dan kontrol kepada pengguna yang membantu menulis pesan. Untuk kasus penggunaan ini, setelah pengguna membuat pilihan di UI, add-on akan menafsirkan pilihan dan memperbarui draf email yang berfungsi saat ini sebagaimana mestinya.
Untuk mempermudah pembaruan draf email 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 oleh pengguna Gmail), atau konten teks biasa.UpdateDraftActionResponse
—Merepresentasikan respons terhadap tindakan yang memperbarui draf email saat ini.UpdateDraftActionResponseBuilder
—Builder untuk objekUpdateDraftActionResponse
.UpdateDraftBodyAction
—Merepresentasikan tindakan yang memperbarui isi email draf saat ini.UpdateDraftBodyType
—Enum yang menentukan cara isi diubah.UpdateDraftSubjectAction
—Merepresentasikan tindakan yang memperbarui kolom subjek email draf saat ini.UpdateDraftToRecipientsAction
—Mewakili tindakan yang memperbarui penerima draf email saat ini.UpdateDraftCcRecipientsAction
—Mewakili tindakan yang memperbarui penerima Cc email draf saat ini.UpdateDraftBccRecipientsAction
—Mewakili tindakan yang memperbarui penerima Bcc email draf saat ini.
Biasanya, UI Compose add-on menyertakan widget 'Simpan' atau 'Sisipkan' yang dapat diklik pengguna untuk menunjukkan bahwa mereka telah selesai membuat pilihan di UI dan ingin pilihan mereka ditambahkan ke email yang mereka tulis. Untuk menambahkan
interaktivitas ini, widget harus memiliki
objek Action
terkait yang
menyuruh add-on agar menjalankan fungsi callback tertentu saat widget
diklik. Anda harus menerapkan fungsi callback ini. Setiap fungsi callback harus menampilkan objek UpdateDraftActionResponse
bawaan 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 Kepada, Cc, penerima 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 mem-build 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;
}