Cards v2

{
  "header": {
    object (CardHeader)
  },
  "sections": [
    {
      object (Section)
    }
  ],
  "sectionDividerStyle": enum (DividerStyle),
  "cardActions": [
    {
      object (CardAction)
    }
  ],
  "name": string,
  "fixedFooter": {
    object (CardFixedFooter)
  },
  "displayStyle": enum (DisplayStyle),
  "peekCardHeader": {
    object (CardHeader)
  }
}

object (CardHeader)

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

object (Section)

包含一組小工具。每個部分都有可選的標頭。各個區段會以線條分隔，如需 Google Chat 應用程式的範例，請參閱「定義資訊卡的部分」。

enum (DividerStyle)

標題、區段和頁尾之間的分隔符號樣式。

object (CardAction)

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

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

舉例來說，以下 JSON 會使用 Settings 和 Send 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"
      }
    }
  }
]

string

資訊卡的名稱。用於資訊卡導覽中的資訊卡 ID。

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

object (CardFixedFooter)

固定在資訊卡底部的頁尾。

如果在設定 fixedFooter 時未指定 primaryButton 或 secondaryButton，就會發生錯誤。對於 Chat 應用程式，您可以在對話方塊中使用固定頁尾，但無法在資訊卡訊息中使用。

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

enum (DisplayStyle)

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

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

object (CardHeader)

顯示內容比對內容時，Peek 資訊卡標題會做為預留位置，讓使用者在首頁資訊卡和內容比對資訊卡之間前後瀏覽。

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

{
  "title": string,
  "subtitle": string,
  "imageType": enum (ImageType),
  "imageUrl": string,
  "imageAltText": string
}

string

必要欄位。資訊卡標題。標頭的高度固定：如果同時指定標題和副標題，每個標題和副標題都會佔用一行。如果只指定標題，系統會將標題放在兩行中。

string

資訊卡標題的副標題。如果指定，會顯示在 title 下方的獨立行中。

enum (ImageType)

用於裁剪圖片的形狀。

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

string

資訊卡標題中圖片的 HTTPS 網址。

string

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

{
  "header": string,
  "widgets": [
    {
      object (Widget)
    }
  ],
  "collapsible": boolean,
  "uncollapsibleWidgetsCount": integer,
  "collapseControl": {
    object (CollapseControl)
  }
}

string

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

object (Widget)

該區段中的所有小工具。至少須包含一個小工具。

boolean

指出這個部分是否可收合。

可摺疊的版面可隱藏部分或所有小工具，但使用者只要按一下「顯示更多」，即可展開該版面，查看隱藏的小工具。使用者可以按一下「顯示較少」，再次隱藏小工具。

如要決定要隱藏哪些小工具，請指定 uncollapsibleWidgetsCount。

integer

即使在摺疊區段時，仍會顯示的不可摺疊小工具數量。

舉例來說，如果某個區段包含五個小工具，而 uncollapsibleWidgetsCount 設為 2，系統一律會顯示前兩個小工具，而最後三個則預設為收合。只有在 collapsible 為 true 時，系統才會考慮 uncollapsibleWidgetsCount。

object (CollapseControl)

選用設定。定義區段的展開和收合按鈕。只有當該部分可摺疊時，這個按鈕才會顯示。如果未設定這個欄位，系統會使用預設按鈕。 適用於 Google Chat 應用程式，但不適用於 Google Workspace 外掛程式。

{
  "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)
  },
  "carousel": {
    object (Carousel)
  },
  "chipList": {
    object (ChipList)
  }
  // End of list of possible types for union field data.
}

enum (HorizontalAlignment)

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

object (TextParagraph)

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

例如，下列 JSON 會建立加粗的文字：

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

object (Image)

顯示圖片。

舉例來說，下列 JSON 會建立附帶替代文字的圖片：

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

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"
  }
}

object (ButtonList)

按鈕清單。

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

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

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"
      }
    ]
  }
}

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
    }
  ]
}

object (DateTimePicker)

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

例如，下列 JSON 會建立日期/時間挑選器，用於安排預約：

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

object (Divider)

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

例如，下列 JSON 會建立分隔符：

"divider": {
}

object (Grid)

顯示包含一組項目的格狀畫面。

格線支援任意數量的欄和項目。列數取決於項目數量上限除以資料欄數。格線包含 10 個項目和 2 個欄，因此有 5 列。格線包含 11 個項目和 2 個欄，因此有 6 列。

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

