버튼 목록

ButtonList 위젯은 Button 집합을 표시합니다. 버튼에는 텍스트, 아이콘 또는 텍스트와 아이콘을 모두 표시할 수 있습니다.

Button은 사용자가 버튼을 클릭할 때 발생하는 OnClick 작업을 지원합니다. 예:

  • OpenLink로 연결되는 하이퍼링크(예: Google Chat 개발자 문서 https://developers.google.com/chat의 하이퍼링크)를 엽니다.
  • 커스텀 함수(예: API 호출)를 실행하는 작업을 실행합니다.

"disabled": "true"를 설정하여 사용자가 버튼을 클릭하지 못하게 할 수 있습니다.

접근성을 위해 버튼은 대체 텍스트를 지원합니다.

다음 이미지는 두 개의 Button로 구성된 ButtonList 위젯으로 구성된 카드를 보여줍니다. 버튼 하나만 누르면 새 탭에서 Google Chat 개발자 문서가 열립니다. 다른 버튼은 goToView()라는 맞춤 함수를 실행하고 매개변수 viewType="Bird Eye View"를 전달합니다.

Google Chat에서 텍스트 단락 위젯을 보여주는 카드 메시지
그림 1: Button 두 개를 표시하는 ButtonList 위젯을 보여주는 Google Chat의 카드 메시지

카드의 JSON은 다음과 같습니다.

JSON

{
  "cardsV2": [
    {
      "cardId": "exampleCard",
      "card": {
        "sections": [
          {
            "widgets": [
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Open a hyperlink",
                      "onClick": {
                        "openLink": {
                          "url": "https://developers.google.com/chat",
                        }
                      }
                    },
                    {
                      "text": "Run a custom function",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "BIRD EYE VIEW",
                            }
                          ],
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

예 2: 맞춤 색상이 있는 버튼 및 비활성화된 버튼

다음 이미지는 두 개의 Button로 구성된 ButtonList 위젯으로 구성된 카드를 보여줍니다. 한 버튼은 Color 필드를 사용하여 버튼의 배경색을 맞춤설정합니다. 다른 버튼은 Disabled 필드로 비활성화되어 사용자가 버튼을 클릭하고 함수를 실행할 수 없습니다.

ButtonList 위젯을 보여주는 Google Chat의 카드 메시지
그림 2: Button 두 개를 표시하는 ButtonList 위젯을 보여주는 Google Chat의 카드 메시지

카드의 JSON은 다음과 같습니다.

JSON

{
 "cards_v2":[
    {
       "card_id":"exampleCard",
       "card":{
          "sections":[
             {
                "widgets":[
                   {
                      "buttonList":{
                         "buttons":[
                            {
                               "text":"View documentation hyperlink",
                               "onClick":{
                                  "openLink":{
                                     "url":"https://developers.google.com/chat"
                                  }
                               },
                               "color":{
                                  "red":0,
                                  "green":0,
                                  "blue":1,
                                  "alpha":0.5
                               }
                            },
                            {
                               "text":"Button disabled",
                               "onClick":{
                                  "openLink":{
                                     "url":"https://developers.google.com/chat"
                                  }
                               },
                               "disabled":true
                            }
                         ]
                      }
                   }
                ]
             }
          ]
       }
    }
 ]
}

예 3: 아이콘을 표시하는 버튼

다음 이미지는 두 개의 아이콘 Button이 있는 ButtonList 위젯으로 구성된 카드를 보여줍니다. 버튼 하나는 [knownIcon]((https://developers.google.com/chat/api/guides/message-formats/cards#builtinicons)) 필드를 사용하여 Google Chat의 기본 제공 이메일 아이콘을 표시합니다. 다른 버튼은 iconUrl 필드를 사용하여 맞춤 위젯 아이콘을 표시합니다.

ButtonList 위젯을 보여주는 Google Chat의 카드 메시지
그림 3: 두 개의 아이콘 Button을 표시하는 ButtonList 위젯을 보여주는 Google Chat의 카드 메시지

카드의 JSON은 다음과 같습니다.

JSON

{
"cards_v2": [
  {
  "card_id": "exampleCard",
  "card": {
    "sections": [
    {
      "widgets": [
      {
        "buttonList": {
          "buttons": [
                          {
              "icon": {"knownIcon": "EMAIL",},
              "onClick": {
                "action": {
                  "function": "sendEmail",
                  "parameters": [
                    {
                      "key": "emailContent",
                      "value": "Email value",
                    }
                  ],
                }
              }
            },
            {
              "icon": {"iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png",},
              "onClick": {
                "action": {
                  "function": "inviteBot",
                  "parameters": [
                    {
                      "key": "botType",
                      "value": "Bot value",
                    }
                  ],
                }
              }
            },
          ]
        }
      }
    ]
    }
    ]
  }
  }
]
}

예 4: 아이콘과 텍스트가 있는 버튼

다음 이미지는 사용자에게 이메일을 전송하라는 메시지를 표시하는 ButtonList 위젯으로 구성된 카드를 보여줍니다. 첫 번째 버튼에는 이메일 아이콘이 표시되고 두 번째 버튼에는 텍스트가 표시됩니다. 사용자는 아이콘 또는 텍스트 버튼을 클릭하여 sendEmail 함수를 실행할 수 있습니다.

ButtonList 위젯을 보여주는 Google Chat의 카드 메시지
그림 1: Button 두 개를 표시하는 ButtonList 위젯을 보여주는 Google Chat의 카드 메시지

카드의 JSON은 다음과 같습니다.

JSON

{
"cards_v2": [
  {
  "card_id": "exampleCard",
  "card": {
    "sections": [
    {
      "widgets": [
      {
        "buttonList": {
          "buttons": [
                          {
              "icon": {"knownIcon": "EMAIL",},
              "onClick": {
                "action": {
                  "function": "sendEmail",
                  "parameters": [
                    {
                      "key": "emailContent",
                      "value": "Email value",
                    }
                  ],
                }
              }
            },
            {
              "text": "Send email",
              "onClick": {
                "action": {
                  "function": "sendEmail",
                  "parameters": [
                    {
                      "key": "sendEmailType",
                      "value": "email value",
                    }
                  ],
                }
              }
            },
          ]
        }
      }
    ]
    }
    ]
  }
  }
]
}

ButtonList JSON 표현 및 필드

JSON 표현
{
  "buttons": [
    {
      object (Button)
    }
  ]
}
필드
buttons[]

object ( Button )

버튼 배열입니다.

Button JSON 표현 및 필드

JSON 표현
{
  "text": string,
  "icon": {
    object (Icon)
  },
  "color": {
    object (Color)
  },
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean,
  "altText": string
}
필드
text

string

버튼 안에 표시되는 텍스트입니다.

icon

object ( Icon )

아이콘 이미지입니다. icon text 가 모두 설정된 경우 아이콘이 텍스트 앞에 표시됩니다.

color

object ( Color )

설정하면 버튼이 단색 배경으로 채워지고 배경 색상과 대비를 유지하기 위해 글꼴 색상이 변경됩니다. 예를 들어 파란색 배경을 설정하면 흰색 텍스트가 될 수 있습니다.

설정되지 않은 경우 이미지 배경이 흰색이고 글꼴 색상은 파란색입니다.

빨간색, 녹색, 파란색의 경우 각 필드의 값은 float 숫자입니다. 두 값은 0과 255를 255 (153/255)로 나눈 값 또는 0과 1 (0.6) 사이의 값 중 하나로 표현할 수 있습니다. 0은 색상이 없음을 나타내며 1 또는 255/255는 RGB 눈금에서 해당 색상의 전체 존재를 나타냅니다.

원하는 경우 알파를 설정합니다. 이 방정식을 사용하여 투명도 수준을 설정합니다.

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

알파의 경우 값 1은 단색에 상응하고 값 0은 완전한 투명한 색상에 해당합니다.

예를 들어 다음 색상은 투명한 투명한 빨간색을 나타냅니다.

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

object ( OnClick )

필수 항목입니다. 버튼을 클릭할 때 실행할 작업입니다(예: 하이퍼링크 열기 또는 맞춤 함수 실행).

disabled

boolean

true 인 경우 버튼은 비활성 상태로 표시되고 사용자 작업에 응답하지 않습니다.

altText

string

접근성에 사용되는 대체 텍스트입니다.

사용자가 버튼의 기능을 알 수 있도록 설명 텍스트를 설정합니다. 예를 들어 버튼이 하이퍼링크를 여는 경우 '새 브라우저 탭을 열고 Google Chat 개발자 문서( https://developers.google.com/chat )로 이동합니다.'와 같이 쓸 수 있습니다.

Icon

카드의 위젯에 표시되는 아이콘

내장 커스텀 아이콘을 지원합니다.

JSON 표현
{
  "altText": string,
  "imageType": enum (ImageType),

  // Union field icons can be only one of the following:
  "knownIcon": string,
  "iconUrl": string
  // End of list of possible types for union field icons.
}
필드
altText

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/chat

아이콘이 Button 에 설정된 경우 사용자가 버튼 위로 마우스를 가져가면 altText 가 도우미 텍스트로 표시됩니다. 그러나 버튼에 text 도 설정되어 있으면 아이콘의 altText 이 무시됩니다.

imageType

enum ( ImageType )

이미지에 적용되는 자르기 스타일입니다. 경우에 따라 CIRCLE 자르기를 적용하면 이미지가 기본 제공 아이콘보다 더 크게 그려집니다.

공용체 필드 icons . 카드의 위젯에 표시되는 아이콘입니다. icons 는 다음 중 하나여야 합니다.
knownIcon

string

Google Workspace에서 제공하는 기본 제공 아이콘 중 하나를 표시합니다.

예를 들어 비행기 아이콘을 표시하려면 AIRPLANE 를 지정합니다. 버스의 경우 BUS 를 지정합니다.

지원되는 아이콘의 전체 목록은 기본 제공 아이콘 을 참고하세요.

iconUrl

string

HTTPS URL에서 호스팅되는 맞춤 아이콘을 표시합니다.

예를 들면 다음과 같습니다.

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

지원되는 파일 형식에는 .png .jpg 이 포함됩니다.

ImageType

이미지를 자르는 데 사용되는 도형입니다.

열거형
SQUARE 기본값 이미지에 정사각형 마스크를 적용합니다. 예를 들어 4x3 이미지는 3x3이 됩니다.
CIRCLE 이미지에 원형 마스크를 적용합니다. 예를 들어 4x3 이미지는 지름이 3인 원형이 됩니다.

Onclick

사용자가 카드에서 버튼과 같은 상호작용 요소를 클릭할 때 응답하는 방법을 나타냅니다.

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 부가기능에서는 지원되지만 Chat 앱에서는 지원되지 않습니다.

Action

양식 제출 시의 동작을 설명하는 작업입니다. 예를 들어 Apps Script를 호출하여 양식을 처리할 수 있습니다. 작업이 트리거되면 양식 값이 서버로 전송됩니다.

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 로 설정하면 앱이 대화상자 를 열 수 있습니다.

지정된 경우 로드 표시기는 표시되지 않습니다.

Chat 앱에서는 지원되지만 Google Workspace 부가기능에서는 지원되지 않습니다. 부가기능에 지정하는 경우 전체 카드가 삭제되고 클라이언트에 아무것도 표시되지 않습니다.

ActionParameter

작업 메서드가 호출될 때 제공할 문자열 매개변수의 목록입니다. 예를 들어 다시 알림 버튼 3개(지금 일시중지, 1일 일시중지, 다음 주 다시 알림)를 사용하는 것이 좋습니다. 문자열 매개변수 목록에 다시 알림 유형 및 다시 알림 시간을 전달하여 작업 메서드 = pause()를 사용할 수 있습니다.

자세한 내용은 CommonEventObject 를 참조하세요.

JSON 표현
{
  "key": string,
  "value": string
}
필드
key

string

액션 스크립트에 해당하는 매개변수의 이름입니다.

value

string

매개변수 값입니다.

LoadIndicator

작업을 호출하는 동안 작업에 표시되는 로드 표시기를 지정합니다.

열거형
SPINNER 콘텐츠가 로드 중임을 나타내는 스피너를 표시합니다.
NONE 아무것도 표시되지 않습니다.

Interaction

선택사항입니다. 대화상자 를 열 때 필요합니다.

사용자와의 상호작용에 따른 조치(예: 사용자가 카드 메시지의 버튼을 클릭하는 경우)

지정하지 않으면 앱은 정상적으로 링크 열기 또는 함수 실행과 같은 action 를 실행하여 응답합니다.

interaction 를 지정하면 앱이 특별한 대화형 방식으로 응답할 수 있습니다. 예를 들어 interaction OPEN_DIALOG 로 설정하면 앱이 대화상자 를 열 수 있습니다.

지정된 경우 로드 표시기는 표시되지 않습니다.

Chat 앱에서는 지원되지만 Google Workspace 부가기능에서는 지원되지 않습니다. 부가기능에 지정하는 경우 전체 카드가 삭제되고 클라이언트에 아무것도 표시되지 않습니다.

열거형
INTERACTION_UNSPECIFIED 기본값 action 는 정상적으로 실행됩니다.
OPEN_DIALOG

채팅 앱이 사용자와 상호작용하는 데 사용하는 창 형식의 카드 기반 인터페이스인 대화상자 를 엽니다.

카드 메시지의 버튼 클릭에 응답하여 채팅 앱에서만 지원됩니다.

Google Workspace 부가기능에서는 지원되지 않습니다. 부가기능에 지정하는 경우 전체 카드가 삭제되고 클라이언트에 아무것도 표시되지 않습니다.