Cards v2

資訊卡

Google Chat 訊息或 Google Workspace 外掛程式中顯示的資訊卡介面。

資訊卡支援定義的版面配置、按鈕等互動式 UI 元素,以及圖片等互動式多媒體。利用資訊卡呈現詳細資訊、向使用者收集資訊,並引導使用者採取下一步。

使用資訊卡建構工具設計及預覽資訊卡。

開啟資訊卡建構工具

如要瞭解如何建構資訊卡,請參閱下列說明文件:

範例:Google Chat 應用程式的資訊卡訊息

聯絡人資訊卡範例

如要在 Google Chat 中建立範例資訊卡訊息,請使用下列 JSON:

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
           "title": "Sasha",
           "subtitle": "Software Engineer",
           "imageUrl":
           "https://developers.google.com/chat/images/quickstart-app-avatar.png",
           "imageType": "CIRCLE",
           "imageAltText": "Avatar for Sasha"
         },
         "sections": [
           {
             "header": "Contact Info",
             "collapsible": true,
             "uncollapsibleWidgetsCount": 1,
             "widgets": [
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "EMAIL"
                   },
                   "text": "sasha@example.com"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PERSON"
                   },
                   "text": "<font color=\"#80e27e\">Online</font>"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PHONE"
                   },
                   "text": "+1 (555) 555-1234"
                 }
               },
               {
                 "buttonList": {
                   "buttons": [
                     {
                       "text": "Share",
                       "onClick": {
                        "openLink": {
                           "url": "https://example.com/share"
                         }
                       }
                     },
                     {
                       "text": "Edit",
                       "onClick": {
                         "action": {
                           "function": "goToView",
                           "parameters": [
                             {
                               "key": "viewType",
                               "value": "EDIT"
                             }
                           ]
                         }
                       }
                     }
                   ]
                 }
               }
             ]
           }
         ]
       }
    }
  ]
}
JSON 表示法
{
  "header": {
    object (CardHeader)
  },
  "sections": [
    {
      object (Section)
    }
  ],
  "sectionDividerStyle": enum (DividerStyle),
  "cardActions": [
    {
      object (CardAction)
    }
  ],
  "name": string,
  "fixedFooter": {
    object (CardFixedFooter)
  },
  "displayStyle": enum (DisplayStyle),
  "peekCardHeader": {
    object (CardHeader)
  }
}
欄位
header

object (CardHeader)

資訊卡的標題。標題通常包含主要圖片和標題。標題一律會顯示在資訊卡頂端。

sections[]

object (Section)

包含一組小工具。每個部分都有專屬的選用標頭。各個區段會以分隔線隔開。如需 Google Chat 應用程式的範例,請參閱資訊卡專區

sectionDividerStyle

enum (DividerStyle)

不同區段之間的分隔線樣式。

cardActions[]

object (CardAction)

資訊卡的動作。系統會將動作新增至資訊卡的工具列選單。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

舉例來說,下列 JSON 會以 SettingsSend Feedback 選項建構資訊卡動作選單:

"cardActions": [
  {
    "actionLabel": "Settings",
    "onClick": {
      "action": {
        "functionName": "goToView",
        "parameters": [
          {
            "key": "viewType",
            "value": "SETTING"
         }
        ],
        "loadIndicator": "LoadIndicator.SPINNER"
      }
    }
  },
  {
    "actionLabel": "Send Feedback",
    "onClick": {
      "openLink": {
        "url": "https://example.com/feedback"
      }
    }
  }
]
name

string

卡片名稱。做為卡片導覽中的卡片 ID。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

displayStyle

enum (DisplayStyle)

在 Google Workspace 外掛程式中,設定 peekCardHeader 的顯示屬性。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

peekCardHeader

object (CardHeader)

顯示相關內容時,預覽資訊卡標頭會做為預留位置,方便使用者在首頁資訊卡和內容資訊卡之間向前瀏覽。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

CardHeader

代表資訊卡標頭。如需 Google Chat 應用程式的範例,請參閱資訊卡標頭

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "title": string,
  "subtitle": string,
  "imageType": enum (ImageType),
  "imageUrl": string,
  "imageAltText": string
}
欄位
title

string

必要欄位。資訊卡標題的標題。標頭的高度固定:如果同時指定標題和副標題,則標題和副標題都會佔一行。如果僅指定標題,則會同時採用兩行。

subtitle

string

資訊卡標題的副標題。如果有指定,系統會在 title 下方單獨一行顯示。

imageType

enum (ImageType)

用來裁剪圖片的形狀。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

imageUrl

string

資訊卡標頭圖片的 HTTPS 網址。

imageAltText

string

這張圖片用於無障礙功能的替代文字。

ImageType

用來裁剪圖片的形狀。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
SQUARE 預設值。為圖片套用正方形遮罩。舉例來說,4x3 的圖片會變成 3x3。
CIRCLE 為圖片套用圓形遮罩。舉例來說,4x3 的圖片會成為帶有直徑 3 的圓形。

區段

區段包含一組小工具,這些小工具會按照指定順序垂直算繪。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "header": string,
  "widgets": [
    {
      object (Widget)
    }
  ],
  "collapsible": boolean,
  "uncollapsibleWidgetsCount": integer
}
欄位
header

string

顯示在區段頂端的文字。支援簡單的 HTML 格式文字。如要進一步瞭解如何設定文字格式,請參閱「在 Google Chat 應用程式中設定文字格式」和「在 Google Workspace 外掛程式中設定文字格式」。

widgets[]

object (Widget)

該區塊中的所有小工具。至少要有一個小工具。

collapsible

boolean

指出這個區段是否可收合。

可收合部分隱藏部分或所有小工具,但使用者按一下「顯示更多」展開該部分,即可顯示隱藏的小工具。使用者只要按一下「顯示較少」,即可再次隱藏小工具。

如要決定要隱藏的小工具,請指定 uncollapsibleWidgetsCount

uncollapsibleWidgetsCount

integer

無法收合的小工具數量,即使區段收合也一樣。

舉例來說,如果區段包含五個小工具,而 uncollapsibleWidgetsCount 設為 2,系統一律會顯示前兩個小工具,而最後三個小工具會預設為收合。只有在 collapsibletrue 時,系統才會將 uncollapsibleWidgetsCount 納入考量。

小工具

每張資訊卡是由小工具組成。

小工具是一種複合物件,可以代表文字、圖片、按鈕和其他物件類型。

JSON 表示法
{
  "horizontalAlignment": enum (HorizontalAlignment),

  // Union field data can be only one of the following:
  "textParagraph": {
    object (TextParagraph)
  },
  "image": {
    object (Image)
  },
  "decoratedText": {
    object (DecoratedText)
  },
  "buttonList": {
    object (ButtonList)
  },
  "textInput": {
    object (TextInput)
  },
  "selectionInput": {
    object (SelectionInput)
  },
  "dateTimePicker": {
    object (DateTimePicker)
  },
  "divider": {
    object (Divider)
  },
  "grid": {
    object (Grid)
  },
  "columns": {
    object (Columns)
  }
  // End of list of possible types for union field data.
}
欄位
horizontalAlignment

enum (HorizontalAlignment)

指定小工具是否要對齊資料欄的左側、右側或中央。

聯集欄位 data。小工具只能包含下列其中一個項目。您可以使用多個小工具欄位顯示更多項目。data 只能採用下列其中一種設定:
textParagraph

object (TextParagraph)