舉例來說，下列 JSON 會建立 2 欄格式，其中包含 1 個項目：

"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"
    }
  }
}

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"
          }
        }
      ]
    }
  ]
}

object (Carousel)

輪轉介面包含一組巢狀小工具。例如，以下是輪轉介面 JSON 表示法，其中包含兩個文字段落。

{
  "widgets": [
    {
      "textParagraph": {
        "text": "First text paragraph in the carousel."
      }
    },
    {
      "textParagraph": {
        "text": "Second text paragraph in the carousel."
      }
    }
  ]
}

object (ChipList)

方塊清單。

舉例來說，下列 JSON 會建立兩個方塊。第一個是文字方塊，第二個是可開啟連結的圖示方塊：

"chipList": {
  "chips": [
    {
      "text": "Edit",
      "disabled": true,
    },
    {
      "icon": {
        "knownIcon": "INVITE",
        "altText": "check calendar"
      },
      "onClick": {
        "openLink": {
          "url": "https://example.com/calendar"
        }
      }
    }
  ]
}

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

{
  "text": string,
  "maxLines": integer
}

string

小工具中顯示的文字。

integer

小工具中顯示的文字行數上限。如果文字超過指定的最大行數，系統會隱藏多餘的內容，並在「顯示更多」按鈕後方顯示。如果文字等於或短於指定的最大行數，系統就不會顯示「顯示更多」按鈕。

預設值為 0，在這種情況下，系統會顯示所有內容。系統會忽略負值。 適用於 Google Chat 應用程式，但不適用於 Google Workspace 外掛程式。

{
  "imageUrl": string,
  "onClick": {
    object (OnClick)
  },
  "altText": string
}

string

圖片的 HTTPS 網址。

例如：

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

object (OnClick)

當使用者點選圖片時，點擊會觸發這個動作。

string

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

{

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

object (Action)

如果指定了這個 onClick，系統就會觸發動作。

object (OpenLink)

如果指定，這個 onClick 會觸發開啟連結動作。

object (Action)

當動作需要開啟連結時，外掛程式會觸發這項動作。這與上述 openLink 不同，因為這需要與伺服器通訊才能取得連結。因此，在開啟連結動作回應傳回之前，網頁用戶端必須先完成一些準備工作。

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

object (Card)

如果指定了點擊動作，系統會在點擊後將新卡片推送至卡片堆疊。

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

object (OverflowMenu)

如果指定此 onClick，系統會開啟溢位選單。 適用於 Google Chat 應用程式，但不適用於 Google Workspace 外掛程式。

{
  "function": string,
  "parameters": [
    {
      object (ActionParameter)
    }
  ],
  "loadIndicator": enum (LoadIndicator),
  "persistValues": boolean,
  "interaction": enum (Interaction),
  "requiredWidgets": [
    string
  ],
  "allWidgetsAreRequired": boolean
}

string

當包含元素遭到點選或以其他方式啟用時，要叫用的自訂函式。

如需使用範例，請參閱「讀取表單資料」。

object (ActionParameter)

動作參數清單。

enum (LoadIndicator)

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

boolean

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

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

如果為 false，則在觸發動作時會清除表單值。如要避免使用者在處理動作時進行變更，請將 LoadIndicator 設為 SPINNER。

enum (Interaction)

選用設定。開啟對話方塊時必須使用。

回應與使用者互動 (例如使用者按下資訊卡訊息中的按鈕) 時的動作。

如果未指定，應用程式會執行 action 來回應，例如開啟連結或執行函式。

指定 interaction 後，應用程式就能以特殊互動方式回應。舉例來說，將 interaction 設為 OPEN_DIALOG，應用程式就能開啟對話方塊。指定後，系統就不會顯示載入指標。如果指定為外掛程式，則會移除整個資訊卡，並在用戶端中顯示空白畫面。

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

string

如果在叫用此動作時，此處所列的資訊方塊沒有值，表單提交作業就會中止。

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

boolean

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

{
  "key": string,
  "value": string
}

string

動作指令碼的參數名稱。

string

參數的值。

{
  "url": string,
  "openAs": enum (OpenAs),
  "onClose": enum (OnClose)
}

string

要開啟的網址。

enum (OpenAs)

如何開啟連結。

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

enum (OnClose)

用戶端是否會在開啟連結後忘記連結，或是觀察連結，直到視窗關閉為止。

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

{
  "items": [
    {
      object (OverflowMenuItem)
    }
  ]
}

object (OverflowMenuItem)

必要欄位。選單選項清單。

{
  "startIcon": {
    object (Icon)
  },
  "text": string,
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean
}

object (Icon)

文字前方顯示的圖示。

string

必要欄位。向使用者說明或識別商品的文字。

object (OnClick)

必要欄位。選取選單選項時所觸發的動作。這個 OnClick 無法包含 OverflowMenu，任何指定的 OverflowMenu 都會遭到捨棄，且選單項目會停用。

boolean

是否停用選單選項。預設值為 false。

{
  "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.
}

string

選用設定。用於無障礙功能的圖示說明。如未指定，則會提供預設值 Button。最佳做法是，您應設定有用的說明，說明圖示顯示的內容，以及適用情況下圖示的功能。例如 A user's account portrait 或 Opens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/workspace/chat。

如果圖示是在 Button 中設定，當使用者將滑鼠游標懸停在按鈕上時，altText 會顯示為實用提示文字。不過，如果按鈕也設定了 text，系統會忽略圖示的 altText。

enum (ImageType)

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

string

顯示 Google Workspace 提供的內建圖示。

例如，如要顯示飛機圖示，請指定 AIRPLANE。如為巴士，請指定 BUS。

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

string

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

例如：

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

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

object (MaterialIcon)

顯示一個 Google Material Icons。

例如，如要顯示核取方塊圖示，請使用

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

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

{
  "name": string,
  "fill": boolean,
  "weight": integer,
  "grade": integer
}

string

Google Material 圖示中定義的圖示名稱，例如 check_box。任何無效的名稱都會遭到捨棄，並替換成空字串，導致圖示無法顯示。

boolean

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

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

integer

圖示的粗細。請選擇 {100, 200, 300, 400, 500, 600, 700}。如未指定，則預設值為 400。如指定任何其他值，則會使用預設值。

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

integer

粗細和等級會影響符號的粗細。等級調整比權重調整更精細，對符號大小的影響也較小。選擇 {-25, 0, 200}。如未指定，預設值為 0。如指定任何其他值，則會使用預設值。

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

{
  "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.
}

object (Icon)

已淘汰，改用 startIcon。

object (Icon)

文字前方顯示的圖示。

string

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

string

必要欄位。主要文字。

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

boolean

文字換行設定。如果是 true，文字會斷行並顯示在多行上。否則文字會截斷。

僅適用於 text，不適用於 topLabel 和 bottomLabel。

string

顯示在 text 下方的文字。一律會包裝。

object (OnClick)

使用者點選 topLabel 或 bottomLabel 時，系統會觸發這項動作。

object (Button)

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

object (SwitchControl)

使用者可點選切換鈕小工具來變更狀態並觸發動作。

object (Icon)

文字後方顯示的圖示。

支援內建和自訂圖示。

{
  "text": string,
  "icon": {
    object (Icon)
  },
  "color": {
    object (Color)
  },
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean,
  "altText": string,
  "type": enum (Type)
}

string

按鈕內顯示的文字。

object (Icon)

按鈕中顯示的圖示。如果同時設定 icon 和 text，圖示會顯示在文字前方。

object (Color)

選用設定。按鈕的顏色。如果已設定，按鈕 type 會設為 FILLED，而 text 和 icon 欄位的顏色會設為對比色，以利閱讀。舉例來說，如果按鈕顏色設為藍色，按鈕中的任何文字或圖示都會設為白色。

如要設定按鈕顏色，請為 red、green 和 blue 欄位指定值。值必須���介於 0 和 1 之間的浮點數，並以 RGB 顏色值為依據，其中 0 (0/255) 代表沒有顏色，而 1 (255/255) 代表顏色的最大濃度。

例如，以下程式碼會將顏色設為最高強度的紅色：

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
}

alpha 欄位無法用於按鈕顏色。如果指定此欄位，系統會忽略這個欄位。

object (OnClick)

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

boolean

如果是 true，按鈕會顯示為非活動狀態，且不會回應使用者動作。

string

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

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

enum (Type)

選用設定。按鈕類型。如果未設定，按鈕類型預設為 OUTLINED。如果已設定 color 欄位，系統會強制將按鈕類型設為 FILLED，並忽略為此欄位設定的任何值。

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

{
  "red": number,
  "green": number,
  "blue": number,
  "alpha": number
}

number

顏色中的紅色量，值介於 [0, 1] 之間。

number

顏色中的綠色量，值介於 [0, 1] 之間。

number

顏色中的藍色量，值介於 [0, 1] 之間。

number

應套用至像素的此顏色比例。也就是說，最終像素顏色由以下等式定義：

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

也就是說，值為 1.0 對應於純色，而值為 0.0 則對應於完全透明的顏色。這會使用包裝函式���息，而非簡單的浮點向量，以便區分預設值和未設定的值。如果省略，這個色彩物件會以實色顯示 (就好像 Alpha 值明確指定為 1.0 的值一樣)。

{
  "name": string,
  "value": string,
  "selected": boolean,
  "onChangeAction": {
    object (Action)
  },
  "controlType": enum (ControlType)
}

string

在表單輸入事件中，系統用來識別切換鈕小工具的名稱。

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

string

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

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

boolean

當 true 為 1 時，表示已選取切換鈕。

object (Action)

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

enum (ControlType)

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

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

{
  "buttons": [
    {
      object (Button)
    }
  ]
}

object (Button)

按鈕陣列。

{
  "name": string,
  "label": string,
  "hintText": string,
  "value": string,
  "type": enum (Type),
  "onChangeAction": {
    object (Action)
  },
  "initialSuggestions": {
    object (Suggestions)
  },
  "autoCompleteAction": {
    object (Action)
  },
  "validation": {
    object (Validation)
  },
  "placeholderText": string
}

string

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

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

string

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

指定可協助使用者輸入應用程式所需資訊的文字。舉例來說，如果您詢問某人的姓名，但需要對方的姓氏，請輸入 surname 而非 name。

如果未指定 hintText，則為必要欄位。否則為選用項目。

string

文字輸入欄位下方顯示的文字，可協助使用者輸入特定值。這段文字會一直顯示。

如果未指定 label，則為必要欄位。否則為選用項目。

string

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

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

enum (Type)

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

object (Action)

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

例如執行自訂函式或在 Google Chat 中開啟對話方塊。

object (Suggestions)

使用者可輸入的建議值。使用者點選文字輸入欄位時，就會顯示這些值。使用者輸入內容時，系統會根據使用者輸入的內容，動態篩選建議值。

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

建議值可引導使用者輸入應用程式可解讀的值。在參照 JavaScript 時，部分使用者可能會輸入 javascript，其他使用者則會輸入 java script。建議使用 JavaScript 可讓使用者與應用程式互動的方式標準化。

指定後，TextInput.type 一律為 SINGLE_LINE，即使設為 MULTIPLE_LINE 也是如此。

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

object (Action)

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

如果未指定，建議會由 initialSuggestions 設定，並由用戶端處理。

如果指定，應用程式會採取此處指定的動作，例如執行自訂函式。

Google Workspace 外掛程式可使用，但 Google Chat 應用程式無法使用。

object (Validation)

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

string

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

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

Action

Navigation

推送、彈出或更新卡片。

開發人員預覽版：Google Chat 中的外掛程式。

Card

將一張牌推到牌堆中。

開發人員預覽版：針對 Google Chat 中的對話方塊，開啟或更新對話方塊。

Card

使用新卡片更新頂端資訊卡，並保留已填寫的表單欄位值。如果是不同欄位，則會捨棄該值。

開發人員預覽版：針對 Google Chat 中的對話方塊，開啟或更新對話方塊。

{
  "items": [
    {
      object (SuggestionItem)
    }
  ]
}

object (SuggestionItem)

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

