Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tiện ích

Tiện ích là một phần tử trên giao diện người dùng cung cấp một hoặc nhiều chức năng sau:

Cấu trúc cho các tiện ích khác, chẳng hạn như thẻ và phần,
Thông tin cho người dùng, chẳng hạn như văn bản và hình ảnh, hoặc
Khả năng thực hiện hành động, chẳng hạn như nút, trường nhập văn bản hoặc hộp đánh dấu.

Các nhóm tiện ích được thêm vào các phần thẻ sẽ xác định giao diện người dùng tổng thể của tiện ích bổ sung. Tiện ích 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 các nhóm 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à lượt tương tác của người dùng.

Tiện ích có cấu trúc

Các tiện ích cấu trúc cung cấp vùng chứa và tổ chức cho các tiện ích khác được dùng trong giao diện người dùng.

Nhóm nút: Một tập hợp gồm một hoặc nhiều nút văn bản hoặc nút hình ảnh, được nhóm lại với nhau trong một hàng ngang.
Thẻ: Một thẻ ngữ cảnh duy nhất chứa một hoặc nhiều phần thẻ. Xác định cách người dùng di chuyển giữa các thẻ bằng cách định cấu hình thao tác đ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 được dùng.
Phần thẻ: Một nhóm các tiện ích được thu thập, phân chia từ các phần thẻ khác bằng một đường kẻ ngang và có thể 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 một phần thẻ.

Ví dụ về một thẻ cho thấy các tiện ích có cấu trúc

Khi thêm một tiện ích vào một trong các vùng chứa, bạn sẽ tạo và thêm một bản sao của tiện ích đó. Nếu bạn thay đổi tiện ích sau khi thêm, thì thay đổi đó sẽ không xuất hiện trong giao diện. Đảm bảo rằng bạn đã hoàn tất việc tạo tiện ích trước khi thêm tiện ích. Nếu cần thay đổi một tiện ích sau khi thêm, hãy tạo lại toàn bộ phần thẻ hoặc thẻ. Hãy xem phần Tạo thẻ để biết thêm thông tin chi tiết.

Ngoài các tiện ích cấu trúc cơ bản này, trong một tiện ích bổ sung Google Workspace, bạn có thể sử dụng Dịch vụ thẻ để tạo các cấu trúc chồng lên thẻ hiện tại: chân trang cố định và thẻ xem 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 phần còn lại của nội dung thẻ.

Ví dụ về tiện ích chân trang cố định

Đoạn mã 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ẻ xem nhanh

Ví dụ về thông báo thẻ xem nhanh

Khi nội dung theo bối 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ư trong Gmail, bạn có thể hiển thị ngay nội dung theo bối cảnh mới (hành vi mặc định) hoặc hiển thị thông báo thẻ xem nhanh ở cuối thanh bên. Nếu người dùng nhấp vào nút Quay lại để quay lại trang chủ trong khi một điều kiện kích hoạt theo bối 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 bối cảnh.

Để hiển thị thẻ xem nhanh khi có nội dung theo bối cảnh mới, hãy thêm .setDisplayStyle(CardService.DisplayStyle.PEEK) vào lớp CardBuilder. Thẻ bật lên chỉ xuất hiện nếu một đối tượng thẻ được trả về cùng với điều kiện kích hoạt theo bối cảnh của bạn; nếu không, các thẻ được trả về sẽ thay thế thẻ hiện tại.

Để tuỳ chỉnh tiêu đề của thẻ xem nhanh, hãy thêm phương thức .setPeekCardHeader bằng một đối tượng CardHeader tiêu chuẩn khi tạo thẻ theo bối cảnh. Theo mặc định, tiêu đề của thẻ Xem nhanh chỉ chứa tên của tiện ích bổ sung. Ví dụ về thẻ xem nhanh được tuỳ chỉnh

Dựa trên Cats Google Workspace add-on quickstart (Hướng dẫn nhanh về tiện ích bổ sung Cats Google Workspace), mã sau đây sẽ thông báo cho người dùng về nội dung theo bối cảnh mới bằng thẻ Xem nhanh và tuỳ chỉnh tiêu đề của thẻ Xem nhanh để hiển thị tiêu đề của chuỗi thư Gmail đã chọn.

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 thông tin cung cấp thông tin cho người dùng.

Hình ảnh: Hình ảnh được chỉ định bằng một URL được lưu trữ và có thể truy cập công khai.
DecoratedText: Một chuỗi nội dung văn bản mà bạn có thể ghép với các phần tử khác, chẳng hạn như nhãn trên cùng và dưới cùng, cũng như hình ảnh hoặc biểu tượng. Tiện ích DecoratedText cũng có thể bao gồm tiện ích Button hoặc Switch. Các công tắc đã 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ó thể sử dụng định dạng HTML; nhãn trên cùng và dưới cùng phải sử dụng văn bản thuần tuý.
Đoạn văn bản: Một đoạn văn bản có thể bao gồm các phần tử được định dạng bằng HTML.