顯示文字段落。支援簡單的 HTML 格式文字。如要進一步瞭解如何設定文字格式,請參閱「在 Google Chat 應用程式中設定文字格式」和「在 Google Workspace 外掛程式中設定文字格式」。

舉例來說,下列 JSON 會建立粗體文字:

"textParagraph": {
  "text": "  <b>bold text</b>"
}
image

object (Image)

顯示圖片。

舉例來說,下列 JSON 會建立含有替代文字的圖片:

"image": {
  "imageUrl":
  "https://developers.google.com/chat/images/quickstart-app-avatar.png",
  "altText": "Chat app avatar"
}
decoratedText

object (DecoratedText)

顯示裝飾的文字項目。

舉例來說,下列 JSON 會建立帶有裝飾的文字小工具,顯示電子郵件地址:

"decoratedText": {
  "icon": {
    "knownIcon": "EMAIL"
  },
  "topLabel": "Email Address",
  "text": "sasha@example.com",
  "bottomLabel": "This is a new Email address!",
  "switchControl": {
    "name": "has_send_welcome_email_to_sasha",
    "selected": false,
    "controlType": "CHECKBOX"
  }
}
buttonList

object (ButtonList)

按鈕清單。

舉例來說,下列 JSON 會建立兩個按鈕。第一個是藍色文字按鈕,第二個是開啟連結的圖片按鈕:

"buttonList": {
  "buttons": [
    {
      "text": "Edit",
      "color": {
        "red": 0,
        "green": 0,
        "blue": 1,
        "alpha": 1
      },
      "disabled": true,
    },
    {
      "icon": {
        "knownIcon": "INVITE",
        "altText": "check calendar"
      },
      "onClick": {
        "openLink": {
          "url": "https://example.com/calendar"
        }
      }
    }
  ]
}
textInput

object (TextInput)

顯示使用者可輸入內容的文字方塊。

舉例來說,下列 JSON 會為電子郵件地址建立文字輸入內容:

"textInput": {
  "name": "mailing_address",
  "label": "Mailing Address"
}

再舉一個例子,下列 JSON 會使用靜態建議,為程式設計語言建立文字輸入內容:

"textInput": {
  "name": "preferred_programing_language",
  "label": "Preferred Language",
  "initialSuggestions": {
    "items": [
      {
        "text": "C++"
      },
      {
        "text": "Java"
      },
      {
        "text": "JavaScript"
      },
      {
        "text": "Python"
      }
    ]
  }
}
selectionInput

object (SelectionInput)

顯示可讓使用者選取項目的選取控制項。選取控制項可以是核取方塊、圓形按鈕、切換按鈕或下拉式選單。

舉例來說,下列 JSON 會建立下拉式選單,讓使用者選擇大小:

"selectionInput": {
  "name": "size",
  "label": "Size"
  "type": "DROPDOWN",
  "items": [
    {
      "text": "S",
      "value": "small",
      "selected": false
    },
    {
      "text": "M",
      "value": "medium",
      "selected": true
    },
    {
      "text": "L",
      "value": "large",
      "selected": false
    },
    {
      "text": "XL",
      "value": "extra_large",
      "selected": false
    }
  ]
}
dateTimePicker

object (DateTimePicker)

顯示可讓使用者輸入日期、時間或日期和時間的小工具。

舉例來說,下列 JSON 會建立日期時間挑選器以安排預約:

"dateTimePicker": {
  "name": "appointment_time",
  "label": "Book your appointment at:",
  "type": "DATE_AND_TIME",
  "valueMsEpoch": "796435200000"
}
divider

object (Divider)

顯示小工具之間的水平分隔線。

舉例來說,下列 JSON 會建立分隔線:

"divider": {
}
grid

object (Grid)

顯示含有一系列項目的格狀檢視畫面。

格線可支援任意數量的欄和項目。資料列數是由項目數量上限除以欄數所決定。含有 10 個項目和 2 個欄的格狀檢視畫面有 5 列。如果格狀檢視畫面中有 11 個項目和 2 個資料欄,該網格有 6 個資料列。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

舉例來說,下列 JSON 會建立含有單一項目的 2 欄格線:

"grid": {
  "title": "A fine collection of items",
  "columnCount": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4
  },
  "items": [
    {
      "image": {
        "imageUri": "https://www.example.com/image.png",
        "cropStyle": {
          "type": "SQUARE"
        },
        "borderStyle": {
          "type": "STROKE"
        }
      },
      "title": "An item",
      "textAlignment": "CENTER"
    }
  ],
  "onClick": {
    "openLink": {
      "url": "https://www.example.com"
    }
  }
}
columns

object (Columns)

最多可顯示 2 欄。

如要加入超過 2 個資料欄,或是使用資料列,請使用 Grid 小工具。

舉例來說,下列 JSON 會建立 2 個資料欄,每個資料欄都含有文字段落:

"columns": {
  "columnItems": [
    {
      "horizontalSizeStyle": "FILL_AVAILABLE_SPACE",
      "horizontalAlignment": "CENTER",
      "verticalAlignment": "CENTER",
      "widgets": [
        {
          "textParagraph": {
            "text": "First column text paragraph"
          }
        }
      ]
    },
    {
      "horizontalSizeStyle": "FILL_AVAILABLE_SPACE",
      "horizontalAlignment": "CENTER",
      "verticalAlignment": "CENTER",
      "widgets": [
        {
          "textParagraph": {
            "text": "Second column text paragraph"
          }
        }
      ]
    }
  ]
}

TextParagraph

支援格式設定的文字段落。如需 Google Chat 應用程式的範例,請參閱文字段落。如要進一步瞭解如何設定文字格式,請參閱「在 Google Chat 應用程式中設定文字格式」和「在 Google Workspace 外掛程式中設定文字格式」。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "text": string
}
欄位
text

string

小工具中顯示的文字。

圖片

由網址指定的圖片,可以具有 onClick 動作。如需範例,請參閱「映像檔」一節。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "imageUrl": string,
  "onClick": {
    object (OnClick)
  },
  "altText": string
}
欄位
imageUrl

string

代管圖片的 HTTPS 網址。

例如:

https://developers.google.com/chat/images/quickstart-app-avatar.png
onClick

object (OnClick)

使用者點選圖片時,就會觸發這項動作。

altText

string

這張圖片用於無障礙功能的替代文字。

OnClick

代表當使用者點選資訊卡上的互動式元素 (例如按鈕) 時的回應方式。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{

  // Union field data can be only one of the following:
  "action": {
    object (Action)
  },
  "openLink": {
    object (OpenLink)
  },
  "openDynamicLinkAction": {
    object (Action)
  },
  "card": {
    object (Card)
  }
  // End of list of possible types for union field data.
}
欄位

聯集欄位 data

data 只能採用下列其中一種設定:

action

object (Action)

如果有指定,這個 onClick 會觸發動作。

card

object (Card)

按下新卡片後,系統會將新卡片推送至卡片堆疊 (如有指定)。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

動作

說明表單提交時的行為。舉例來說,您可以叫用 Apps Script 指令碼來處理表單。如果觸發動作,表單值就會傳送至伺服器。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "function": string,
  "parameters": [
    {
      object (ActionParameter)
    }
  ],
  "loadIndicator": enum (LoadIndicator),
  "persistValues": boolean,
  "interaction": enum (Interaction)
}
欄位
function

string

當使用者點選或突然啟用包含的元素時,要叫用的自訂函式。

