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 thành phần 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
• Khả năng thực hiện hành động như nút, trường nhập dữ liệu 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 của thẻ xác định giao diện người dùng tổng thể của tiện ích bổ sung. Tiện ích có cùng giao diện và chức năng 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

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 với 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à tổ chức cho các tiện ích khác được dùng trong giao diện người dùng.

• Tập hợp 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 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 của thẻ. Định nghĩa cách người dùng di chuyển giữa các thẻ bằng cách định cấu hình tính năng điều hướng thẻ.
• Tiêu đề thẻ: Tiêu đề cho một thẻ nhất định. Tiêu đề thẻ có thể có tiêu đề, tiêu đề phụ và hình ảnh. Các thao tác trên thẻ và thao tác phổ biến sẽ xuất hiện trong tiêu đề thẻ nếu được sử dụng.
• Phần của thẻ: Một nhóm tiện ích được thu thập, được phân tách khỏi các phần khác của thẻ bằng một đường ngang và có thể có tiêu đề phần. Mỗi thẻ phải có ít nhất một phần của thẻ. Bạn không thể thêm thẻ hoặc tiêu đề thẻ vào một phần của thẻ.

Khi bạn 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, thay đổi đó sẽ không được phản ánh trong giao diện. Đảm bảo tiện ích đã hoàn tất trước khi thêm. Nếu bạn cần thay đổi một tiện ích sau khi thêm, hãy xây dựng lại toàn bộ phần của thẻ hoặc thẻ. Xem phần Tạo thẻ để biết thêm thông tin.

Ngoài các tiện ích cấu trúc cơ bản này, trong 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 trước:

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ẻ.

Đoạn mã sau đây 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ẻ xem trước

Khi nội dung theo ngữ cảnh mới được kích hoạt bằng một hành động của người dùng, chẳng hạn như mở một 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ẻ xem trước ở cuối thanh bên. Nếu người dùng nhấp vào Quay lại arrow_back để 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, hãy thêm .setDisplayStyle(CardService.DisplayStyle.PEEK) vào lớp CardBuilder. Thẻ xem trước chỉ xuất hiện nếu một đối tượng thẻ được trả về bằng trình kích hoạt theo ngữ cảnh; 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 trước, hãy thêm phương thức .setPeekCardHeader bằng đối tượng CardHeader tiêu chuẩn khi tạo thẻ theo ngữ cảnh. Theo mặc định, tiêu đề thẻ Xem trước chỉ chứa tên của tiện ích bổ sung.

Dựa trên hướng dẫn bắt đầu 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 ngữ cảnh mới bằng thẻ Xem trước và tuỳ chỉnh tiêu đề của thẻ Xem trước để 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 thông tin

Tiện ích thông tin trình bày thông tin cho người dùng.

• **Hình ảnh**: Hình ảnh được biểu thị bằng một URL được lưu trữ và có thể truy cập công khai.
• DecoratedText Tiện ích DecoratedText cũng có thể bao gồm tiện ích Nút hoặc Công tắc. 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 HTML.

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

Tiện ích tương tác với 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 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 để biết thêm thông tin.

• 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 phổ biến, xuất hiện trên mọi thẻ mà tiện ích bổ sung xác định.
• Bộ chọn DateTime: Tiện ích cho phép người dùng chọn ngày, giờ hoặc cả hai. 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.
• Lựa chọn đầu vào: 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 lựa chọn đầu vào hiển thị dưới dạng hộp đánh dấu, nút chọn hoặc hộp lựa chọn thả xuống.
• Công tắc: Một tiện ích bật/tắt được dùng với tiện ích DecoratedText. Theo mặc định, các tiện ích này hiển thị 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 nút văn bản (mặc định là trong suốt). Bạn cũng có thể tắt nút nếu cần.
• Nhập văn bản: Một trường nhập dữ liệu. Tiện ích 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 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. Đại diện cho các mục bằng hình ảnh, tiêu đề, tiêu đề phụ và các lựa chọn tuỳ chỉnh như kiểu đường viền và kiểu cắt.

Hộp đánh dấu DecoratedText

Bạn có thể xác định một DecoratedText tiện ích 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 đính kèm với DecoratedText bằng phương thức setOnClickAction.

Đoạn mã sau đây cho biết cách xác định 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 để gán 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ã 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 bộ chọn ngày-giờ. Trình xử lý này định dạng và ghi lại một chuỗi đại diện cho ngày-giờ do người dùng chọn trong 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 các 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. Khi được chọn, bộ chọn ngày sẽ mở giao diện người dùng lịch dựa trên tháng để cho phép người dùng chọn 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 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 giờ sẽ mở bộ chọn giờ "đồng hồ" di động tích hợp.

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ị hình ảnh, tiêu đề và tiêu đề 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 lưới bằng mã nhận dạng được trả về dưới dạng tham số cho thao tác được 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 hỗ trợ định dạng HTML văn bản cơ bản. Khi đặt nội dung văn bản của các tiện ích này, hãy đư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 trình bày trong bảng sau: