本頁面由 Cloud Translation API 翻譯而成。

小工具

小工具是提供下列一或多項功能的 UI 元素：

其他小工具的結構，例如資訊卡和區段
提供給使用者的資訊，例如文字和圖片，或
動作的操作選項，例如按鈕、文字輸入欄位或核取方塊。

新增至資訊卡部分的小工具組合會定義整體外掛程式 UI。在電腦和行動裝置上，小工具的外觀和功能都相同。參考說明文件說明瞭幾種建構小工具集合的方法。

外掛小工具通常分為三類：結構性小工具、資訊小工具和使用者互動小工具。

結構性小工具

結構性小工具可為 UI 中使用的其他小工具提供容器和組織。

按鈕組合：一或多個文字或圖像按鈕的集合，以水平列的方式分組。
資訊卡：單一內容資訊卡，其中包含一或多個資訊卡部分。您可以設定資訊卡導覽，定義使用者在資訊卡之間移動的方式。
資訊卡標題：指定資訊卡的標題。資訊卡標題可包含標題、副標題和圖片。如果外掛程式使用資訊卡動作和通用動作，這些動作會顯示在資訊卡標頭中。
資訊卡專區：一組集結的資訊方塊，與其他資訊卡專區以水平線分隔，可視需要加上專區標題。每張資訊卡至少要有一個資訊卡部分。您無法在資訊卡版面中新增資訊卡或資訊卡標題。

結構性小工具

除了這些基本結構小工具外，您還可以在 Google Workspace 外掛程式中使用資訊卡服務，建立與目前資訊卡重疊的結構：固定頁尾和預覽資訊卡：

固定頁尾

您可以在資訊卡底部新增一排固定按鈕。這個列不會隨著資訊卡的其餘內容移動或捲動。

固定底部小工具範例

以下程式碼摘錄顯示如何定義固定底部的範例，並將其新增至資訊卡：

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();

Peek 資訊卡

預覽資訊卡範例

當新的情境內容因使用者操作而觸發時 (例如開啟 Gmail 郵件)，您可以立即顯示新的情境內容 (預設行為)，也可以在側欄底部顯示預覽卡通知。如果使用者在啟用內容觸發條件時按一下「返回」返回首頁，系統就會顯示預覽資訊卡，協助使用者再次找到內容。

如要在有新內容可用時顯示預覽資訊卡，請將 .setDisplayStyle(CardService.DisplayStyle.PEEK) 新增至 CardBuilder 類別，而非立即顯示新內容。只有在透過內容觸發條件傳回單一資訊卡物件時，才會顯示預覽資訊卡；否則，傳回的資訊卡會立即取代目前的資訊卡。

如要自訂窺視卡的標題，請在建構內容卡時，使用標準 CardHeader 物件新增 .setPeekCardHeader() 方法。根據預設，Peek 資訊卡標題只會顯示外掛程式的名稱。

自訂的預覽資訊卡範例

以下程式碼是根據 Cats Google Workspace 外掛程式快速入門，使用 Peek 資訊卡通知使用者新內容的相關內容，並自訂 Peek 資訊卡的標題，以顯示所選 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);

資訊小工具

資訊小工具可向使用者顯示資訊。

圖片：由您提供的代管且可公開存取的網址所指示的圖片。
DecoratedText：文字內容字串，可與其他元素搭配使用，例如頂端和底部的文字標籤，以及圖片或圖示。DecoratedText 小工具也可以包含按鈕或切換鈕小工具。新增的切換鈕可以是切換鈕或核取方塊。DecoratedText 小工具的內容文字可以使用 HTML 格式；頂端和底部的標籤則必須使用純文字。
文字段落：文字段落，可包含HTML 格式元素。

資訊小工具

使用者互動小工具

使用者互動小工具可讓外掛程式回應使用者採取的動作。您可以使用動作回應設定這些小工具，以便顯示不同資訊卡、開啟網址、顯示通知、撰寫電子郵件草稿或執行其他 Apps Script 函式。詳情請參閱「建立互動式資訊卡」指南。