如需使用方式範例,請參閱「建立互動式資訊卡」。

parameters[]

object (ActionParameter)

動作參數清單。

loadIndicator

enum (LoadIndicator)

指定動作在呼叫動作時要顯示的載入指標。

persistValues

boolean

指出表單值在動作完成後是否仍會保留。預設值為 false

如果設為 true,表單值會在動作觸發後保留。如要讓使用者在動作處理期間進行變更,請將 LoadIndicator 設為 NONE。如果是即時通訊應用程式中的資訊卡訊息,您也必須將動作的 ResponseType 設為 UPDATE_MESSAGE,並使用包含該動作的卡片中相同的 cardId

如果設為 false,系統會在觸發動作時清除表單值。如要防止使用者在動作處理期間進行變更,請將 LoadIndicator 設為 SPINNER

interaction

enum (Interaction)

選用設定。開啟對話方塊時為必填。

如何回應使用者互動 (例如使用者在卡片訊息中點選按鈕) 的回應。

如未指定,應用程式會照常執行 action (例如開啟連結或執行函式) 來回應。

透過指定 interaction,應用程式能以特殊的互動方式做出回應。例如,將 interaction 設為 OPEN_DIALOG,應用程式就能開啟對話方塊。如果有指定,系統就不會顯示載入指標。如果為外掛程式指定,系統會刪除整張資訊卡,且用戶端不會顯示任何內容。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

ActionParameter

叫用動作方法時,要使用的字串參數清單。舉例來說,你可以考慮設定三個延後按鈕,分別是「立即延後」、「延後一天」或「下週再延後」。您可以使用 action method = snooze(),在字串參數清單中傳遞延後類型和延後時間。

詳情請參閱 CommonEventObject

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "key": string,
  "value": string
}
欄位
key

string

動作指令碼的參數名稱。

value

string

參數值。

LoadIndicator

指定動作在呼叫動作時要顯示的載入指標。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
SPINNER 正在載入旋轉圖示,表示正在載入內容。
NONE 因此不會顯示任何內容。

互動

選用設定。開啟對話方塊時為必填。

如何回應使用者互動 (例如使用者在卡片訊息中點選按鈕) 的回應。

如未指定,應用程式會照常執行 action (例如開啟連結或執行函式) 來回應。

透過指定 interaction,應用程式能以特殊的互動方式做出回應。例如,將 interaction 設為 OPEN_DIALOG,應用程式就能開啟對話方塊

如果有指定,系統就不會顯示載入指標。如果為外掛程式指定,系統會刪除整張資訊卡,且用戶端不會顯示任何內容。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

列舉
INTERACTION_UNSPECIFIED 預設值。action 會照常執行。
OPEN_DIALOG

開啟對話方塊,這是一個視窗式的卡片式介面,供 Chat 應用程式用來與使用者互動。

這項功能僅支援即時通訊應用程式,用於回應卡片訊息的按鈕點擊動作。如果為外掛程式指定,系統會刪除整張資訊卡,且用戶端不會顯示任何內容。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

OpenAs

OnClick 動作開啟連結時,用戶端可選擇以原尺寸視窗 (如果用戶端使用的畫面) 或重疊 (例如彈出式視窗) 開啟連結。實作方式視用戶端平台功能而定,如果用戶端不支援所選值,系統可能會忽略該值。所有用戶端都支援 FULL_SIZE

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

列舉
FULL_SIZE 連結會在完整大小的視窗開啟 (如果這是用戶端使用的頁框)。
OVERLAY 連結會以重疊方式開啟,例如彈出式視窗。

OnClose

透過 OnClick 動作開啟的連結時,用戶端會執行的動作。

實作方式視用戶端平台功能而定。舉例來說,網路瀏覽器可能會透過 OnClose 處理常式以彈出式視窗開啟連結。

如果同時設定 OnOpenOnClose 處理常式,且用戶端平台無法同時支援這兩個值,系統會優先採用 OnClose

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

列舉
NOTHING 預設值。資訊卡不會重新載入;沒有任何反應。
RELOAD

在子項視窗關閉後重新載入資訊卡。

如果與 OpenAs.OVERLAY 搭配使用,子項視窗可做為強制回應對話方塊,且系統會封鎖父項資訊卡,直到子項視窗關閉為止。

DecoratedText

小工具會顯示文字加上選擇性裝飾,例如在文字上方或下方顯示標籤、文字前方的圖示、選取小工具,或文字後方的按鈕。如需 Google Chat 應用程式的範例,請參閱「裝飾文字」一節。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "icon": {
    object (Icon)
  },
  "startIcon": {
    object (Icon)
  },
  "topLabel": string,
  "text": string,
  "wrapText": boolean,
  "bottomLabel": string,
  "onClick": {
    object (OnClick)
  },

  // Union field control can be only one of the following:
  "button": {
    object (Button)
  },
  "switchControl": {
    object (SwitchControl)
  },
  "endIcon": {
    object (Icon)
  }
  // End of list of possible types for union field control.
}
欄位
icon
(deprecated)

object (Icon)

已淘汰,並改用 startIcon

startIcon

object (Icon)

顯示在文字前方的圖示。

topLabel

string

text 上方顯示的文字。一律截斷。

text

string

必要欄位。主要文字。

支援簡易格式設定。如要進一步瞭解如何設定文字格式,請參閱「在 Google Chat 應用程式中設定文字格式」和「在 Google Workspace 外掛程式中設定文字格式」。

wrapText

boolean

自動換行設定。如果是 true,文字會換行並顯示多行。否則文字會遭到截斷。

僅適用於 text,不適用於 topLabelbottomLabel

bottomLabel

string

顯示在 text 下方的文字。一律要換行。

onClick

object (OnClick)

當使用者點選 topLabelbottomLabel 時,就會觸發這項動作。

聯集欄位 control。在 decoratedText 小工具的文字右側顯示的按鈕、切換鈕、核取方塊或圖片。control 只能採用下列其中一種設定:
button

object (Button)

使用者點選以觸發動作的按鈕。

switchControl

object (SwitchControl)

這個切換小工具可讓使用者點選來變更狀態及觸發動作。

endIcon

object (Icon)

顯示在文字後方的圖示。

支援內建自訂圖示。

圖示

資訊卡上的小工具所顯示的圖示。如需 Google Chat 應用程式的範例,請參閱圖示

支援內建自訂圖示。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "altText": string,
  "imageType": enum (ImageType),

  // Union field icons can be only one of the following:
  "knownIcon": string,
  "iconUrl": string,
  "materialIcon": {
    object (MaterialIcon)
  }
  // End of list of possible types for union field icons.
}
欄位
altText

string

選用設定。無障礙功能圖示的說明。如未指定,系統會提供預設值 Button。最佳做法是為圖示顯示的內容和功能設定實用的說明。例如 A user's account portraitOpens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/chat

如果在 Button 中設定圖示,使用者將滑鼠遊標懸停在按鈕上時,altText 會顯示為說明文字。不過,如果按鈕也設定了 text,系統就會忽略圖示的 altText

imageType

enum (ImageType)

套用至圖片的裁剪樣式。在某些情況下,套用 CIRCLE 裁剪會導致圖片繪製大於內建圖示。

聯集欄位 icons。資訊卡小工具中顯示的圖示。icons 只能採用下列其中一種設定:
knownIcon

string

顯示 Google Workspace 提供的其中一個內建圖示。

