小工具

小工具是一種提供下列一或多項的 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();

預覽資訊卡

預覽資訊卡範例

當使用者動作 (例如開啟 Gmail 訊息) 觸發新的情境內容時,您可以立即顯示新的內容相關內容 (預設行為),或是在側欄底部顯示預覽資訊卡通知。如果使用者點選「返回」 返回首頁,並在情境觸發事件啟用期間,系統會顯示迅速瀏覽資訊卡,協助使用者再次找到相關內容。

如要在有新內容可用時顯示迅速顯示資訊卡,請在 CardBuilder 類別中加入 .setDisplayStyle(CardService.DisplayStyle.PEEK),而不是立即顯示新的內容比對內容。只有在與情境觸發條件一併傳回單一資訊卡物件時,才會顯示預覽資訊卡;否則,傳回的卡片會立即取代目前的卡片。

如要自訂預覽資訊卡的標題,請在建構內容資訊卡時,透過標準 CardHeader 物件新增 .setPeekCardHeader() 方法。根據預設,預覽資訊卡標頭只會包含外掛程式的名稱。

自訂預覽資訊卡範例

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 小工具也可以加入 ButtonSwitch 小工具。新增的切換按鈕可以是切換按鈕或核取方塊。DecoratedText 小工具的內容文字可以使用 HTML 格式;頂部和底部標籤必須使用純文字。
  • Text paragraph (文字段落) - 可包含 HTML 格式元素的文字段落。

資訊小工具

使用者互動小工具

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

  • 資訊卡動作:放在外掛程式標題列選單中的選單項目。標題列選單也可以包含定義為通用動作的項目,會顯示在外掛程式定義的每張資訊卡上。
  • 日期時間挑選器:可讓使用者選取日期、時間或兩者的小工具。詳情請參閱下方的「日期和時間挑選器」一節。
  • 圖片按鈕:使用圖片而非文字的按鈕。您可以使用多個預先定義的圖示,或由其網址指出的公開代管圖片。
  • 選取輸入 - 代表一組選項的輸入欄位。選取輸入小工具會以核取方塊、圓形按鈕或下拉式選取方塊的形式顯示。
  • 切換:切換小工具。只能將切換按鈕與 DecoratedText 小工具搭配使用。根據預設,這些切換鈕會顯示為切換鈕,但您可以將其顯示為核取方塊
  • 文字按鈕:含有文字標籤的按鈕。您可以為文字按鈕指定背景顏色填滿 (預設為透明)。您也可以視需要停用按鈕。
  • Text input (文字輸入):文字輸入欄位。小工具可以包含標題文字、提示文字和多行文字。小工具可在文字值變更時觸發動作。
  • 格線:代表項目集合的多欄版面配置。您可以用圖片、標題、副標題和一系列自訂選項 (例如邊框和裁剪樣式) 來呈現項目。
資訊卡動作小工具 使用者互動小工具

DecoratedText 個核取方塊

您可以定義已附加核取方塊的 DecoratedText 小工具,而不是按鈕或二進位檔切換開關。和切換按鈕一樣,核取方塊值會納入動作事件物件,透過 setOnClickAction(action) 方法附加至此 DecoratedTextAction

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

以下程式碼片段說明如何定義核取方塊 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/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);
  }
}

 

下表為電腦和行動裝置上的挑選器選取使用者介面範例。選取後,日期挑選器會開啟月為單位的日曆 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>." 以下時間格式是
換行字元 "This is the first line. <br> This is a new line. 這是第一行。
這是新的一行。