資訊卡動作：放置在外掛程式標頭列選單中的選單項目。標頭列選單還可包含定義為通用動作的項目，這些項目會顯示在附加元件定義的每張資訊卡上。
DateTime 挑選器：可讓使用者選取日期、時間或同時選取二者的小工具。詳情請參閱下方的「日期和時間挑選器」一節。
圖片按鈕：使用圖片而非文字的按鈕。您可以使用其中一個預先定義的圖示，或透過網址指定的公開代管圖片。
選取輸入：代表一組選項的輸入欄位。選取輸入小工具會以核取方塊、圓形按鈕或下拉式選單的形式顯示。
切換鈕：切換式小工具。您只能將切換鈕與 DecoratedText 小工具搭配使用。根據預設，這些元素會顯示為切換鈕，但您可以改為將其顯示為核取方塊。
文字按鈕：含有文字標籤的按鈕。您可以為文字按鈕指定背景顏色填充 (預設為透明)。您也可以視需要停用按鈕。
文字輸入：文字輸入欄位。小工具可以包含標題文字、提示文字和多行文字。當文字值變更時，小工具可以觸發動作。
格狀：多欄版面配置，代表一組項目。您可以使用圖片、標題、副標題，以及邊框和裁剪樣式等各種自訂選項來呈現項目。

`DecoratedText` 核取方塊

您可以定義附有核取方塊的 DecoratedText 小工具，而不是按鈕或二元切換鈕。與切換鈕相同，核取方塊的值會包含在動作事件物件中，並透過 setOnClickAction(action) 方法傳遞至 Action，該物件會附加至 DecoratedText。

裝飾文字核取方塊小工具範例

以下程式碼片段說明如何定義可新增至資訊卡的核取方塊 DecoratedText 小工具：

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

日期和時間挑選器

您可以定義小工具，讓使用者選取時間、日期或同時選取二者。您可以使用 setOnChangeAction() 指派小工具處理常式函式，在選擇器的值變更時執行。

自訂的預覽資訊卡範例

以下程式碼片段說明如何定義僅日期的挑選器、僅時間的挑選器和日期/時間的挑選器，然後將這些挑選器新增至資訊卡：

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"));

以下是日期/時間挑選器小工具處理常式函式的範例。這個處理程序會格式化並記錄字串，代表使用者在日期/時間挑選器小工具中選擇的日期/時間，其 ID 為「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);
  }
}

下表列出電腦和行動裝置上的挑選器選取 UI 範例。選取後，日期挑選器會開啟以月份為基礎的日曆 UI，讓使用者快速選取新日期。

當使用者在電腦裝置上選取時間挑選器時，系統會開啟下拉式選單，列出以 30 分鐘為單位的時間清單，供使用者選取。使用者也可以輸入特定時間。在行動裝置上選取時間挑選器，會開啟內建的行動「時鐘」時間挑選器。

電腦	行動裝置

格線

使用格線小工具，以多欄版面配置顯示項目。每個項目都可以顯示圖片、標題和副標題。使用其他設定選項，設定文字相對於格狀項目中圖片的位置。

您可以使用 ID 設定格線項目，該 ID 會以參數的形式傳回至格線上定義的動作。

格狀小工具範例

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"));

設定文字格式

部分文字小工具支援簡單的 HTML 文字格式。設定這些小工具的文字內容時，只要加入對應的 HTML 標記即可。

下表列出支援的標記及其用途：

格式	範例	算繪結果
粗體	`"This is <b>bold</b>."`	這是粗體字。
斜體	`"This is <i>italics</i>."`	這是斜體字。
底線	`"This is <u>underline</u>."`	這是「底線」。
刪除線	`"This is <s>strikethrough</s>."`	這是~~刪除線~~。
字型顏色	`"This is <font color=\"#FF0000\">red font</font>."`	這是紅色字型。
超連結	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	這是一個超連結。
時間	`"This is a time format: <time>2023-02-16 15:00</time>."`	時間格式如下：2023-02-16 15:00。
換行字元	`"This is the first line. <br> This is a new line.`"	這是第一行。這是新行。

小工具

小工具類型

結構性小工具

固定頁尾

Peek 資訊卡

資訊小工具

使用者互動小工具

DecoratedText 核取方塊

日期和時間挑選器

格線

設定文字格式

`DecoratedText` 核取方塊