舉例來說,如要顯示飛機圖示,請指定 AIRPLANE。如果是公車,請指定 BUS

如需完整的支援圖示清單,請參閱「內建圖示」一文。

iconUrl

string

顯示由 HTTPS 網址代管的自訂圖示。

例如:

"iconUrl":
"https://developers.google.com/chat/images/quickstart-app-avatar.png"

支援的檔案類型包括 .png.jpg

materialIcon

object (MaterialIcon)

顯示其中一個 Google 質感設計圖示

舉例來說,如要顯示核取方塊圖示,請使用

"materialIcon": {
  "name": "check_box"
}

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

MaterialIcon

Google Material 圖示,包含超過 2500 個選項。

舉例來說,如要顯示包含自訂權重和成績的核取方塊圖示,請輸入以下內容:

{
  "name": "check_box",
  "fill": true,
  "weight": 300,
  "grade": -25
}

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

JSON 表示法
{
  "name": string,
  "fill": boolean,
  "weight": integer,
  "grade": integer
}
欄位
name

string

Google Material 圖示中定義的圖示名稱,例如 check_box。系統會捨棄任何無效名稱,並以空白字串取代,並導致圖示無法顯示。

fill

boolean

是否顯示填滿圖示。預設值為 false。

如要預覽不同的圖示設定,請前往 Google 字型圖示,然後調整「自訂」底下的設定。

weight

integer

圖示的筆劃粗細。可選擇的類型:{100, 200, 300, 400, 500, 600, 700}。如果缺少,則預設值為 400。如果指定任何其他值,則會使用預設值。

如要預覽不同的圖示設定,請前往 Google 字型圖示,然後調整「自訂」底下的設定。

grade

integer

權重和等級會影響符號的粗細。調整評分方式比調整權重還要精細,而且會對符號大小造成些微影響。請從 {-25, 0, 200} 中選擇。如果留空,預設值為 0。如果指定任何其他值,則會使用預設值。

如要預覽不同的圖示設定,請前往 Google 字型圖示,然後調整「自訂」底下的設定。

按鈕

使用者可點選的文字、圖示,以及文字和圖示按鈕。如需 Google Chat 應用程式的範例,請參閱按鈕清單

如要讓圖片變成可點擊的按鈕,請指定 Image (非 ImageComponent),並設定 onClick 動作。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "text": string,
  "icon": {
    object (Icon)
  },
  "color": {
    object (Color)
  },
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean,
  "altText": string
}
欄位
text

string

按鈕中顯示的文字。

icon

object (Icon)

圖示圖片。如果同時設定了 icontext,圖示會顯示在文字前方。

color

object (Color)

設定後,按鈕會以單色的背景顏色填滿,而字型顏色也會變更,維持與背景顏色的對比度。舉例來說,設定藍色背景可能會產生白色文字。

如未設定,圖片背景為白色,字型顏色則為藍色。

以紅色、綠色和藍色表示,每個欄位的值都是 float 數字,您可以透過以下兩種方式表示:0 到 255 除以 255 (153/255),或介於 0 到 1 (0.6) 的值。0 代表缺少顏色,而 1 或 255/255 則代表該色彩在 RGB 比例中的完整呈現。

您可以選擇設定 alpha,使用以下方程式設定透明度:

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

如果是 alpha1 的值與單色對應,0 值則對應完全透明的顏色。

舉例來說,下列顏色代表半透明的紅色:

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
   "alpha": 0.5
}
onClick

object (OnClick)

必要欄位。使用者點選按鈕 (例如開啟超連結或執行自訂函式) 時要執行的動作。

disabled

boolean

如果為 true,按鈕會呈現停用狀態,且不會回應使用者動作。

altText

string

用於無障礙功能的替代文字。

設定說明文字,讓使用者瞭解按鈕的功能。舉例來說,如果按鈕會開啟超連結,您可以寫「開啟新的瀏覽器分頁,然後前往 https://developers.google.com/chat" 查看 Google Chat 開發人員說明文件」。

Color

代表 RGBA 色域中的顏色。這種呈現方式能簡化與不同語言色彩表示法之間的轉換,而不是密集度。舉例來說,這個表示法的欄位可以透過 Java 輕鬆提供給 java.awt.Color 的建構函式;也可以巧妙地提供給 iOS 中的 UIColor 的 +colorWithRed:green:blue:alpha 方法。而且只要多一點工作,就能在 JavaScript 中輕鬆格式化為 CSS rgba() 字串。

本參考頁面沒有應用於解讀 RGB 值的絕對色彩空間資訊,例如 sRGB、Adobe RGB、DCI-P3 和 BT.2020。根據預設,應用程式應假設為 sRGB 色域。

需要決定顏色相等性時,除非另有說明,否則實作時,如果所有紅色、綠色、藍色和 Alpha 值之間的顏色差異不超過 1e-5,則將兩種顏色視為相等。

範例 (Java):

 import com.google.type.Color;

 // ...
 public static java.awt.Color fromProto(Color protocolor) {
   float alpha = protocolor.hasAlpha()
       ? protocolor.getAlpha().getValue()
       : 1.0;

   return new java.awt.Color(
       protocolor.getRed(),
       protocolor.getGreen(),
       protocolor.getBlue(),
       alpha);
 }

 public static Color toProto(java.awt.Color color) {
   float red = (float) color.getRed();
   float green = (float) color.getGreen();
   float blue = (float) color.getBlue();
   float denominator = 255.0;
   Color.Builder resultBuilder =
       Color
           .newBuilder()
           .setRed(red / denominator)
           .setGreen(green / denominator)
           .setBlue(blue / denominator);
   int alpha = color.getAlpha();
   if (alpha != 255) {
     result.setAlpha(
         FloatValue
             .newBuilder()
             .setValue(((float) alpha) / denominator)
             .build());
   }
   return resultBuilder.build();
 }
 // ...

範例 (iOS / Obj-C):

 // ...
 static UIColor* fromProto(Color* protocolor) {
    float red = [protocolor red];
    float green = [protocolor green];
    float blue = [protocolor blue];
    FloatValue* alpha_wrapper = [protocolor alpha];
    float alpha = 1.0;
    if (alpha_wrapper != nil) {
      alpha = [alpha_wrapper value];
    }
    return [UIColor colorWithRed:red green:green blue:blue alpha:alpha];
 }

 static Color* toProto(UIColor* color) {
     CGFloat red, green, blue, alpha;
     if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) {
       return nil;
     }
     Color* result = [[Color alloc] init];
     [result setRed:red];
     [result setGreen:green];
     [result setBlue:blue];
     if (alpha <= 0.9999) {
       [result setAlpha:floatWrapperWithValue(alpha)];
     }
     [result autorelease];
     return result;
}
// ...

範例 (JavaScript):

// ...

var protoToCssColor = function(rgb_color) {
   var redFrac = rgb_color.red || 0.0;
   var greenFrac = rgb_color.green || 0.0;
   var blueFrac = rgb_color.blue || 0.0;
   var red = Math.floor(redFrac * 255);
   var green = Math.floor(greenFrac * 255);
   var blue = Math.floor(blueFrac * 255);

   if (!('alpha' in rgb_color)) {
      return rgbToCssColor(red, green, blue);
   }

   var alphaFrac = rgb_color.alpha.value || 0.0;
   var rgbParams = [red, green, blue].join(',');
   return ['rgba(', rgbParams, ',', alphaFrac, ')'].join('');
};

