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

小工具

小工具是一種 UI 元素，可以提供下列一或多項內容：

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

新增至資訊卡部分的小工具組合，會定義外掛程式使用者介面小工具在網頁和行動裝置上顯示的外觀和功能相同。參考說明文件說明瞭幾個建立小工具集的方法。

外掛程式小工具通常分為三類群組：結構小工具資訊小工具和使用者互動小工具

結構小工具

結構小工具提供其他小工具的容器和組織運用在使用者介面中的部分

設定按鈕：A 一或多個文字或圖片按鈕集合，由一組文字或圖片組成水平列。
資訊卡：單一內容含有一或多個資訊卡部分的資訊卡定義使用者移動的方式只要在資訊卡之間設定資訊卡導覽。
資訊卡標題：特定資訊卡的標題資訊卡標題可包含標題、字幕和圖片。資訊卡動作和通用動作會顯示在這個資訊卡標頭 (如果外掛程式的話)。
資訊卡部分：A 收集到的小工具組，除以其他資訊卡區塊並視需要加上區段標題每張卡片都必須包含至少須建立一個卡片區段你無法為資訊卡新增資訊卡或資訊卡標題專區。

結構小工具

除了這些基本的結構小工具之外，可用的 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();

迅速看卡

預覽資訊卡範例

新的情境內容時是由使用者動作 (例如開啟 Gmail 郵件可以讓 Gmail 郵件立即顯示新的內容比對內容。 (預設行為) 或是在頁面底部顯示迅速瀏覽資訊卡通知 側欄中。如果使用者點選「返回」就能返回首頁內容相關觸發條件已啟用，用來協助使用者找到再次指定相關內容

要在有新的相關內容時顯示快速資訊卡，而非立即顯示新的內容比對內容訊息張貼時間：.setDisplayStyle(CardService.DisplayStyle.PEEK)，分享對象： CardBuilder 類別只有一張卡片物件與內容相關觸發條件否則，傳回的卡片會立即取代目前的資訊卡內容

如要自訂預覽資訊卡的標頭，請新增 .setPeekCardHeader() 方法，其中包含標準 CardHeader 物件。預設會顯示 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：A 文字可與其他元素 (如頂端和底部) 配對的內容字串文字標籤以及圖片或圖示DecoratedText 小工具也可以包含 Button 或「切換」小工具。已新增外接切換裝置可以是切換鈕或核取方塊。內容文字 DecoratedText 小工具可以使用 HTML 格式；可觸及和底部標籤必須使用純文字
文字段落：A 文字段落，可包含 HTML 格式元素。

資訊小工具

使用者互動小工具

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

資訊卡動作：選單外掛程式標題列選單中的項目你也可以透過標題列選單包含定義為通用動作的項目會顯示在外掛程式定義的每張資訊卡上
日期時間挑選器：小工具可讓使用者選取日期、時間或兩者並用。詳情請見日期和時間挑選器請參閱下文。
圖片按鈕：A 這個按鈕只會使用圖片而不是文字您可以使用其中一種根據網址指出的預先定義圖示或公開代管圖片。
選取輸入欄位 - 代表選項集合的輸入欄位所選輸入小工具顯示為核取方塊、圓形按鈕或下拉式選取方塊。
切換：切換鈕切換鈕只能與 DecoratedText 小工具。預設這些動作會顯示為切換鈕，但您也可以核取方塊。
文字按鈕：A 包含文字標籤的按鈕您可以為文字指定背景顏色填滿按鈕 (預設為透明)。也可以。
文字輸入：文字輸入欄位小工具可包含標題文字、提示文字和多行文字。當文字值變更時，小工具可能會觸發動作。
方格：多欄代表項目集合的版面配置。您可以使用圖片、標題、副標題和各種自訂選項，如邊框以及裁剪樣式

`DecoratedText` 個核取方塊

您可以定義 DecoratedText 小工具附加了核取方塊，而非按鈕或二元切換切換鈕。和切換按鈕一樣，核取方塊的值也包含在動作事件物件傳遞至 Action 已附加至這個DecoratedText 由 setOnClickAction(action) 方法。

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

以下程式碼片段說明如何定義核取方塊 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 對應至格狀檢視中定義的動作

格線小工具範例

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.` 吋	這是第一行。這是新的路線。

小工具

小工具類型

結構小工具

固定頁尾

迅速看卡

資訊小工具

使用者互動小工具

DecoratedText 個核取方塊

日期和時間挑選器

格線

設定文字格式

`DecoratedText` 個核取方塊