{

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

string

文字輸入欄位建議輸入內容的值。這與使用者自行輸入的內容相同。

{
  "characterLimit": integer,
  "inputType": enum (InputType)
}

integer

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

enum (InputType)

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

{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,
  "validation": {
    object (Validation)
  },

  // 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.
}

string

必要欄位。用於識別表單輸入事件中選取輸入內容的名稱。

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

string

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

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

enum (SelectionType)

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

object (SelectionItem)

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

object (Action)

如果指定，系統會在選取項目變更時提交表單。如未指定，則必須指定用於提交表單的按鈕。

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

integer

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

integer

對於多重選取選單，使用者輸入文字字元數量，系統會根據這個數量傳回建議的選取項目。

如果未設定，多重選取選單會使用下列預設值：

• 如果選單使用 SelectionInput 項目的靜態陣列，預設為 0 個字元，並立即從陣列填入項目。
• 如果選單使用動態資料來源 (multi_select_data_source)，預設會在查詢資料來源以傳回建議項目之前，先顯示 3 個字元。

object (Validation)

針對下拉式選單，此選項輸入欄位的驗證機制。

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

object (Action)

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

object (PlatformDataSource)

Google Workspace 的資料來源。

{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}

string

向使用者說明或識別商品的文字。

string

與此項目相關聯的值。用戶端應將此值做為表單輸入值。

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

boolean

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

string

對於多重選取選單，請提供項目 text 欄位旁顯示的圖示網址。支援 PNG 和 JPEG 檔案。必須是 HTTPS 網址。例如：https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png。

string

對於多重選取選單，這是顯示在項目 text 欄位下方的文字說明或標籤。

{

  // 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.
}

enum (CommonDataSource)

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

object (HostAppDataSourceMarkup)

專屬於 Google Workspace 主機應用程式 (例如 Google Chat 中的聊天室) 的資料來源。

這個欄位支援 Google API 用戶端程式庫，但無法在 Cloud 用戶端程式庫中使用。詳情請參閱「安裝用戶端程式庫」。

{

  // 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.
}

object (ChatClientDataSourceMarkup)

Google Chat 的資料來源。

{

  // Union field source can be only one of the following:
  "spaceDataSource": {
    object (SpaceDataSource)
  }
  // End of list of possible types for union field source.
}

object (SpaceDataSource)

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

{
  "defaultToCurrentSpace": boolean
}

boolean

如果設為 true，多重選取選單會預設選取目前的 Google Chat 聊天室做為項目。

{
  "name": string,
  "label": string,
  "type": enum (DateTimePickerType),
  "valueMsEpoch": string,
  "timezoneOffsetDate": integer,
  "onChangeAction": {
    object (Action)
  },
  "validation": {
    object (Validation)
  }
}

string

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

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

string

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

enum (DateTimePickerType)

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

string (int64 format)

小工具中顯示的預設值，以自 Unix Epoch 紀元時間起算的毫秒為單位。

根據選擇器類型 (DateTimePickerType) 指定值：

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

integer

代表時區與世界標準時間時差的數字，以分鐘為單位。如果已設定，valueMsEpoch 會顯示在指定時區。如果未設定，則值會預設為使用者的時區設定。

object (Action)

當使用者在 DateTimePicker 介面中按一下「儲存」或「清除」時觸發。

object (Validation)

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

{
  "title": string,
  "items": [
    {
      object (GridItem)
    }
  ],
  "borderStyle": {
    object (BorderStyle)
  },
  "columnCount": integer,
  "onClick": {
    object (OnClick)
  }
}

string

顯示在格狀標題中的文字。

object (GridItem)

要顯示在格狀中項目。

object (BorderStyle)

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

integer

網格中要顯示的欄數。如果未指定這個欄位，系統會使用預設值，而這個預設值會因顯示格線的位置 (對話方塊或隨附應用程式) 而異。

object (OnClick)

每個個別的格線項目都會重複使用這個回呼，但在回呼的參數中加入項目清單中的項目 ID 和索引。

{
  "id": string,
  "image": {
    object (ImageComponent)
  },
  "title": string,
  "subtitle": string,
  "layout": enum (GridItemLayout)
}

string

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

object (ImageComponent)

格狀項目中顯示的圖片。

string

格線項目的標題。

string

格線項目的副標題。

enum (GridItemLayout)

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

{
  "imageUri": string,
  "altText": string,
  "cropStyle": {
    object (ImageCropStyle)
  },
  "borderStyle": {
    object (BorderStyle)
  }
}

string

圖片網址。

string

圖片的無障礙標籤。

object (ImageCropStyle)

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

object (BorderStyle)

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

{
  "type": enum (ImageCropType),
  "aspectRatio": number
}

enum (ImageCropType)

裁剪類型。

number

如果裁剪類型為 RECTANGLE_CUSTOM，則使用的顯示比例。

舉例來說，���下是如何套用 16:9 的顯示比例：

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

{
  "type": enum (BorderType),
  "strokeColor": {
    object (Color)
  },
  "cornerRadius": integer
}

enum (BorderType)

框線類型。

object (Color)

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

如要設定筆劃顏色，請為 red、green 和 blue 欄位指定值。值必須是介於 0 和 1 之間的浮點數，並以 RGB 顏色值為依據，其中 0 (0/255) 代表沒有顏色，而 1 (255/255) 代表顏色的最大濃度。

例如，以下程式碼會將顏色設為最高強度的紅色：

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
}