var rgbToCssColor = function(red, green, blue) {
  var rgbNumber = new Number((red << 16) | (green << 8) | blue);
  var hexString = rgbNumber.toString(16);
  var missingZeros = 6 - hexString.length;
  var resultBuilder = ['#'];
  for (var i = 0; i < missingZeros; i++) {
     resultBuilder.push('0');
  }
  resultBuilder.push(hexString);
  return resultBuilder.join('');
};

// ...
JSON 表示法
{
  "red": number,
  "green": number,
  "blue": number,
  "alpha": number
}
欄位
red

number

以顏色在 [0, 1] 期間的值,以顏色表示的紅色量。

green

number

在 [0, 1] 期間,以色彩表示的綠色量值。

blue

number

以區間 [0, 1] 為值表示的顏色中的藍色量。

alpha

number

這個色彩應套用至像素的比例。換句話說,最終像素顏色是由以下公式定義:

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

也就是說,值 1.0 對應的是單色,而 0.0 值則對應完全透明的顏色。此做法使用包裝函式訊息 (而非簡單的浮點純量),因此可以區分預設值和未設定的值。如果省略,這個色彩物件會以單色呈現 (如同 Alpha 值明確將 1.0 值指定為 1.0)。

SwitchControl

切換樣式切換按鈕,或 decoratedText 小工具中的核取方塊。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

僅支援 decoratedText 小工具。

JSON 表示法
{
  "name": string,
  "value": string,
  "selected": boolean,
  "onChangeAction": {
    object (Action)
  },
  "controlType": enum (ControlType)
}
欄位
name

string

切換小工具在表單輸入事件中識別的名稱。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

value

string

使用者輸入的值,做為表單輸入事件的一部分傳回。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

selected

boolean

如果為 true,就會選取切換按鈕。

onChangeAction

object (Action)

在切換狀態變更時要執行的動作,例如要執行的函式。

controlType

enum (ControlType)

切換鈕在使用者介面中的顯示方式。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

ControlType

切換鈕在使用者介面中的顯示方式。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
SWITCH 切換樣式的切換按鈕。
CHECKBOX 已淘汰,並改用 CHECK_BOX
CHECK_BOX 核取方塊。

ButtonList

水平排列的按鈕清單。如需 Google Chat 應用程式的範例,請參閱按鈕清單

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "buttons": [
    {
      object (Button)
    }
  ]
}
欄位
buttons[]

object (Button)

一組按鈕。

TextInput

可供使用者輸入文字的欄位。支援建議和變更操作。如需 Google Chat 應用程式的範例,請參閱「文字輸入」一文。

即時通訊應用程式會在表單輸入事件期間接收及處理所輸入文字的值。如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

如需收集使用者未定義或抽象的資料,可以使用文字輸入內容。如要向使用者收集已定義或列舉的資料,請使用 SelectionInput 小工具。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "name": string,
  "label": string,
  "hintText": string,
  "value": string,
  "type": enum (Type),
  "onChangeAction": {
    object (Action)
  },
  "initialSuggestions": {
    object (Suggestions)
  },
  "autoCompleteAction": {
    object (Action)
  },
  "placeholderText": string
}
欄位
name

string

在表單輸入事件中識別文字輸入內容的名稱。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

label

string

使用者介面中的文字輸入欄位上方顯示的文字。

指定有助於使用者輸入應用程式所需資訊的文字。舉例來說,假設您想詢問某人的名字,但特別需要姓氏,請輸入 surname,而不是 name

如未指定 hintText,則為必要欄位。否則則為選填。

hintText

string

顯示在文字輸入欄位下方的文字,提示使用者輸入特定值,藉此協助他們。且會一律顯示這段文字。

如未指定 label,則為必要欄位。否則則為選填。

value

string

使用者輸入的值,做為表單輸入事件的一部分傳回。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

type

enum (Type)

文字輸入欄位在使用者介面中的顯示方式。例如欄位為單行或多行。

onChangeAction

object (Action)

文字輸入欄位發生變更時的處理方式。例如,使用者在欄位中新增或刪除文字。

建議採取的行動包括在 Google Chat 中執行自訂函式或開啟對話方塊

initialSuggestions

object (Suggestions)

建議使用者輸入的值。當使用者按一下文字輸入欄位時,系統就會顯示這些值。當使用者輸入內容時,建議的值會動態篩選,以符合使用者輸入的內容。

舉例來說,程式設計語言的文字輸入欄位可能會提供 Java、JavaScript、Python 和 C++ 的建議。使用者開始輸入 Jav 時,建議篩選器清單只顯示 JavaJavaScript

建議值可協助引導使用者輸入應用程式能理解的值。提及 JavaScript 時,部分使用者可能會輸入 javascript 和其他 java script。建議 JavaScript 可以標準化使用者與應用程式的互動方式。

如果有指定,TextInput.type 一律為 SINGLE_LINE,即使設為 MULTIPLE_LINE 也一樣。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

autoCompleteAction

object (Action)

選用設定。指定當文字輸入欄位向互動者提供建議時要採取的動作。

如未指定,系統會由 initialSuggestions 設定建議並由用戶端處理。

如有指定,應用程式就會執行此處指定的動作,例如執行自訂函式。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

placeholderText

string

欄位空白時,顯示在文字輸入欄位中的文字。請使用這段文字,提示使用者輸入值。例如:Enter a number from 0 to 100

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

類型

文字輸入欄位在使用者介面中的顯示方式。例如單行輸入欄位或多行輸入。如果指定 initialSuggestions,則 type 一律為 SINGLE_LINE,即使設為 MULTIPLE_LINE 也一樣。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
SINGLE_LINE 文字輸入欄位的高度固定為一行。
MULTIPLE_LINE 文字輸入欄位中的高度固定為多行。

RenderActions

一組轉譯操作說明,指示資訊卡執行某項動作,或是指示外掛程式的主機應用程式或 Chat 應用程式執行特定應用程式動作。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

欄位
action

Action

動作

欄位
navigations[]

Navigation

推送或更新顯示的卡片。

在堆疊中新增資訊卡 (向前瀏覽)。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

navigations: {
  pushCard: CARD
}

使用新的資訊卡取代頂端資訊卡。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

navigations: {
  updateCard: CARD
}

建議

建議使用者輸入的值。當使用者按一下文字輸入欄位時,系統就會顯示這些值。當使用者輸入內容時,建議的值會動態篩選,以符合使用者輸入的內容。

舉例來說,程式設計語言的文字輸入欄位可能會提供 Java、JavaScript、Python 和 C++ 的建議。使用者開始輸入 Jav 時,系統會在建議篩選器清單中顯示 JavaJavaScript

建議值可協助引導使用者輸入應用程式能理解的值。提及 JavaScript 時,部分使用者可能會輸入 javascript 和其他 java script。建議 JavaScript 可以標準化使用者與應用程式的互動方式。

如果有指定,TextInput.type 一律為 SINGLE_LINE,即使設為 MULTIPLE_LINE 也一樣。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "items": [
    {
      object (SuggestionItem)
    }
  ]
}
欄位
items[]

object (SuggestionItem)

文字輸入欄位中用於自動完成建議的建議清單。

SuggestionItem

使用者可在文字輸入欄位中輸入的其中一個建議值。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{

  // Union field content can be only one of the following:
  "text": string
  // End of list of possible types for union field content.
}
欄位

聯集欄位 content

content 只能採用下列其中一種設定:

text

string

