Trang này được dịch bởi Cloud Translation API.

Tiện ích

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 nội dung sau:

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

Các tập hợp tiện ích được thêm vào các phần thẻ sẽ xác định tổng thể giao diện người dùng 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. Chiến lược phát hành đĩa đơn tài liệu tham khảo mô tả một số phương pháp xây dựng bộ tiện ích.

Các tiện ích bổ sung thường được phân loại thành ba loại 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 kết cấu 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.

Nhóm nút – A tập hợp một hoặc nhiều nút văn bản hoặc hình ảnh, được nhóm lại với nhau trong một hàng ngang.
Thẻ – Một ngữ cảnh duy nhất chứa một hoặc nhiều mục 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 thao tác thẻ.
Tiêu đề thẻ – Thẻ của một thẻ cụ thể. Tiêu đề thẻ có thể chứa tiêu đề, phụ đề và hình ảnh. Thao tác đối với thẻ và hành động chung xuất hiện trong thời gian đầu thẻ nếu tiện ích bổ sung sử dụng chúng.
Mục thẻ – A nhóm tiện ích được thu thập, được chia từ các phần thẻ khác theo quy tắc ngang và có tiêu đề mục (không bắt buộc). 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 thẻ .

Tiện ích cấu trúc

Ngoài các tiện ích cấu trúc cơ bản này, trong một Tiện ích bổ sung của Google Workspace mà 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ẻ 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 phần còn lại của nội dung thẻ.

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

Nội dung sau đây phần trích dẫn mã cho biết cách xác định một chân trang cố định mẫu 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ị

Ví dụ về thẻ xem 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ị ngay nội dung theo ngữ cảnh mới (hành vi mặc định) hoặc hiển thị thông báo thẻ hiển 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 mình trong khi trình kích hoạt theo ngữ cảnh đang hoạt động, một thẻ xem trước sẽ xuất hiện để giúp người dùng tìm thấy 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 CardBuilder . Thẻ xem trước chỉ xuất hiện nếu một đối tượng thẻ duy nhất được trả lại cùng với trình kích hoạt theo ngữ cảnh; nếu không, các thẻ được trả về sẽ ngay lập tức thay thế 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() bằng CardHeader chuẩn khi tạo thẻ ngữ cảnh. Theo mặc định, tiêu đề Thẻ hiển thị chỉ chứa tên của tiện ích bổ sung.

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

Mã sau đây, dựa trên Bắt đầu nhanh tiện ích bổ sung cho Google Workspace về mèo, thông báo cho người dùng về nội dung theo ngữ cảnh mới bằng thẻ Xem nhanh và các tuỳ chỉnh tiêu đề của thẻ Xem nhanh để hiển thị thư Gmail đã chọn chủ đề của chuỗi.

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 thông tin

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

Tiện ích thông tin

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 này phản hồi các hành động do người dùng. Bạn có thể định cấu hình các tiện ích này với 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. Xem Hướng dẫn Tạo thẻ tương tác cho chi tiết.

Thao tác đối với thẻ – Một trình đơn mục đượ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à hành động 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. Xem Bộ chọn ngày và giờ bên dưới để biết thêm thông tin.
Nút hình ảnh – A sử dụng hình ảnh thay vì văn bản. Bạn có thể sử dụng một trong các biểu tượng định sẵn hoặc một hình ảnh được lưu trữ công khai biểu thị bằng URL của hình ảnh đó.
Nhập dữ liệu 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 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.
Công tắc – Nút bật/tắt tiện ích. Bạn chỉ có thể sử dụng công tắc cùng với Tiện ích DecoratedText. Theo mặc định các màn hình này dưới dạng nút bật/tắt, nhưng bạn có thể làm cho chúng hiển thị dưới dạng hộp đánh dấu.
Nút văn bản – A có nhãn văn bản. Bạn có thể chỉ định màu nền cho văn bản (mặc định là trong suốt). Bạn cũng có thể tắt nút này cần thiết.
Nhập văn bản – Văn bản trường nhập dữ liệu. Tiện ích này có thể chứa 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 – Nhiều cột bố cục đạ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 đề, phụ đề và một loạt các tuỳ chọn tuỳ chỉnh như đường viền và cắt.

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

Bạn có thể xác định DecoratedText tiện ích có hộp đánh dấu đi kèm, thay vì nút hoặc nút bật/tắt nhị phân . Giống như nút chuyển, 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 đã đính kèm vào DecoratedText này theo setOnClickAction(action) .

Ví dụ về tiện ích hộp đánh dấu văn bản được trang trí

Phần trích dẫn mã sau đây minh hoạ cách xác định hộp đánh dấu DecoratedText sau đó bạn có thể thêm tiện ích này 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 chức năng trình xử lý tiện ích cho thực thi khi giá trị của bộ chọn thay đổi.

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

Phần trích dẫn mã sau đây minh hoạ cách xác định bộ chọn chỉ có ngày, và bộ chọn ngày giờ mà sau đó 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ề một hàm của trình xử lý tiện ích bộ chọn ngày giờ. Chiến dịch này trình xử lý định dạng và ghi lại một chuỗi đại diện cho ngày giờ đã chọn người dùng trong 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/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 trình bày ví dụ về giao diện người dùng lựa chọn bộ chọn trên máy tính và thiết bị di động thiết bị. Khi được chọn, bộ chọn ngày sẽ mở giao diện người dùng của lịch dựa trên tháng để cho phép để người dùng nhanh chóng chọn 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 để người dùng có thể chọn . Người dùng cũng có thể nhập thời gian cụ thể. Trên thiết bị di động, việc chọn một bộ chọn giờ sẽ mở "đồng hồ" tích hợp sẵn trên thiết bị di động bộ chọn giờ.

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ị 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 tương ứng 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 giá trị nhận dạng được trả về dưới dạng thông số vào hành động được xác định trên lưới.

Ví dụ về tiện ích 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, chỉ cần bao gồm các thẻ HTML tương ứng.

Dưới đây là các thẻ được hỗ trợ và mục đích của chúng bảng:

Định dạng	Ví dụ:	Kết quả được hiển thị
Đậm	`"This is <b>bold</b>."`	Đây là kiểu chữ in đậm.
In nghiêng	`"This is <i>italics</i>."`	Tên này là in nghiêng.
Gạch dưới	`"This is <u>underline</u>."`	Đây là nội dung gạch chân.
Gạch ngang chữ	`"This is <s>strikethrough</s>."`	Đây là chữ ~~gạch ngang chữ~~.
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à 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.
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.

Tiện ích

Các loại tiện ích

Tiện ích cấu trúc

Chân trang cố định

Thẻ hiển thị

Tiện ích thông tin

Tiện ích tương tác của người dùng

DecoratedText hộp đánh dấu

Bộ chọn ngày và giờ

Lưới

Định dạng văn bản

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