Esta página foi traduzida pela API Cloud Translation.

Lista de botões

O widget ButtonList exibe um conjunto de Buttons. Os botões podem mostrar texto, um ícone ou texto e um ícone.

Cada Button oferece suporte a uma ação OnClick que ocorre quando os usuários clicam no botão. Por exemplo:

Abra um hiperlink com o OpenLink, como um hiperlink para a documentação do desenvolvedor do Google Chat, https://developers.google.com/chat.
executar uma ação que executa uma função personalizada, como chamar uma API.

Para impedir que os usuários cliquem em um botão, defina "disabled": "true".

Para acessibilidade, os botões oferecem suporte a texto alternativo.

Exemplo 1: um botão que abre um link e um botão que executa uma função personalizada

A imagem a seguir mostra um card que consiste em um widget ButtonList de duas Buttons. Um botão abre a documentação para desenvolvedores do Google Chat em uma nova guia. O outro botão executa uma função personalizada chamada goToView() e transmite um parâmetro: viewType="Bird Eye View".

Uma mensagem de card no Google Chat com um widget de parágrafo de texto. — **Figura 1**: uma mensagem no card no Google Chat com um widget `ButtonList` mostrando dois `Button`s.

Este é o JSON do cartão:

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

Exemplo 2: um botão com cor personalizada e um botão desativado

A imagem a seguir mostra um card que consiste em um widget ButtonList de duas Buttons. Um botão usa o campo Color para personalizar a cor do plano de fundo dele. O outro botão é desativado com o campo Disabled, que impede o usuário de clicar no botão e executar a função.

Mensagem de card no Google Chat mostrando um widget da lista de botões. — **Figura 2**: uma mensagem com card no Google Chat que mostra um widget `ButtonList` mostrando dois `Button`s.

Este é o JSON do cartão:

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

Exemplo 3: botões que exibem ícones