建議在文字輸入欄位中輸入的值。這相當於使用者自行輸入的內容。

SelectionInput

這個小工具可建立一或多個 UI 項目供使用者選取。例如下拉式選單或核取方塊。您可以使用這個小工具收集可供預測或列舉的資料。如需 Google Chat 應用程式中的範例,請參閱「選擇輸入內容」。

即時通訊應用程式可以處理使用者選取或輸入的項目價值。如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

如要向使用者收集未定義或抽象的資料,請使用 TextInput 小工具。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}
欄位
name

string

用於識別表單輸入事件中選擇輸入內容的名稱。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

label

string

顯示在使用者介面中的選擇輸入欄位上方的文字。

指定有助於使用者輸入應用程式所需資訊的文字。舉例來說,如果使用者從下拉式選單選取工作票證的緊急程度,標籤可能會是「緊急」或「選取緊急程度」。

type

enum (SelectionType)

SelectionInput 小工具中向使用者顯示的項目類型。選取類型支援不同的互動類型。舉例來說,使用者可以勾選一或多個核取方塊,但只能從下拉式選單中選取一個值。

items[]

object (SelectionItem)

可選取項目的陣列。例如一組圓形按鈕或核取方塊。最多可支援 100 個項目。

onChangeAction

object (Action)

如果有指定,系統就會在選取變更後提交表單。如未指定,您必須另外指定用來提交表單的按鈕。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

multiSelectMaxSelectedItems

integer

在複選選單中,使用者可選取的項目數量上限。最小值為 1 個項目。如果未指定,則預設為 3 個項目。

multiSelectMinQueryLength

integer

針對複選選單,系統會在應用程式查詢前,使用者輸入的文字字元數自動完成,並在選單中顯示建議項目。

如果未指定,靜態資料來源的預設值為 0 個字元,外部資料來源則預設為 3 個字元。

聯集欄位 multi_select_data_source。如果是複選選單,則填入選取項目的資料來源。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。 multi_select_data_source 只能採用下列其中一種設定:

externalDataSource

object (Action)

外部資料來源,例如關聯資料庫。

platformDataSource

object (PlatformDataSource)

Google Workspace 的資料來源。

SelectionType

使用者可選擇的項目格式。不同選項支援不同的互動類型。舉例來說,使用者可以一次勾選多個核取方塊,但只能從下拉式選單中選取一個項目。

每項選擇輸入都支援一種選擇類型。例如無法混用核取方塊和切換按鈕等。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
CHECK_BOX 一組核取方塊。使用者可以選取一或多個核取方塊。
RADIO_BUTTON 一組圓形按鈕。使用者可以選取一個圓形按鈕。
SWITCH 一組外接切換裝置。使用者可以啟用一或多個切換按鈕。
DROPDOWN 下拉式選單。使用者可以從選單中選取一個項目。
MULTI_SELECT

靜態或動態資料的複選選單。使用者在選單列中選取一或多個項目。使用者也可以輸入值來填入動態資料。舉例來說,使用者只要輸入 Google Chat 聊天室的名稱,小工具就會自動建議聊天室。

如要為複選選單填入項目,可以使用下列其中一種資料來源:

  • 靜態資料:項目在小工具中會指定為 SelectionItem 物件。最多 100 個項目。
  • Google Workspace 資料:系統會運用 Google Workspace 使用者或 Google Chat 聊天室等 Google Workspace 資料填入項目。
  • 外部資料:系統會從 Google Workspace 以外的外部資料來源填入項目。

如需實作複選選單的範例,請參閱 SelectionInput 小工具頁面

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。開發人員預覽版為 Google Workspace 外掛程式的多個選項。

SelectionItem

使用者可以在選擇輸入項目中選取的項目,例如核取方塊或切換按鈕。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}
欄位
text

string

向使用者識別或描述項目的文字。

value

string

與這個項目相關聯的值。用戶端應使用這個值做為表單輸入值。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

selected

boolean

該項目是否預設為選取狀態。如果選項輸入欄位只接受一個值 (例如圓形按鈕或下拉式選單),請只針對一個項目設定此欄位。

startIconUri

string

如果是複選選單,該項目的 text 欄位旁邊會顯示圖示的網址。支援 PNG 和 JPEG 檔案。必須是 HTTPS 網址。例如:https://developers.google.com/chat/images/quickstart-app-avatar.png

bottomText

string

複選選單會顯示在該項目的 text 欄位下方的文字說明或標籤。

PlatformDataSource

如果 SelectionInput 小工具使用複選選單,則為 Google Workspace 的資料來源。用於在複選選單中填入項目。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

JSON 表示法
{

  // Union field data_source can be only one of the following:
  "commonDataSource": enum (CommonDataSource),
  "hostAppDataSource": {
    object (HostAppDataSourceMarkup)
  }
  // End of list of possible types for union field data_source.
}
欄位
聯集欄位 data_source。資料來源。data_source 只能採用下列其中一種設定:
commonDataSource

enum (CommonDataSource)

所有 Google Workspace 應用程式 (例如 Google Workspace 機構使用者) 共用的資料來源。

hostAppDataSource

object (HostAppDataSourceMarkup)

Google Workspace 代管應用程式專用的資料來源,例如 Google Chat 中的聊天室。

CommonDataSource

所有 Google Workspace 應用程式共用的資料來源。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

列舉
UNKNOWN 預設值。請勿使用。
USER Google Workspace 使用者。使用者只能在 Google Workspace 機構中查看及選取使用者。

HostAppDataSourceMarkup

如果 SelectionInput 小工具使用複選選單,這是來自 Google Workspace 應用程式的資料來源。資料來源會為複選選單填入所選項目。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

JSON 表示法
{

  // Union field data_source can be only one of the following:
  "chatDataSource": {
    object (ChatClientDataSourceMarkup)
  }
  // End of list of possible types for union field data_source.
}
欄位
聯集欄位 data_source。這個 Google Workspace 應用程式可填入複選選單的項目。data_source 只能採用下列其中一種設定:
chatDataSource

object (ChatClientDataSourceMarkup)

Google Chat 的資料來源。

ChatClientDataSourceMarkup

如果 SelectionInput 小工具使用複選選單,則為 Google Chat 的資料來源。資料來源會為複選選單填入所選項目。舉例來說,使用者可以選取他們所屬的 Google Chat 聊天室。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

JSON 表示法
{

  // Union field source can be only one of the following:
  "spaceDataSource": {
    object (SpaceDataSource)
  }
  // End of list of possible types for union field source.
}
欄位
聯集欄位 source。Google Chat 資料來源。 source 只能採用下列其中一種設定:
spaceDataSource

object (SpaceDataSource)

使用者所屬的 Google Chat 聊天室。

SpaceDataSource

這個資料來源可將 Google Chat 聊天室填入複選選單的選取項目。只填入使用者所屬的聊天室。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

JSON 表示法
{
  "defaultToCurrentSpace": boolean
}
欄位
defaultToCurrentSpace

boolean

如果設為 true,則複選選單預設會選取目前的 Google Chat 聊天室項目。

DateTimePicker

可讓使用者輸入日期或時間,或同時輸入日期和時間。如需 Google Chat 應用程式的範例,請參閱「日期時間挑選器」。

使用者可以輸入文字,或使用挑選器選取日期和時間。如果使用者輸入的日期或時間無效,挑選器會顯示錯誤,提示使用者正確輸入資訊。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "name": string,
  "label": string,
  "type": enum (DateTimePickerType),
  "valueMsEpoch": string,
  "timezoneOffsetDate": integer,
  "onChangeAction": {
    object (Action)
  }
}
欄位
name