alpha 欄位無法用於描邊顏色。如果指定此欄位，系統會忽略這個欄位。

integer

邊框的圓角半徑。

{
  "columnItems": [
    {
      object (Column)
    }
  ]
}

object (Column)

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

{
  "horizontalSizeStyle": enum (HorizontalSizeStyle),
  "horizontalAlignment": enum (HorizontalAlignment),
  "verticalAlignment": enum (VerticalAlignment),
  "widgets": [
    {
      object (Widgets)
    }
  ]
}

enum (HorizontalSizeStyle)

指定資料欄填滿卡片寬度的做法。

enum (HorizontalAlignment)

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

enum (VerticalAlignment)

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

object (Widgets)

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

{

  // 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)
  },
  "chipList": {
    object (ChipList)
  }
  // End of list of possible types for union field data.
}

object (TextParagraph)

TextParagraph 小工具。

object (Image)

Image 小工具。

object (DecoratedText)

DecoratedText 小工具。

object (ButtonList)

ButtonList 小工具。

object (TextInput)

TextInput 小工具。

object (SelectionInput)

SelectionInput 小工具。

object (DateTimePicker)

DateTimePicker 小工具。

object (ChipList)

ChipList widget。 適用於 Google Chat 應用程式，但不適用於 Google Workspace 外掛程式。

{
  "layout": enum (Layout),
  "chips": [
    {
      object (Chip)
    }
  ]
}

enum (Layout)

指定的方塊清單版面配置。

object (Chip)

陣列的方塊。

{
  "icon": {
    object (Icon)
  },
  "label": string,
  "onClick": {
    object (OnClick)
  },
  "enabled": boolean,
  "disabled": boolean,
  "altText": string
}

object (Icon)

圖示圖片。如果同時設定 icon 和 text，圖示會顯示在文字前方。

string

方塊內顯示的文字。

object (OnClick)

選用設定。使用者點選方塊時要執行的動作，例如開啟超連結或執行自訂函式。

boolean

方塊是否處於有效狀態，並回應使用者動作。預設值為 true。已淘汰，請改用 disabled。

boolean

方塊是否處於停用狀態，並忽略使用者動作。預設值為 false。

string

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

設定說明性文字，讓使用者瞭解晶片的功能。舉例來說，如果方塊會開啟超連結，請寫下「開啟新的瀏覽器分頁，並前往 Google Chat 開發人員說明文件 (網址為 https://developers.google.com/workspace/chat")」

{
  "carouselCards": [
    {
      object (CarouselCard)
    }
  ]
}

object (CarouselCard)

輪轉介面中包含的資訊卡清單。

{
  "widgets": [
    {
      object (NestedWidget)
    }
  ],
  "footerWidgets": [
    {
      object (NestedWidget)
    }
  ]
}

object (NestedWidget)

輪轉介面資訊卡中顯示的小工具清單。系統會依指定順序顯示小工具。

object (NestedWidget)

輪轉介面資訊卡底部顯示的小工具清單。系統會依指定的順序顯示小工具。

{

  // Union field data can be only one of the following:
  "textParagraph": {
    object (TextParagraph)
  },
  "buttonList": {
    object (ButtonList)
  },
  "image": {
    object (Image)
  }
  // End of list of possible types for union field data.
}

object (TextParagraph)

文字段落小工具。

object (ButtonList)

按鈕清單小工具。

object (Image)

圖片小工具。

{
  "horizontalAlignment": enum (HorizontalAlignment),
  "expandButton": {
    object (Button)
  },
  "collapseButton": {
    object (Button)
  }
}

enum (HorizontalAlignment)

展開和收合按鈕的水平對齊方式。

object (Button)

選用設定。定義可自訂的按鈕，用於展開該部分。必須同時設定 expandButton 和 collapseButton 欄位。只有一個欄位組合不會生效。如果未設定這個欄位，系統會使用預設按鈕。

object (Button)

選用設定。定義可自訂的按鈕，用於收合該部分。必須同時設定 expandButton 和 collapseButton 欄位。只有一個欄位組合不會生效。如果未設定這個欄位，系統會使用預設按鈕。

{
  "actionLabel": string,
  "onClick": {
    object (OnClick)
  }
}

string

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

object (OnClick)

這個待辦事項的 onClick 動作。

{
  "primaryButton": {
    object (Button)
  },
  "secondaryButton": {
    object (Button)
  }
}

object (Button)

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

object (Button)

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