A imagem a seguir mostra um card que consiste em um widget ButtonList com dois ícones Button. Um botão usa o campo [knownIcon]((https://developers.google.com/chat/api/guides/message-formats/cards#builtinicons)) para exibir o ícone de e-mail integrado do Google Chat. O outro botão usa o campo iconUrl para exibir um ícone de widget personalizado.

Este é o JSON do cartão:

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

Exemplo 4: botões com um ícone e um texto

A imagem a seguir mostra um card que consiste em um widget ButtonList que solicita que o usuário envie um e-mail. O primeiro botão mostra um ícone de e-mail, e o segundo botão mostra texto. O usuário pode clicar no ícone ou no botão de texto para executar a função sendEmail.

Este é o JSON do cartão:

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` representação e campos JSON

Representação JSON
{ "buttons": [ { object (`Button`) } ] }

Campos

Campos
`buttons[]`	`object ( Button )` Uma matriz de botões.


       buttons[]

object ( Button )

Uma matriz de botões.

`Button` representação e campos JSON

Representação JSON
{ "text": string, "icon": { object (`Icon`) }, "color": { object (`Color`) }, "onClick": { object (`OnClick`) }, "disabled": boolean, "altText": string }

Campos
`text`	`string` O texto exibido no botão.
`icon`	`object ( Icon )` Imagem do ícone. Se `icon` e `text` forem definidos, o ícone aparecerá antes do texto.
`color`	`object ( Color )` Se definido, o botão será preenchido com uma cor sólida do plano de fundo, e a cor da fonte será alterada para manter o contraste com a cor do plano de fundo. Por exemplo, um fundo azul pode resultar em texto branco. Se ela não for definida, o plano de fundo da imagem será branco e a cor da fonte será azul. Para vermelho, verde e azul, o valor de cada campo é um número `float` que pode ser expresso de duas maneiras: como um número entre 0 e 255 dividido por 255 (153/255) ou como um valor entre 0 e 1 (0,6). O valor 0 representa a ausência de uma cor e 1 ou 255/255 representa a presença total dessa cor na escala RGB. Você pode definir alfa, que define um nível de transparência usando esta equação: `pixel color = alpha * (this color) + (1.0 - alpha) * (background color)` Para alfa, um valor de 1 corresponde a uma cor sólida, e um valor de 0 corresponde a uma cor completamente transparente. Por exemplo, a cor a seguir representa um vermelho meio transparente: `"color": { "red": 1, "green": 0, "blue": 0, "alpha": 0.5 }`
`onClick`	`object ( OnClick )` Obrigatório. A ação a ser realizada quando o botão é clicado, como abrir um hiperlink ou executar uma função personalizada.
`disabled`	`boolean` Se `true` , o botão será exibido em um estado inativo e não responderá às ações do usuário.
`altText`	`string` O texto alternativo usado para acessibilidade. Defina um texto descritivo para que os usuários saibam o que o botão faz. Por exemplo, se um botão abrir um hiperlink, você poderá escrever: "Abre uma nova guia do navegador e navega até a documentação do desenvolvedor do Google Chat em https://developers.google.com/chat" .

`Icon`

Um ícone exibido em um widget em um card.

Oferece suporte a ícones integrados e personalizados .

Representação JSON

Representação 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,
  "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.
}

Campos
`altText`	`string` Opcional. Uma descrição do ícone usado para acessibilidade. Se não for especificado, o valor padrão "Botão" será fornecido. Como prática recomendada, defina uma descrição útil para o que o ícone exibe e, se aplicável, o que ele faz. Por exemplo, `A user's account portrait` ou `Opens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/chat` . Se o ícone estiver definido em um `Button`, o `altText` aparecerá como texto auxiliar quando o usuário passar o cursor sobre o botão. No entanto, se o botão também definir `text`, o `altText` do ícone será ignorado.
`imageType`	`enum ( ImageType )` Estilo de corte aplicado à imagem. Em alguns casos, aplicar um corte `CIRCLE` faz com que a imagem seja desenhada em um tamanho maior que o ícone integrado.
Campo de união `icons` . Ícone exibido no widget no card. `icons` pode ser apenas de um dos tipos a seguir:
`knownIcon`	`string` Exiba um dos ícones integrados fornecidos pelo Google Workspace. Por exemplo, para exibir um ícone de avião, especifique `AIRPLANE`. Para um ônibus, especifique `BUS`. Para ver uma lista completa de ícones compatíveis, consulte ícones integrados .
`iconUrl`	`string` Mostrar um ícone personalizado hospedado em um URL HTTPS. Exemplo: `"iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png"` Os tipos de arquivo aceitos incluem `.png` e `.jpg` .

`ImageType`

É a forma usada para cortar a imagem.

Enums
`SQUARE`	Valor padrão. Aplica uma máscara quadrada à imagem. Por exemplo, uma imagem 4x3 se torna 3x3.
`CIRCLE`	Aplica uma máscara circular à imagem. Por exemplo, uma imagem 4 x 3 se torna um círculo com um diâmetro de 3.

`Onclick`

Representa como responder quando os usuários clicam em um elemento interativo em um card, como um botão.

Representação JSON

Representação 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`. }

{

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

Campos
Campo de união `data` . `data` pode ser apenas de um dos tipos a seguir:
`action`	`object ( Action )` Se especificada, uma ação é acionada por este `onClick` .
`openLink`	`object ( OpenLink )` Se especificado, este `onClick` vai acionar uma ação de link aberto.
`openDynamicLinkAction`	`object ( Action )` Um complemento aciona essa ação quando ela precisa abrir um link. Isso é diferente do `openLink` acima, porque ele precisa se comunicar com o servidor para receber o link. Portanto, parte do trabalho de preparação é necessário para que o cliente da Web faça antes que a resposta da ação de link aberto volte.
`card`	`object ( Card )` Um novo cartão é enviado para a pilha de cards após o clique, se especificado. Com os complementos do Google Workspace, mas não os apps do Chat.

`Action`

Uma ação que descreve o comportamento quando o formulário é enviado. Por exemplo, um Apps Script pode ser invocado para processar o formulário. Se a ação for acionada, os valores do formulário serão enviados ao servidor.

Representação JSON
{ "function": string, "parameters": [ { object (`ActionParameter`) } ], "loadIndicator": enum (`LoadIndicator`), "persistValues": boolean, "interaction": enum (`Interaction`) }

Campos
`function`	`string` Uma função personalizada a ser invocada quando o elemento que contém o conteúdo for clicado ou ativado por outros motivos. Para ver exemplos de uso, consulte Criar cards interativos .
`parameters[]`	`object ( ActionParameter )` Lista de parâmetros de ação.
`loadIndicator`	`enum ( LoadIndicator )` Especifica o indicador de carregamento que a ação exibe ao fazer a chamada para a ação.
`persistValues`	`boolean` Indica se os valores do formulário persistem após a ação. O valor padrão é `false` . Se `true` , os valores do formulário permanecem após o acionamento da ação. Para permitir que o usuário faça alterações durante o processamento da ação, defina LoadIndicator como `NONE` . Para mensagens do cartão em apps de chat, você também precisa definir o ResponseType da ação como `UPDATE_MESSAGE` e usar o mesmo `cardId` do cartão que continha a ação. Se `false` , os valores do formulário serão apagados quando a ação for acionada. Para evitar que o usuário faça alterações enquanto a ação é processada, defina LoadIndicator como `SPINNER` .
`interaction`	`enum ( Interaction )` Opcional. Obrigatório ao abrir uma caixa de diálogo . O que fazer em resposta a uma interação com o usuário, como clicar em um botão em uma mensagem de card. Se não for especificado, o app responderá executando uma `action`, como a abertura de um link ou a execução de uma função, normalmente. Ao especificar um `interaction`, o app pode responder de maneiras interativas especiais. Por exemplo, definindo `interaction` como `OPEN_DIALOG` , o app pode abrir uma caixa de diálogo . Quando especificado, um indicador de carregamento não é mostrado. Compatível com apps de chat, mas não com complementos do Google Workspace. Se especificado para um complemento, todo o cartão será retirado, e nada será exibido no cliente.

`ActionParameter`

Lista de parâmetros de string a serem fornecidos quando o método de ação for invocado. Por exemplo, considere estes três botões: adiar agora, adiar 1 dia ou adiar semana que vem. Você pode usar o método de ação = sleep(), transmitindo o tipo de adiamento e o tempo de adiamento na lista de parâmetros de string.

Para saber mais, consulte CommonEventObject .

Representação JSON
{ "key": string, "value": string }

Campos

Campos
`key`	`string` Nome do parâmetro do script de ação.
`value`	`string` O valor do parâmetro.

key

string

Nome do parâmetro do script de ação.


       value

string

O valor do parâmetro.

`LoadIndicator`

Especifica o indicador de carregamento que a ação exibe ao fazer a chamada para a ação.

Enums
`SPINNER`	Exibe um ícone de carregamento indicando que o conteúdo está sendo carregado.
`NONE`	Nada é exibido.

`Interaction`

Opcional. Obrigatório ao abrir uma caixa de diálogo .

O que fazer em resposta a uma interação com o usuário, como clicar em um botão em uma mensagem de card.

Se não for especificado, o app responderá executando uma action, como a abertura de um link ou a execução de uma função, normalmente.

Ao especificar um interaction, o app pode responder de maneiras interativas especiais. Por exemplo, definindo interaction como OPEN_DIALOG , o app pode abrir uma caixa de diálogo .

Quando especificado, um indicador de carregamento não é mostrado.

Compatível com apps de chat, mas não com complementos do Google Workspace. Se especificado para um complemento, todo o cartão será retirado, e nada será exibido no cliente.

Enums

INTERACTION_UNSPECIFIED Valor padrão. O action é executado normalmente.

Enums
`INTERACTION_UNSPECIFIED`	Valor padrão. O `action` é executado normalmente.
`OPEN_DIALOG`	Abre uma caixa de diálogo , uma interface em janelas e baseada em cards que os apps de chat usam para interagir com os usuários. Esse recurso só é compatível com apps de chat em resposta a cliques em botões nas mensagens do card. Não é compatível com os complementos do Google Workspace. Se especificado para um complemento, todo o cartão será retirado, e nada será exibido no cliente.


       OPEN_DIALOG

Abre uma caixa de diálogo , uma interface em janelas e baseada em cards que os apps de chat usam para interagir com os usuários.

Esse recurso só é compatível com apps de chat em resposta a cliques em botões nas mensagens do card.

Não é compatível com os complementos do Google Workspace. Se especificado para um complemento, todo o cartão será retirado, e nada será exibido no cliente.

`OpenLink`

Representa um evento onClick que abre um hiperlink.

Representação JSON
{ "url": string, "openAs": enum (`OpenAs`), "onClose": enum (`OnClose`) }

Campos

Campos
`url`	`string` O URL a ser aberto.
`openAs`	`enum ( OpenAs )` Como abrir um link. Não há suporte para os apps de chat.
`onClose`	`enum ( OnClose )` Indica se o cliente esqueceu de um link depois de abri-lo ou se o observa até a janela fechar. Não há suporte para os apps de chat.

url

string

O URL a ser aberto.


       openAs

enum ( OpenAs )

Como abrir um link. Não há suporte para os apps de chat.


       onClose

enum ( OnClose )

Indica se o cliente esqueceu de um link depois de abri-lo ou se o observa até a janela fechar. Não há suporte para os apps de chat.

Lista de botões

Exemplo 1: um botão que abre um link e um botão que executa uma função personalizada

JSON

Exemplo 2: um botão com cor personalizada e um botão desativado

JSON

Exemplo 3: botões que exibem ícones

JSON

Exemplo 4: botões com um ícone e um texto

JSON

ButtonList representação e campos JSON

Button representação e campos JSON

Icon

ImageType

Onclick

Action

ActionParameter

LoadIndicator

Interaction

OpenLink

`ButtonList` representação e campos JSON

`Button` representação e campos JSON

`Icon`

`ImageType`

`Onclick`

`Action`

`ActionParameter`

`LoadIndicator`

`Interaction`

`OpenLink`