Ngoài việc cung cấp giao diện dựa trên thẻ khi người dùng đang đọc Gmail thư, Tiện ích bổ sung của Google Workspace giúp mở rộng Gmail có thể cung cấp một giao diện khác khi người dùng đang soạn thư mới hoặc đang trả lời những câu hỏi hiện có. Điều này cho phép các Tiện ích bổ sung của Google Workspace tự động hoá tác vụ soạn email cho người dùng.
Truy cập giao diện người dùng của tiện ích bổ sung trong Compose
Có hai cách để xem giao diện người dùng Compose của một tiện ích bổ sung. Cách đầu tiên là bắt đầu soạn thư nháp hoặc thư trả lời mới trong khi tiện ích bổ sung đã mở. Thứ hai là khởi động tiện ích bổ sung trong khi soạn bản nháp.
Một trong hai trường hợp đều khiến tiện ích bổ sung thực thi lệnh gọi hàm kích hoạt Compose, được xác định trong tiện ích bổ sung tệp kê khai. Hàm kích hoạt Compose tạo giao diện người dùng cho Compose đó hành động mà sau đó Gmail sẽ hiển thị cho người dùng.
Tạo tiện ích bổ sung cho Compose
Bạn có thể thêm chức năng soạn thư vào tiện ích bổ sung bằng cách làm theo các bước chung sau:
- Thêm
gmail.composeTrigger
với dự án tập lệnh tiện ích bổ sung tệp kê khai và cập nhật tệp kê khai phạm vi cần đưa vào những yêu cầu bắt buộc đối với thao tác soạn thư. - Triển khai hàm kích hoạt Compose tạo giao diện người dùng khi
trình kích hoạt sẽ kích hoạt. Hàm kích hoạt Compose trả về một giá trị duy nhất
đối tượng
Card
hoặc một mảng Các đối tượngCard
bao gồm giao diện người dùng Compose cho thao tác soạn thư. - Triển khai các hàm callback được liên kết để phản ứng lại các lệnh gọi lại của người dùng
các lượt tương tác trên giao diện người dùng Compose. Các hàm này không phải là chính thao tác Compose
(chỉ khiến giao diện người dùng Compose xuất hiện); đúng hơn, đây là những
các chức năng riêng lẻ chi phối điều sẽ xảy ra khi các phần tử khác nhau của
giao diện người dùng Compose được chọn. Ví dụ: thẻ giao diện người dùng chứa một nút
thường có một hàm callback được liên kết thực thi khi người dùng nhấp vào
nút đó. Hàm callback cho các tiện ích cập nhật tin nhắn nháp
Nội dung nên trả về một giá trị
UpdateDraftActionResponse
.
Hàm kích hoạt Compose
Giao diện người dùng soạn thư của tiện ích bổ sung được xây dựng theo cách giống với thông báo của tiện ích bổ sung Giao diện người dùng – sử dụng dịch vụ Thẻ Apps Script để tạo thẻ và điền chúng bằng tiện ích.
Bạn phải triển khai
gmail.composeTrigger.selectActions[].runFunction
mà bạn xác định trong tệp kê khai. Hàm kích hoạt Compose phải trả về
một đối tượng Card
hoặc
một mảng các đối tượng Card
bao gồm giao diện người dùng Compose cho thao tác đó. Các hàm này rất giống nhau
đến hàm kích hoạt theo ngữ cảnh
và nên xây dựng thẻ theo cách tương tự.
Đối tượng sự kiện kích hoạt Compose
Khi bạn chọn một thao tác soạn thư, thao tác này sẽ thực thi điều kiện kích hoạt tương ứng trong Compose hàm và truyền cho hàm một đối tượng sự kiện dưới dạng tham số. Đối tượng sự kiện có thể mang thông tin về bối cảnh của tiện ích bổ sung và bản nháp đang được kết hợp với chức năng kích hoạt.
Xem bài viết Cấu trúc đối tượng sự kiện
để biết chi tiết về cách thông tin được sắp xếp trong đối tượng sự kiện. Thông tin
có trong đối tượng sự kiện được kiểm soát một phần bởi giá trị của thuộc tính
gmail.composeTrigger.draftAccess
trường tệp kê khai:
Nếu
gmail.composeTrigger.draftAccess
trường tệp kê khai làNONE
hoặc không được đưa vào, đối tượng sự kiện chỉ có tối thiểu thông tin.Nếu
gmail.composeTrigger.draftAccess
được đặt thànhMETADATA
, đối tượng sự kiện được truyền đến hàm kích hoạt Compose được điền sẵn danh sách người nhận email đang được soạn.
Đang chèn nội dung vào bản thảo đang hoạt động
Thông thường, giao diện người dùng Compose Tiện ích bổ sung của Google Workspace cung cấp các tuỳ chọn và chức năng điều khiển cho người dùng giúp soạn thư. Đối với các trường hợp sử dụng này, khi người dùng đã thực hiện lựa chọn trong giao diện người dùng, tiện ích bổ sung sẽ diễn giải các lựa chọn và cập nhật bản nháp email đang làm việc cho phù hợp.
Để cập nhật email nháp hiện tại dễ dàng hơn, hãy nhấp vào Dịch vụ thẻ đã được mở rộng với các lớp sau:
ContentType
— Một enum xác định xem có thêm HTML có thể thay đổi, HTML không thể thay đổi hay không (phiên bản mà Gmail người dùng không thể chỉnh sửa) hoặc nội dung văn bản thuần tuý.UpdateDraftActionResponse
– Đại diện cho phản hồi cho thao tác cập nhật email nháp hiện tại.UpdateDraftActionResponseBuilder
– A trình tạo choUpdateDraftActionResponse
.UpdateDraftBodyAction
– Đại diện cho một thao tác cập nhật nội dung của email nháp hiện tại.UpdateDraftBodyType
— Một enum xác định cách thay đổi phần thân.UpdateDraftSubjectAction
– Đại diện cho một thao tác cập nhật trường tiêu đề của email nháp hiện tại.UpdateDraftToRecipientsAction
– Đại diện cho một thao tác cập nhật mục Đến người nhận của email nháp hiện tại.UpdateDraftCcRecipientsAction
– Đại diện cho một thao tác cập nhật những người nhận Cc của email nháp hiện tại.UpdateDraftBccRecipientsAction
– Đại diện cho một thao tác cập nhật những người nhận Bcc của email nháp hiện tại.
Thông thường, giao diện người dùng của tiện ích bổ sung trong Compose có nút "Lưu" hoặc "Chèn" mà một người dùng
có thể nhấp để cho biết họ đã chọn xong trong giao diện người dùng và muốn biết
các lựa chọn cần thêm vào email mà họ đang soạn. Để thêm nội dung này
tương tác, thì tiện ích phải có
một đối tượng Action
được liên kết
hướng dẫn tiện ích bổ sung chạy một hàm callback cụ thể khi tiện ích này
đã nhấp vào. Bạn phải triển khai các hàm callback này. Mỗi hàm callback phải
trả về một biến đã tạo
UpdateDraftActionResponse
nêu chi tiết các thay đổi cần thực hiện đối với email nháp hiện tại.
Ví dụ 1
Đoạn mã sau đây cho biết cách tạo giao diện người dùng Compose cập nhật tiêu đề và Tới, Cc, Bcc của những người nhận thư nháp hiện tại.
/**
* 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;
}
Ví dụ 2
Đoạn mã sau đây cho biết cách tạo một giao diện người dùng Compose có chèn hình ảnh vào email nháp hiện tại.
/**
* 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;
}