string

DateTimePicker 在表單輸入事件中識別的名稱。

如要進一步瞭解如何使用表單輸入內容,請參閱「接收表單資料」。

label

string

提示使用者輸入日期、時間或日期和時間的文字。舉例來說,如果使用者正在安排預約,請使用 Appointment dateAppointment date and time 等標籤。

type

enum (DateTimePickerType)

小工具是否支援輸入日期、時間,或日期和時間。

valueMsEpoch

string (int64 format)

小工具中顯示的預設值 (自 Unix 紀元時間以來的毫秒數)。

根據挑選器類型 (DateTimePickerType) 指定值:

  • DATE_AND_TIME :以世界標準時間為準的日曆日期和時間。舉例來說,如要代表世界標準時間 2023 年 1 月 1 日中午 12 點,請使用 1672574400000
  • DATE_ONLY :日曆日期為世界標準時間 00:00:00。舉例來說,如要表示 2023 年 1 月 1 日,請使用 1672531200000
  • TIME_ONLY:以世界標準時間為準的時間。舉例來說,如要代表下午 12:00,請使用 43200000 (或 12 * 60 * 60 * 1000)。
timezoneOffsetDate

integer

代表時區與世界標準時間偏移的數字 (以分鐘為單位)。如果設定這個項目,valueMsEpoch 會顯示在指定時區。如未設定,該值會預設為使用者的時區設定。

onChangeAction

object (Action)

當使用者從 DateTimePicker 介面點選「儲存」或「清除」時,就會觸發這個事件。

DateTimePickerType

DateTimePicker 小工具中日期和時間的格式。決定使用者是否能輸入日期、時間,或同時輸入日期和時間。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
DATE_AND_TIME 使用者輸入日期和時間。
DATE_ONLY 使用者輸入日期。
TIME_ONLY 使用者輸入時間。

分隔線

這個類型沒有任何欄位。

以水平線顯示小工具之間的分隔線。如需 Google Chat 應用程式的範例,請參閱 Divider

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

舉例來說,下列 JSON 會建立分隔線:

"divider": {}

網格

顯示含有一系列項目的格狀檢視畫面。項目只能包含文字或圖片。如果是回應式資料欄,或者如要加入更多文字或圖片,請使用 Columns。如需 Google Chat 應用程式的範例,請參閱格線

格線可支援任意數量的欄和項目。資料列數是由項目除以資料欄所決定。含有 10 個項目和 2 個欄的格狀檢視畫面有 5 列。如果格狀檢視畫面中有 11 個項目和 2 個資料欄,該網格有 6 個資料列。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

舉例來說,下列 JSON 會建立含有單一項目的 2 欄格線:

"grid": {
  "title": "A fine collection of items",
  "columnCount": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4
  },
  "items": [
    {
      "image": {
        "imageUri": "https://www.example.com/image.png",
        "cropStyle": {
          "type": "SQUARE"
        },
        "borderStyle": {
          "type": "STROKE"
        }
      },
      "title": "An item",
      "textAlignment": "CENTER"
    }
  ],
  "onClick": {
    "openLink": {
      "url": "https://www.example.com"
    }
  }
}
JSON 表示法
{
  "title": string,
  "items": [
    {
      object (GridItem)
    }
  ],
  "borderStyle": {
    object (BorderStyle)
  },
  "columnCount": integer,
  "onClick": {
    object (OnClick)
  }
}
欄位
title

string

格狀標題中顯示的文字。

items[]

object (GridItem)

格狀顯示的項目。

borderStyle

object (BorderStyle)

要套用至每個格線項目的框線樣式。

columnCount

integer

格狀檢視中顯示的欄數。如未指定這個欄位,系統會使用預設值,且預設值會因格狀顯示位置 (對話方塊與隨播廣告) 而不同。

onClick

object (OnClick)

每個格線項目都會重複使用這個回呼,但會將項目清單中的商品 ID 和索引新增至回呼的參數。

GridItem

此元素代表格狀版面配置中的項目。項目可以包含文字或圖片,或同時包含文字和圖片。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "id": string,
  "image": {
    object (ImageComponent)
  },
  "title": string,
  "subtitle": string,
  "layout": enum (GridItemLayout)
}
欄位
id

string

這個格線項目的使用者指定 ID。這個 ID 會以父項格線的 onClick 回呼參數傳回。

image

object (ImageComponent)

在格線項目中顯示的圖片。

title

string

格線項目的標題。

subtitle

string

格線項目的子標題。

layout

enum (GridItemLayout)

格線項目使用的版面配置。

ImageComponent

代表圖片。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "imageUri": string,
  "altText": string,
  "cropStyle": {
    object (ImageCropStyle)
  },
  "borderStyle": {
    object (BorderStyle)
  }
}
欄位
imageUri

string

圖片網址。

altText

string

圖片的無障礙標籤。

cropStyle

object (ImageCropStyle)

要套用至圖片的裁剪樣式。

borderStyle

object (BorderStyle)

要套用至圖片的邊框樣式。

ImageCropStyle

此屬性代表套用至圖片的裁剪樣式。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

以下說明如何套用 16:9 長寬比:

cropStyle {
 "type": "RECTANGLE_CUSTOM",
 "aspectRatio": 16/9
}
JSON 表示法
{
  "type": enum (ImageCropType),
  "aspectRatio": number
}
欄位
type

enum (ImageCropType)

裁剪類型。

aspectRatio

number

在裁剪類型為 RECTANGLE_CUSTOM 時採用的顯示比例。

以下說明如何套用 16:9 長寬比:

cropStyle {
 "type": "RECTANGLE_CUSTOM",
 "aspectRatio": 16/9
}

ImageCropType

此屬性代表套用至圖片的裁剪樣式。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
IMAGE_CROP_TYPE_UNSPECIFIED 請勿使用。未指定。
SQUARE 預設值。套用正方形裁剪。
CIRCLE 套用圓形裁剪。
RECTANGLE_CUSTOM 套用自訂顯示比例的矩形裁剪。使用 aspectRatio 設定自訂顯示比例。
RECTANGLE_4_3 套用顯示比例 4:3 的矩形裁剪。

BorderStyle

資訊卡或小工具邊框的樣式選項,包括邊框類型和顏色。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "type": enum (BorderType),
  "strokeColor": {
    object (Color)
  },
  "cornerRadius": integer
}
欄位
type

enum (BorderType)

邊框類型。

strokeColor

object (Color)

類型為 BORDER_TYPE_STROKE 時要使用的顏色。

cornerRadius

integer

邊框的圓角半徑。

BorderType

代表套用至小工具的邊框類型。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
BORDER_TYPE_UNSPECIFIED 請勿使用。未指定。
NO_BORDER 預設值。無框線。
STROKE 大綱。

GridItemLayout

代表格線項目可用的各種版面配置選項。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
GRID_ITEM_LAYOUT_UNSPECIFIED 請勿使用。未指定。
TEXT_BELOW 標題和副標題會顯示在格線項目圖片下方。
TEXT_ABOVE 標題和副標題會顯示在格線項目圖片上方。

Columns 小工具最多會在資訊卡或對話方塊中顯示 2 欄。您可以在每個欄中新增小工具,小工具會依照指定的順序顯示。如需 Google Chat 應用程式中的範例,請參閱「資料欄」一節。