Ví dụ về các tiện ích thông tin trong thẻ

Tiện ích lượt 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 hành động của người dùng. Định cấu hình các tiện ích này bằng các phản hồi hành động để hiển thị các thẻ khác nhau, mở URL, hiển thị thông báo, soạn email nháp hoặc chạy các hàm Apps Script khác. Hãy xem hướng dẫn Tạo thẻ tương tác để biết thông tin chi tiết.

Thao tác trên 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ờ: Tiện ích cho phép người dùng chọn ngày, giờ hoặc cả hai. Hãy xem phần Bộ chọn ngày và giờ để 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. Sử dụng một trong số các biểu tượng được xác định trước hoặc hình ảnh được lưu trữ công khai.
Đầu vào lựa chọn: Một trường nhập dữ liệu đại diện cho một tập hợp các lựa chọn. Tiện ích nhập lựa chọn xuất hiện dưới dạng hộp đánh dấu, nút chọn hoặc hộp lựa chọn thả xuống.
Switch: Một tiện ích bật/tắt dùng với tiện ích DecoratedText. Theo mặc định, các chế độ này sẽ xuất hiện dưới dạng công tắc bật/tắt, nhưng bạn có thể hiển thị chúng dưới dạng hộp đánh dấu.
Nút văn bản: Nút có nhãn văn bản. 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.
Nhập văn bản: Trường nhập dữ liệu văn bản. Tiện ích này có thể có 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 thao tác khi giá trị văn bản thay đổi.
Lưới: Bố cục nhiều cột. Biểu thị các mục bằng hình ảnh, tiêu đề, phụ đề và các lựa chọn tuỳ chỉnh như đường viền và kiểu cắt.

Ví dụ về một trình đơn cho thấy các thao tác với thẻ

Ví dụ về các lượt tương tác của người dùng trong thẻ

Hộp đánh dấu `DecoratedText`

Bạn có thể xác định một tiện ích DecoratedText có hộp đánh dấu được đính kèm, thay vì nút hoặc công tắc bật/tắt nhị phân. Tương tự như công tắc bật/tắt, giá trị của hộp đánh dấu được đưa vào đối tượng sự kiện hành động được truyền đến Action được đính kèm vào DecoratedText này bằng phương thức setOnClickAction.

Ví dụ về tiện ích hộp đánh dấu Decorated-text

Đoạn mã sau đây cho biết cách xác định một tiện ích hộp đánh dấu DecoratedText để 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ờ

Xác định các tiện ích cho phép người dùng chọn giờ, ngày hoặc cả hai. Sử dụng setOnChangeAction để chỉ định một hàm trình xử lý tiện ích cần thực thi khi giá trị của bộ chọn thay đổi.

Ví dụ về thẻ xem nhanh được tuỳ chỉnh

Đoạn mã sau đây cho biết cách xác định bộ chọn chỉ ngày, bộ chọn chỉ giờ và bộ chọn ngày giờ để 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 chọn ngày giờ. Trình xử lý này định dạng và ghi nhật ký một chuỗi biểu thị ngày giờ do người dùng chọn trong một tiện ích bộ chọn ngày giờ có mã nhận dạng 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/workspace/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 lựa chọn của 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 một ngày mới.

Khi người dùng chọn bộ chọn thời gian 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 thành các khoảng thời gian 30 phút. Người dùng cũng có thể nhập một thời gian cụ thể. Trên thiết bị di động, việc chọn bộ chọn thời gian sẽ mở bộ chọn thời gian "đồng hồ" tích hợp trên thiết bị di động.

Máy tính	Thiết bị di động

Lưới

Hiển thị các mục trong 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 lựa 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ột mục lưới.

Định cấu hình một mục trong lưới bằng giá trị nhận dạng được trả về dưới dạng một tham số cho thao tác được xác định trên lưới.

Ví dụ về một tiện ích dạng lưới hiển thị thông tin liên hệ

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 hỗ trợ định dạng HTML văn bản cơ bản. Khi thiết lập nội dung văn bản của các tiện ích này, hãy thêm các thẻ HTML tương ứng.

Các thẻ được hỗ trợ và mục đích của chúng được trình bày trong bảng sau:

Định dạng	Ví dụ	Kết quả được hiển thị
Đậm	`"This is <b>bold</b>."`	Đây là văn bản in đậm.
In nghiêng	`"This is <i>italics</i>."`	Đây là chữ in nghiêng.
Gạch dưới	`"This is <u>underline</u>."`	Đây là gạch dưới.
Gạch ngang chữ	`"This is <s>strikethrough</s>."`	Đây là ~~gạch ngang~~.
Màu phông chữ	`"This is <font color=\"#FF0000\">red font</font>."`	Đây là phông chữ màu đỏ.
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: 2023-02-16 15:00.
Newline	`"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.