小工具是一種 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>." |
採用時間格式:。 |
換行字元 | "This is the first line. <br> This is a new line. 吋 |
這是第一行。 這是新的路線。 |