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 đơn giản, 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à các phần,
Thông tin cho người dùng như văn bản và hình ảnh, hoặc
Affor Dance cho hành động 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 mục thẻ xác định giao diện người dùng của tiện ích bổ sung tổng thể. Tiện ích này có giao diện và chức năng giống nhau trên cả thiết bị di động và web. Tài liệu tham khảo mô tả một số phương pháp xây dựng bộ tiện ích.

Sử dụng Bộ công cụ thiết kế Tiện ích bổ sung của Google Workspace

Để tiết kiệm thời gian thiết kế tiện ích bổ sung, các nhà thiết kế có thể sử dụng bộ thiết kế giao diện người dùng của tiện ích bổ sung của Google Workspace trên Figma. Bạn có thể tạo tài khoản Figma hoặc yêu cầu quản trị viên của tổ chức cấp giấy phép.

Duyệt qua các thành phần và sử dụng các mẫu có sẵn để tạo và trực quan hoá các tiện ích.

Nhận bộ thiết kế

Các loại tiện ích

Tiện ích bổ sung thường được phân thành ba 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à tổ chức cho các tiện ích khác được sử dụng trong AI.

Tiện ích cấu trúc

Bộ nút – 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 thẻ 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 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. Hành động trên thẻ và hành động chung xuất hiện trong tiêu đề thẻ nếu tiện ích bổ sung đó sử dụng chúng.
Phần thẻ – Một nhóm tiện ích được thu thập, chia thành các phần thẻ khác theo quy tắc ngang và có thể có tiêu đề mụ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 mục thẻ.

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, 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ẻ mắt cáo:

Chân trang cố định

Bây giờ, 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 phần nội dung còn lại của thẻ. Đoạn mã sau đây cho biết cách xác định chân trang cố định mẫu và thêm chân trang đó vào một thẻ:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

Thẻ Peek

Ví dụ về thẻ xem trước

Khi một 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 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ẻ hiển thị ở cuối thanh bên. Nếu người dùng nhấp vào Quay lại để quay lại trang chủ trong khi trình kích hoạt theo ngữ cảnh đang hoạt động, thì 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ị một 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. Thẻ xem trước chỉ xuất hiện nếu một đối tượng thẻ được trả về với trình kích hoạt theo ngữ 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() bằng đối tượng CardHeader chuẩn khi tạo thẻ ngữ cảnh. Theo mặc định, tiêu đề thẻ Peek chỉ chứa tên của tiện ích bổ sung.

Mã sau, dựa trên Hướng dẫn bắt đầu nhanh cho tiện ích bổ sung của Google Workspace, thông báo cho người dùng về nội dung mới theo ngữ cảnh bằng thẻ Peek và tuỳ chỉnh tiêu đề của thẻ Peek để hiển thị chủ đề 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 biểu thị bằng URL truy cập công khai và được lưu trữ mà bạn cung cấp.
decorationdText – Chuỗi nội dung văn bản mà bạn có thể ghép nối với các thành phần 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. Các 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 đơn giản 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; các 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 đơn giản, có thể bao gồm các phần tử được định dạng HTML.

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

Tiện ích hành động trên thẻ

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 của người dùng. Bạn có thể định cấu hình các tiện ích này bằng phản hồi hành động để hiển thị nhiều thẻ, 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 Xây dựng thẻ tương tác để biết thông tin chi tiết.

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

Hành động trên thẻ – Một mục trong trình đơn được đặt trong trình đơn của thanh tiêu đề của tiện ích bổ sung. Trình đơn của 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ờ – những 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ể dùng một trong những biểu tượng được xác định trước hoặc hình ảnh được lưu trữ công khai có URL.
Giá trị nhập vào lựa chọn — Trường nhập dữ liệu đại diện cho một tập hợp các tùy chọn. Các tiện ích đầu vào của 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 chọn thả xuống.
Chuyển đổi—Tiện ích bật/tắt. Bạn chỉ có thể sử dụng các công tắc cùng với tiện ích decorationdText. Theo mặc định, những quảng cáo này xuất hiện dưới dạng nút chuyển đổi, nhưng bạn cũng có thể khiến các quảng cáo này hiển thị dưới dạng hộp đánh dấu.
Nút văn bản — Một 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ể vô hiệu hoá nút này nếu cần.
Nhập bằng văn bản – Trường nhập 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 đạ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 có hình ảnh, tiêu đề, tiêu đề phụ và nhiều lựa chọn tuỳ chỉnh như đường viền và kiểu cắt.

Hộp đánh dấu decorationdText

Bạn có thể xác định một tiện ích DecoratedText có hộp đánh dấu đính kèm, thay vì một nút hoặc nút chuyển 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 được đính kèm vào DecoratedText bằng phương thức setOnClickAction(action).

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

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

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 ngày, giờ hoặc cả hai. Bạn có thể sử dụng setOnChangeAction() để chỉ định một hàm xử lý tiện ích thực thi khi giá trị của bộ chọn thay đổi.

Phần trích dẫn mã 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 the 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 the 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 the date and time in EDT 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 xử lý tiện ích bộ chọn ngày giờ. Trình xử lý này chỉ định dạng và ghi nhật ký một chuỗi đại diện cho ngày giờ mà người dùng chọn trong một tiện ích bộ chọn ngày giờ có mã là "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 bên dưới cho thấy ví dụ về các 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 dựa trên tháng để cho phép người dùng nhanh chó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 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, hãy chọn một bộ chọn giờ để mở bộ chọn giờ "đồng hồ" trên thiết bị di động tích hợp sẵn.

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 tuỳ 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ột mục trong 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ố cho hành động đã xác định trên lưới.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .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. Các định dạng sau được hỗ trợ:

Định dạng	Ví dụ:	Kết quả hiển thị
In đậm	`<b>test</b>`	kiểm tra
In nghiêng	`<i>test</i>`	kiểm tra
Gạch dưới	`<u>test</u>`	kiểm tra
Gạch ngang chữ	`<s>test</s>`	~~kiểm tra~~
Màu phông chữ	`<font color="#ea9999">test</font>`	kiểm tra
Đường siêu liên kết	`<a href="http://www.google.com">google</a>`	google
Thời gian	`<time>2020-02-16 15:00</time>`	16/02/2020 15:00
Dòng mới	`test <br> test`	thử nghiệm thử nghiệm