每個欄的高度是由較高欄決定。舉例來說,如果第一欄的高度大於第二欄,則這兩欄的高度都是第一欄。由於每一欄可能包含不同數量的小工具,因此您無法定義列,也無法對齊各欄之間的小工具。

欄並列顯示。您可以使用 HorizontalSizeStyle 欄位自訂每個資料欄的寬度。如果使用者的螢幕寬度太窄,第二欄會換行至第一個欄以下:

  • 使用網頁時,如果螢幕寬度小於或等於 480 像素,則會納入第二欄。
  • 在 iOS 裝置上,如果螢幕寬度小於或等於 300 pt,則第二欄會納入範圍。
  • 在 Android 裝置上,如果螢幕寬度小於或等於 320 dp,則第二欄會納入範圍。

如要加入超過 2 個資料欄,或是使用資料列,請使用 Grid 小工具。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。Google Workspace 外掛程式的資料欄仍為開發人員預覽版。

JSON 表示法
{
  "columnItems": [
    {
      object (Column)
    }
  ]
}
欄位
columnItems[]

object (Column)

資料欄陣列。資訊卡或對話方塊中最多可加入 2 個資料欄。

資料欄。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。Google Workspace 外掛程式的資料欄仍為開發人員預覽版。

JSON 表示法
{
  "horizontalSizeStyle": enum (HorizontalSizeStyle),
  "horizontalAlignment": enum (HorizontalAlignment),
  "verticalAlignment": enum (VerticalAlignment),
  "widgets": [
    {
      object (Widgets)
    }
  ]
}
欄位
horizontalSizeStyle

enum (HorizontalSizeStyle)

指定資料欄填滿資訊卡寬度的方式。

horizontalAlignment

enum (HorizontalAlignment)

指定小工具是否要對齊資料欄的左側、右側或中央。

verticalAlignment

enum (VerticalAlignment)

指定小工具是否要對齊資料欄的頂端、底部或中央。

widgets[]

object (Widgets)

資料欄中包含的小工具陣列。小工具會依照指定的順序顯示。

HorizontalSizeStyle

指定資料欄填滿資訊卡寬度的方式。每欄的寬度,同時取決於 HorizontalSizeStyle 和資料欄中小工具的寬度。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。Google Workspace 外掛程式的資料欄仍為開發人員預覽版。

列舉
HORIZONTAL_SIZE_STYLE_UNSPECIFIED 請勿使用。未指定。
FILL_AVAILABLE_SPACE 預設值。資料欄會填滿可用空間,上限為資訊卡寬度的 70%。如果這兩欄都設為 FILL_AVAILABLE_SPACE,則每欄都會填入 50% 的空間。
FILL_MINIMUM_SPACE 資料欄會盡可能填滿最少空間,且小於資訊卡寬度的 30%。

HorizontalAlignment

指定小工具是否要對齊資料欄的左側、右側或中央。

適用於 Google Chat 應用程式,且不適用於 Google Workspace 外掛程式。

列舉
HORIZONTAL_ALIGNMENT_UNSPECIFIED 請勿使用。未指定。
START 預設值。將小工具對齊資料欄的起始位置。如果是由左至右的版面配置,請靠左對齊。如果是由右至左的版面配置,請靠右對齊。
CENTER 將小工具對齊欄中央。
END 將小工具對齊欄的結尾位置。如為由左至右的版面配置,請將小工具向右對齊。如果是由右至左的版面配置,請將小工具向左對齊。

VerticalAlignment

指定小工具是否要對齊資料欄的頂端、底部或中央。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。Google Workspace 外掛程式的資料欄仍為開發人員預覽版。

列舉
VERTICAL_ALIGNMENT_UNSPECIFIED 請勿使用。未指定。
CENTER 預設值。將小工具對齊欄中央。
TOP 將小工具對齊欄頂端。
BOTTOM 將小工具對齊欄底部。

小工具

您可以在資料欄中加入支援的小工具。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。Google Workspace 外掛程式的資料欄仍為開發人員預覽版。

JSON 表示法
{

  // Union field data can be only one of the following:
  "textParagraph": {
    object (TextParagraph)
  },
  "image": {
    object (Image)
  },
  "decoratedText": {
    object (DecoratedText)
  },
  "buttonList": {
    object (ButtonList)
  },
  "textInput": {
    object (TextInput)
  },
  "selectionInput": {
    object (SelectionInput)
  },
  "dateTimePicker": {
    object (DateTimePicker)
  }
  // End of list of possible types for union field data.
}
欄位

聯集欄位 data

data 只能採用下列其中一種設定:

textParagraph

object (TextParagraph)

TextParagraph小工具。

image

object (Image)

Image小工具。

decoratedText

object (DecoratedText)

DecoratedText小工具。

buttonList

object (ButtonList)

ButtonList小工具。

textInput

object (TextInput)

TextInput小工具。

selectionInput

object (SelectionInput)

SelectionInput小工具。

dateTimePicker

object (DateTimePicker)

DateTimePicker小工具。

DividerStyle

資訊卡的分隔線樣式。目前僅適用於資訊卡區段之間的分隔線。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

列舉
DIVIDER_STYLE_UNSPECIFIED 請勿使用。未指定。
SOLID_DIVIDER 預設選項。算繪各區段之間的實線分隔線。
NO_DIVIDER 如果設定這項政策,區段之間就不會顯示分隔線。

CardAction

資訊卡動作是與資訊卡相關的動作。舉例來說,月結單資訊卡可能包含刪除月結單、電子郵件月結單或瀏覽器開啟月結單等動作。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

JSON 表示法
{
  "actionLabel": string,
  "onClick": {
    object (OnClick)
  }
}
欄位
actionLabel

string

顯示為動作選單項目的標籤。

onClick

object (OnClick)

此待辦事項的 onClick 動作。

CardFixedFooter

顯示在資訊卡底部的固定式 (固定式) 頁尾。

在未指定 primaryButtonsecondaryButton 的情況下設定 fixedFooter 會導致錯誤。

如果是 Chat 應用程式,您可以在對話方塊中使用固定頁尾,但不得在資訊卡訊息中使用。如需 Google Chat 應用程式的範例,請參閱「卡片頁尾」。

適用於 Google Chat 應用程式和 Google Workspace 外掛程式。

JSON 表示法
{
  "primaryButton": {
    object (Button)
  },
  "secondaryButton": {
    object (Button)
  }
}
欄位
primaryButton

object (Button)

固定頁尾的主要按鈕。按鈕必須是已設定文字和顏色的文字按鈕。

secondaryButton

object (Button)

固定頁尾的次要按鈕。按鈕必須是已設定文字和顏色的文字按鈕。如果已設定 secondaryButton,也必須設定 primaryButton

DisplayStyle

在 Google Workspace 外掛程式中,可決定資訊卡的顯示方式。

適用於 Google Workspace 外掛程式,不適用於 Google Chat 應用程式。

列舉
DISPLAY_STYLE_UNSPECIFIED 請勿使用。未指定。
PEEK 資訊卡的標頭會出現在側欄底部,部分覆蓋堆疊目前的資訊卡。按一下標題可將資訊卡彈出至資訊卡堆疊中。如果資訊卡沒有標頭,則會改用產生的標頭。
REPLACE 預設值。顯示資訊卡時,您可以取代資訊卡堆疊中頂端資訊卡的檢視畫面。