Tiện ích là một thành phần trên giao diện người dùng cung cấp một hoặc nhiều tính năng sau:
- Cấu trúc cho các tiện ích khác như thẻ và phần,
- Thông tin cho người dùng như văn bản và hình ảnh, hoặc
- Nội dung cho thao tác chẳng hạn như nút, trường nhập văn bản hoặc hộp đánh dấu.
Tập hợp các tiện ích được thêm vào các phần thẻ sẽ xác định giao diện người dùng tiện ích bổ sung tổng thể. Các tiện ích này có giao diện và chức năng giống nhau trên cả web và thiết bị di động. Tài liệu tham khảo mô tả một số phương thức để tạo tập hợp tiện ích.
Các loại tiện ích
Các tiện ích bổ sung thường được phân loại thành 3 nhóm: tiện ích cấu trúc, tiện ích thông tin và tiện ích tương tác của người dùng.
Tiện ích cấu trúc
Tiện ích cấu trúc cung cấp vùng chứa và cách sắp xếp cho các tiện ích khác được sử dụng trong giao diện người dùng.
- Bộ nút – Tập hợp một hoặc nhiều nút văn bản/hình ảnh, được nhóm với nhau trong một hàng ngang.
- Thẻ: Một thẻ ngữ cảnh chứa một hoặc nhiều phần thẻ. Bạn xác định cách người dùng có thể di chuyển giữa các thẻ bằng cách định cấu hình điều hướng thẻ.
- Tiêu đề thẻ – Tiêu đề của một thẻ nhất định. Tiêu đề thẻ có thể có tiêu đề, phụ đề và hình ảnh. Thao tác trên thẻ và thao tác chung sẽ xuất hiện trong tiêu đề thẻ nếu tiện ích bổ sung sử dụng những thao tác đó.
- Phần thẻ – Một nhóm các tiện ích được thu thập, được chia từ các phần thẻ khác theo quy tắc theo chiều ngang và tuỳ ý có tiêu đề phần. Mỗi thẻ phải có ít nhất một phần thẻ. Bạn không thể thêm thẻ hoặc tiêu đề thẻ vào phần thẻ.
Ngoài các tiện ích cấu trúc cơ bản này, trong Tiện ích bổ sung của Google Workspace, bạn có thể dùng Dịch vụ thẻ để tạo cấu trúc chồng lên thẻ hiện tại: chân trang cố định và thẻ hiển thị nhanh:
Chân trang cố định
Bạn có thể thêm một hàng nút cố định vào cuối thẻ. Hàng này không di chuyển hoặc cuộn cùng với nội dung còn lại trong thẻ.
Đoạn mã trích dẫn sau đây cho biết cách xác định một ví dụ về chân trang cố định và thêm chân trang đó vào thẻ:
var fixedFooter = CardService.newFixedFooter()
.setPrimaryButton(
CardService.newTextButton()
.setText("Primary")
.setOpenLink(CardService.newOpenLink()
.setUrl("https://www.google.com")))
.setSecondaryButton(
CardService.newTextButton()
.setText("Secondary")
.setOnClickAction(
CardService.newAction()
.setFunctionName(
"secondaryCallback")));
var card = CardService.newCardBuilder()
// (...)
.setFixedFooter(fixedFooter)
.build();
Thẻ hiển thị nhanh
Khi nội dung theo ngữ cảnh mới được kích hoạt bởi một hành động của người dùng, chẳng hạn như mở thư Gmail, bạn có thể hiển thị nội dung theo ngữ cảnh mới ngay lập tức (hành vi mặc định) hoặc hiển thị thông báo thẻ nhanh ở cuối thanh bên. Nếu người dùng nhấp vào biểu tượng Quay lại để quay lại trang chủ của bạn trong khi trình kích hoạt theo ngữ cảnh đang hoạt động, thì một thẻ xem trước sẽ xuất hiện để giúp người dùng tìm lại nội dung theo ngữ cảnh.
Để hiển thị thẻ xem trước khi có nội dung theo ngữ cảnh mới, thay vì hiển thị ngay nội dung theo ngữ cảnh mới, hãy thêm .setDisplayStyle(CardService.DisplayStyle.PEEK) vào lớp CardBuilder của bạn. Thẻ xem trước chỉ xuất hiện nếu một đối tượng thẻ duy nhất được trả về bằng điều kiện kích hoạt theo bối cảnh; nếu không, các thẻ được trả về sẽ thay thế ngay thẻ hiện tại.
Để tuỳ chỉnh tiêu đề của thẻ xem trước, hãy thêm phương thức .setPeekCardHeader() với đối tượng CardHeader tiêu chuẩn khi tạo thẻ theo bối cảnh. Theo mặc định, tiêu đề thẻ Peek chỉ chứa tên của tiện ích bổ sung.
Mã sau đây (dựa trên bài viết Bắt đầu nhanh về tiện ích bổ sung Cat Google Workspace) sẽ thông báo cho người dùng về nội dung theo ngữ cảnh mới bằng thẻ Peek và tuỳ chỉnh tiêu đề của thẻ Peek để hiển thị chủ đề của chuỗi thư đã chọn trong Gmail.
var peekHeader = CardService.newCardHeader()
.setTitle('Contextual Cat')
.setImageUrl('https://www.gstatic.com/images/
icons/material/system/1x/pets_black_48dp.png')
.setSubtitle(text);
. . .
var card = CardService.newCardBuilder()
.setDisplayStyle(CardService.DisplayStyle.PEEK)
.setPeekCardHeader(peekHeader);
Tiện ích cung cấp thông tin
Tiện ích cung cấp thông tin hiển thị thông tin cho người dùng.
- Hình ảnh – Hình ảnh được biểu thị bằng một URL truy cập công khai và được lưu trữ mà bạn cung cấp.
- DecoratedText – Chuỗi nội dung văn bản mà bạn có thể ghép nối với các phần tử khác như nhãn văn bản trên cùng và dưới cùng và hình ảnh hoặc biểu tượng. Tiện ích decorationdText cũng có thể bao gồm tiện ích Button (Nút) hoặc Switch (Chuyển đổi). Các nút chuyển đã thêm có thể là nút bật/tắt hoặc hộp đánh dấu. Văn bản nội dung của tiện ích Trang trí có thể sử dụng định dạng HTML; các nhãn trên cùng và dưới cùng phải sử dụng văn bản thuần túy.
- Đoạn văn bản – Đoạn văn bản, có thể bao gồm các phần tử ở định dạng HTML.
Tiện ích tương tác của người dùng
Tiện ích tương tác của người dùng cho phép tiện ích bổ sung phản hồi các thao tác mà người dùng thực hiện. Bạn có thể định cấu hình những tiện ích này bằng các phản hồi hành động để cho thấy nhiều loại thẻ, mở URL, hiện thông báo, soạn email nháp hoặc chạy các chức năng khác của Apps Script. Xem hướng dẫn Xây dựng thẻ tương tác để biết thông tin chi tiết.
- Thao tác với thẻ – Một mục trong trình đơn được đặt trong trình đơn thanh tiêu đề của tiện ích bổ sung. Trình đơn thanh tiêu đề cũng có thể chứa các mục được xác định là thao tác chung, xuất hiện trên mọi thẻ mà tiện ích bổ sung xác định.
- Bộ chọn ngày giờ – các tiện ích cho phép người dùng chọn ngày, giờ hoặc cả hai. Hãy xem Bộ chọn ngày và giờ bên dưới để biết thêm thông tin.
- Nút hình ảnh – Nút sử dụng hình ảnh thay vì văn bản. Bạn có thể sử dụng một trong nhiều biểu tượng xác định trước hoặc hình ảnh được lưu trữ công khai được biểu thị bằng URL của hình ảnh đó.
- Đầu vào lựa chọn – Trường đầu vào biểu thị một tập hợp các tuỳ chọn. Tiện ích nhập lựa chọn hiển thị dưới dạng hộp đánh dấu, nút chọn hoặc hộp chọn thả xuống.
- Switch (Chuyển đổi) – Tiện ích bật/tắt. Bạn chỉ có thể sử dụng nút chuyển cùng với tiện ích DecoratedText. Theo mặc định, các biểu tượng này sẽ hiển thị dưới dạng một nút bật/tắt, nhưng bạn có thể làm cho chúng xuất hiện dưới dạng hộp đánh dấu.
- Nút văn bản – Nút có nhãn văn bản. Bạn có thể chỉ định màu nền cho các nút văn bản (mặc định là trong suốt). Bạn cũng có thể tắt nút này nếu cần.
- Dữ liệu nhập văn bản – Trường nhập dữ liệu văn bản. Tiện ích có thể bao gồm văn bản tiêu đề, văn bản gợi ý và văn bản nhiều dòng. Tiện ích này có thể kích hoạt các hành động khi giá trị văn bản thay đổi.
- Lưới – Bố cục nhiều cột đại diện cho một tập hợp các mục. Bạn có thể biểu thị các mục bằng hình ảnh, tiêu đề, tiêu đề phụ và một loạt tuỳ chọn tuỳ chỉnh như kiểu đường viền và cắt.
DecoratedText hộp đánh dấu
Bạn có thể xác định một tiện ích DecoratedText có đính kèm một hộp đánh dấu, thay vì một nút hoặc công tắc bật/tắt nhị phân. Giống như với nút chuyển, giá trị của hộp đánh dấu sẽ được đưa vào đối tượng sự kiện hành động được chuyển đến Action đính kèm với DecoratedText này bằng phương thức setOnClickAction(action).
Đoạn mã trích dẫn sau đây cho biết cách xác định tiện ích hộp đánh dấu DecoratedText mà sau đó bạn có thể thêm vào thẻ:
var decoratedText = CardService.newDecoratedText()
// (...)
.setSwitch(CardService.newSwitch()
.setFieldName('form_input_switch_key')
.setValue('switch_is_on')
.setControlType(
CardService.SwitchControlType.CHECK_BOX));
Bộ chọn ngày và giờ
Bạn có thể xác định các tiện ích cho phép người dùng chọn giờ, ngày hoặc cả hai.
Bạn có thể sử dụng setOnChangeAction() để chỉ định một hàm trình xử lý tiện ích nhằm thực thi khi giá trị của bộ chọn thay đổi.
Đoạn mã trích dẫn sau đây cho biết cách xác định bộ chọn chỉ ngày, bộ chọn chỉ thời gian và bộ chọn ngày giờ mà bạn có thể thêm vào thẻ:
var dateOnlyPicker = CardService.newDatePicker()
.setTitle("Enter a date")
.setFieldName("date_field")
// Set default value as May 24 2019. Either a
// number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateChange"));
var timeOnlyPicker = CardService.newTimePicker()
.setTitle("Enter a time")
.setFieldName("time_field")
// Set default value as 23:30.
.setHours(23)
.setMinutes(30)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleTimeChange"));
var dateTimePicker = CardService.newDateTimePicker()
.setTitle("Enter a date and time")
.setFieldName("date_time_field")
// Set default value as May 24 2019 03:30 AM UTC.
// Either a number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
// EDT time is 4 hours behind UTC.
.setTimeZoneOffsetInMins(-4 * 60)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateTimeChange"));
Sau đây là ví dụ về hàm trình xử lý tiện ích bộ chọn ngày giờ. Trình xử lý này sẽ định dạng và ghi lại một chuỗi biểu thị ngày giờ mà người dùng đã chọn trong một tiện ích bộ chọn ngày giờ có mã "myDateTimePickerWidgetID":
function handleDateTimeChange(event) {
var dateTimeInput =
event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
var msSinceEpoch = dateTimeInput.msSinceEpoch;
var hasDate = dateTimeInput.hasDate;
var hasTime = dateTimeInput.hadTime;
// The following requires you to configure the add-on to read user locale
// and timezone.
// See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
var userTimezoneId = event.userTimezone.id;
// Format and log the date-time selected using the user's timezone.
var formattedDateTime;
if (hasDate && hasTime) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
} else if (hasDate) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
+ ", Time unspecified";
} else if (hasTime) {
formattedDateTime = "Date unspecified, "
+ Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
}
if (formattedDateTime) {
console.log(formattedDateTime);
}
}
Bảng sau đây cho thấy ví dụ về giao diện người dùng chọn bộ chọn trên máy tính và thiết bị di động. Khi được chọn, bộ chọn ngày sẽ mở giao diện người dùng lịch theo tháng để cho phép người dùng chọn nhanh một ngày mới.
Khi người dùng chọn bộ chọn giờ trên thiết bị máy tính, một trình đơn thả xuống sẽ mở ra với danh sách thời gian được phân tách theo gia số 30 phút mà người dùng có thể chọn. Người dùng cũng có thể nhập một thời gian cụ thể. Trên thiết bị di động khi chọn một bộ chọn giờ, bộ chọn giờ "đồng hồ" tích hợp sẵn trên thiết bị di động sẽ mở ra.
| Máy tính | Di động |
|---|---|
|
|
|
|
Lưới
Hiển thị các mục theo bố cục nhiều cột bằng tiện ích lưới. Mỗi mục có thể hiển thị một hình ảnh, tiêu đề và phụ đề. Sử dụng các tuỳ chọn cấu hình bổ sung để đặt vị trí của văn bản so với hình ảnh trong mục lưới.
Bạn có thể định cấu hình một mục trong lưới bằng một giá trị nhận dạng được trả về dưới dạng tham số cho hành động đã xác định trên lưới.
var gridItem = CardService.newGridItem()
.setIdentifier("item_001")
.setTitle("Lucian R.")
.setSubtitle("Chief Information Officer")
.setImage(imageComponent);
var cropStyle = CardService.newImageCropStyle()
.setImageCropType(CardService.ImageCropType.RECTANGLE_4_3);
var imageComponent = CardService.newImageComponent()
.setImageUrl("https://developers.google.com/workspace/
images/cymbal/people/person1.jpeg")
.setCropStyle(cropStyle)
var grid = CardService.newGrid()
.setTitle("Recently viewed")
.addItem(gridItem)
.setNumColumns(2)
.setOnClickAction(CardService.newAction()
.setFunctionName("handleGridItemClick"));
Định dạng văn bản
Một số tiện ích dựa trên văn bản có thể hỗ trợ định dạng HTML văn bản đơn giản. Khi đặt nội dung văn bản của các tiện ích này, bạn chỉ cần đưa vào các thẻ HTML tương ứng.
Các thẻ được hỗ trợ và mục đích của chúng được thể hiện trong bảng sau:
| Định dạng | Ví dụ: | Kết quả được hiển thị |
|---|---|---|
| Đậm | "This is <b>bold</b>." |
Đây là chữ in đậm. |
| In nghiêng | "This is <i>italics</i>." |
Đây là in nghiêng. |
| Gạch dưới | "This is <u>underline</u>." |
Đây là kiểu gạch dưới. |
| Gạch ngang chữ | "This is <s>strikethrough</s>." |
Đây là tính năng |
| Màu phông chữ | "This is <font color=\"#FF0000\">red font</font>." |
Đây là phông chữ màu đỏ. |
| Đường siêu liên kết | "This is a <a href=\"https://www.google.com\">hyperlink</a>." |
Đây là một siêu liên kết. |
| Thời gian | "This is a time format: <time>2023-02-16 15:00</time>." |
Đây là định dạng thời gian: . |
| Dòng mới | "This is the first line. <br> This is a new line." |
Đây là dòng đầu tiên. Đây là một dòng mới. |