小工具是一種提供下列一或多項的 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 小工具也可以加入 Button 或 Switch 小工具。新增的切換按鈕可以是切換按鈕或核取方塊。DecoratedText 小工具的內容文字可以使用 HTML 格式;頂部和底部標籤必須使用純文字。
- Text paragraph (文字段落) - 可包含 HTML 格式元素的文字段落。
使用者互動小工具
使用者互動小工具可讓外掛程式回應使用者採取的動作。您可以使用動作回應設定這些小工具,以顯示不同的資訊卡、開啟網址、顯示通知、撰寫電子郵件草稿或執行其他 Apps Script 函式。詳情請參閱建構互動式資訊卡指南。
- 資訊卡動作:放在外掛程式標題列選單中的選單項目。標題列選單也可以包含定義為通用動作的項目,會顯示在外掛程式定義的每張資訊卡上。
- 日期時間挑選器:可讓使用者選取日期、時間或兩者的小工具。詳情請參閱下方的「日期和時間挑選器」一節。
- 圖片按鈕:使用圖片而非文字的按鈕。您可以使用多個預先定義的圖示,或由其網址指出的公開代管圖片。
- 選取輸入 - 代表一組選項的輸入欄位。選取輸入小工具會以核取方塊、圓形按鈕或下拉式選取方塊的形式顯示。
- 切換:切換小工具。只能將切換按鈕與 DecoratedText 小工具搭配使用。根據預設,這些切換鈕會顯示為切換鈕,但您可以將其顯示為核取方塊。
- 文字按鈕:含有文字標籤的按鈕。您可以為文字按鈕指定背景顏色填滿 (預設為透明)。您也可以視需要停用按鈕。
- Text input (文字輸入):文字輸入欄位。小工具可以包含標題文字、提示文字和多行文字。小工具可在文字值變更時觸發動作。
- 格線:代表項目集合的多欄版面配置。您可以用圖片、標題、副標題和一系列自訂選項 (例如邊框和裁剪樣式) 來呈現項目。
DecoratedText
個核取方塊
您可以定義已附加核取方塊的 DecoratedText
小工具,而不是按鈕或二進位檔切換開關。和切換按鈕一樣,核取方塊值會納入動作事件物件,透過 setOnClickAction(action)
方法附加至此 DecoratedText
的 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/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. 吋 |
這是第一行。 這是新的一行。 |