Cards v2

Card

Os cards oferecem suporte a layouts definidos, elementos interativos da IU, como botões, e rich media, como imagens. Use cards para apresentar informações detalhadas, coletar informações de usuários e orientá-los a avançar.

No Google Chat, os cards aparecem em vários lugares:

• Como mensagens independentes.
• Uma mensagem de texto aparece logo abaixo dela.
• Como uma caixa de diálogo .

O exemplo de JSON a seguir cria um "cartão de contato" que é exibido:

• Um cabeçalho com o nome do contato, cargo, foto do avatar.
• Uma seção com dados de contato, incluindo texto formatado.
• Botões em que os usuários podem clicar para compartilhar o contato ou ver mais ou menos informações.

{
  "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": "[e-mail]",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "[phone]",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Representação JSON
{ "header": { object (CardHeader) }, "sections": [ { object (Section) } ], "cardActions": [ { object (CardAction) } ], "name": string, "fixedFooter": { object (CardFixedFooter) }, "displayStyle": enum (DisplayStyle), "peekCardHeader": { object (CardHeader) } }

Campos
header	object ( CardHeader ) O cabeçalho do card. Um cabeçalho geralmente contém uma imagem e um título. Os cabeçalhos sempre aparecem na parte de cima de um card.
sections[]	object ( Section ) Contém um conjunto de widgets. Cada seção tem o próprio cabeçalho opcional. As seções são separadas visualmente por um divisor de linhas.
cardActions[]	object ( CardAction ) Ações do card. As ações são adicionadas ao menu da barra de ferramentas do card. Como os cards de apps de chat não têm barra de ferramentas, cardActions[] não é compatível com os apps de chat. Por exemplo, o JSON a seguir cria um menu de ação do card com as opções "Configurações" e "Enviar 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 Nome do card. Usado como identificador de cartão na navegação de cartões. Como os apps de chat não são compatíveis com esse recurso, eles ignoram esse campo.
fixedFooter	object ( CardFixedFooter ) O rodapé fixo mostrado na parte de baixo deste card. Definir fixedFooter sem especificar um primaryButton ou secondaryButton causa um erro. Os apps de chat são compatíveis com fixedFooter em caixas de diálogo , mas não em mensagens do cartão .
displayStyle	enum ( DisplayStyle ) Nos complementos do Google Workspace, define as propriedades de exibição da peekCardHeader . Não há suporte para os apps de chat.
peekCardHeader	object ( CardHeader ) Ao exibir conteúdo contextual, o cabeçalho do card de visualização funciona como um marcador para que o usuário possa navegar entre os cards da página inicial e os cards contextuais. Não há suporte para os apps de chat.

Cabeçalho do card

Representa um cabeçalho de cartão.

Representação JSON
{ "title": string, "subtitle": string, "imageType": enum (ImageType), "imageUrl": string, "imageAltText": string }

Campos
title	string Obrigatório. O título do cabeçalho do card. O cabeçalho tem uma altura fixa. Se um título e um subtítulo forem especificados, cada um deles ocupará uma linha. Se apenas o título for especificado, as duas linhas serão usadas.
subtitle	string O subtítulo do cabeçalho do cartão. Se especificado, aparece na própria linha abaixo de title .
imageType	enum ( ImageType ) É a forma usada para cortar a imagem.
imageUrl	string O URL HTTPS da imagem no cabeçalho do card.
imageAltText	string O texto alternativo desta imagem que é usado para acessibilidade.

Tipo de imagem

É 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.

Seção

Uma seção contém um conjunto de widgets renderizados verticalmente na ordem em que são especificados.

Representação JSON
{ "header": string, "widgets": [ { object (Widget) } ], "collapsible": boolean, "uncollapsibleWidgetsCount": integer }

Campos
header	string Texto que aparece na parte de cima de uma seção. Suporta texto simples formatado em HTML .
widgets[]	object ( Widget ) Todos os widgets da seção. Precisa ter pelo menos um widget.
collapsible	boolean Indica se esta seção é recolhível. As seções recolhíveis ocultam alguns ou todos os widgets, mas os usuários podem expandir a seção para revelar os widgets ocultos clicando em Mostrar mais . Os usuários podem ocultar os widgets novamente clicando em Mostrar menos . Para determinar quais widgets estão ocultos, especifique uncollapsibleWidgetsCount .
uncollapsibleWidgetsCount	integer O número de widgets não recolhíveis que permanecem visíveis mesmo quando uma seção é recolhida. Por exemplo, quando uma seção contém cinco widgets e o uncollapsibleWidgetsCount está definido como 2 , os dois primeiros widgets são sempre mostrados e os últimos três são recolhidos por padrão. O uncollapsibleWidgetsCount é considerado apenas quando collapsible é true .

Widget

Cada card é composto por widgets.

Um widget é um objeto composto que pode representar textos, imagens, botões e outros tipos de objetos.

Representação 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) }, "divider": { object (Divider) }, "grid": { object (Grid) } // End of list of possible types for union field data. }

Campos
Campo de união data . Um widget só pode ter um dos seguintes itens: Você pode usar vários campos de widget para exibir mais itens. data pode ser apenas de um dos tipos a seguir:
textParagraph	object ( TextParagraph ) Exibe um parágrafo de texto. Suporta texto simples formatado em HTML . Por exemplo, o JSON a seguir cria um texto em negrito: "textParagraph": { "text": " <b>bold text</b>" }
image	object ( Image ) Exibe uma imagem. Por exemplo, o JSON a seguir cria uma imagem com texto alternativo: "image": { "imageUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "altText": "Chat app avatar" }
decoratedText	object ( DecoratedText ) Exibe um item de texto decorado. Por exemplo, o JSON a seguir cria um widget de texto decorado que mostra o endereço de e-mail: "decoratedText": { "icon": { "knownIcon": "EMAIL" }, "topLabel": "Email Address", "text": "[e-mail]", "bottomLabel": "This is a new Email address!", "switchControl": { "name": "has_send_welcome_email_to_sasha", "selected": false, "controlType": "CHECKBOX" } }
buttonList	object ( ButtonList ) Uma lista de botões. Por exemplo, o JSON a seguir cria dois botões. O primeiro é um botão de texto azul, e o segundo é um botão de imagem que abre um link: "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 ) Exibe uma caixa de texto onde os usuários podem digitar. Por exemplo, o JSON a seguir cria uma entrada de texto para um endereço de e-mail: "textInput": { "name": "mailing_address", "label": "Mailing Address" } Outro exemplo: o JSON a seguir cria uma entrada de texto para uma linguagem de programação com sugestões estáticas: "textInput": { "name": "preferred_programing_language", "label": "Preferred Language", "initialSuggestions": { "items": [ { "text": "C++" }, { "text": "Java" }, { "text": "JavaScript" }, { "text": "Python" } ] } }
selectionInput	object ( SelectionInput ) Exibe um controle que permite que os usuários selecionem itens. Os controles de seleção podem ser caixas de seleção, botões de opção, chaves ou menus suspensos. Por exemplo, o JSON a seguir cria um menu suspenso que permite aos usuários escolher um tamanho: "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 ) Exibe um widget de seleção/entrada para data, hora ou data e hora. Não há suporte para os apps de chat. O suporte dos apps de chat estará disponível em breve. Por exemplo, o JSON a seguir cria um seletor de data e hora para agendar um horário: "dateTimePicker": { "name": "appointment_time", "label": "Book your appointment at:", "type": "DATE_AND_TIME", "valueMsEpoch": "796435200000" }
divider	object ( Divider ) Exibe um divisor de linhas horizontal entre os widgets. Por exemplo, o JSON a seguir cria um divisor: "divider": { }
grid	object ( Grid ) Exibe uma grade com um conjunto de itens. Uma grade aceita qualquer número de colunas e itens. O número de linhas é determinado pelos limites superiores dos itens de número divididos pelo número de colunas. Uma grade com 10 itens e 2 colunas tem 5 linhas. Uma grade com 11 itens e 2 colunas tem 6 linhas. Por exemplo, o JSON a seguir cria uma grade de duas colunas com um único item: "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" } } }

Parágrafo

Um parágrafo que oferece suporte à formatação. Consulte Formatação de texto para saber mais detalhes.

Representação JSON
{ "text": string }

Campos
text	string O texto mostrado no widget.

Imagem

Uma imagem especificada por um URL e pode ter uma ação onClick .

Representação JSON
{ "imageUrl": string, "onClick": { object (OnClick) }, "altText": string }

Campos
imageUrl	string O URL https que hospeda a imagem. Exemplo: https://developers.google.com/chat/images/quickstart-app-avatar.png
onClick	object ( OnClick ) Quando um usuário clica na imagem, o clique aciona essa ação.
altText	string O texto alternativo desta imagem, usado para acessibilidade.

Ao clicar

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

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

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.

Ação

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.

Parâmetro de ação

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
key	string Nome do parâmetro do script de ação.
value	string O valor do parâmetro.

Indicador de carga

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.

Interação

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

Link aberto

Representa um evento onClick que abre um hiperlink.

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

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.

Abrir como

Quando um OnClick abre um link, ele pode abri-lo como uma janela em tamanho original (se esse for o frame usado pelo cliente) ou uma sobreposição (como um pop-up). A implementação depende dos recursos da plataforma do cliente, e o valor selecionado poderá ser ignorado se o cliente não for compatível. FULL_SIZE tem suporte de todos os clientes.

Com os complementos do Google Workspace, mas não os apps do Chat.

Enums
FULL_SIZE	O link é aberto como uma janela de tamanho original. Esse é o frame usado pelo cliente.
OVERLAY	O link é aberto como uma sobreposição, como um pop-up.

Fechado

O que o cliente faz quando um link aberto por uma ação OnClick é fechado.

A implementação depende dos recursos da plataforma do cliente. Por exemplo, um navegador da Web pode abrir um link em uma janela pop-up com um gerenciador OnClose .

Se os gerenciadores OnOpen e OnClose estiverem definidos e a plataforma do cliente não for compatível com os dois valores, OnClose terá precedência.

Com os complementos do Google Workspace, mas não os apps do Chat.

Enums
NOTHING	Valor padrão. O cartão não é recarregado; nada acontece.
RELOAD	Recarrega o cartão depois que a janela secundária fecha. Se usada em conjunto com OpenAs.OVERLAY , a janela filha atua como uma caixa de diálogo modal e o cartão pai é bloqueado até que a janela filha feche.

Texto decorado

Um widget que exibe texto com decorações opcionais, como um rótulo acima ou abaixo do texto, um ícone na frente do texto, um widget de seleção ou um botão após o texto.

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

Campos
icon (deprecated)	object ( Icon ) Este item está obsoleto. Obsoleto, substituído por startIcon .
startIcon	object ( Icon ) Ícone exibido na frente do texto.
topLabel	string O texto que aparece acima text . Sempre trunca.
text	string Obrigatório. O texto principal. Suporta formatação simples. Consulte Formatação de texto para ver detalhes sobre a formatação.
wrapText	boolean A configuração de ajuste de texto. Se true , o texto vai ser agrupado e exibido em várias linhas. Caso contrário, o texto será truncado. Isso se aplica apenas a text , não topLabel e bottomLabel .
bottomLabel	string O texto que aparece abaixo text . Sempre trunca.
onClick	object ( OnClick ) Quando os usuários clicam em topLabel ou bottomLabel , essa ação é acionada.
Campo de união control . Um botão, um interruptor, uma caixa de seleção ou uma imagem que aparece no lado direito do texto no widget decoratedText . control pode ser apenas de um dos tipos a seguir:
button	object ( Button ) Um botão que pode ser clicado para acionar uma ação.
switchControl	object ( SwitchControl ) É possível clicar em um widget de interruptor para alterar o estado e acionar uma ação.
endIcon	object ( Icon ) Ícone exibido após o texto. Oferece suporte a ícones integrados e personalizados .

Ícone

Um ícone exibido em um widget em um card.

Oferece suporte a ícones integrados e personalizados .

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

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 .

Botão

Um botão de texto, ícone ou texto + ícone no qual os usuários podem clicar.

Para transformar uma imagem em um botão clicável, especifique um Image (não um ImageComponent ) e defina uma ação onClick .

No momento, compatível com apps do Chat, incluindo caixas de diálogo e cards ) e complementos do Google Workspace.

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

Cor

Representa uma cor no espaço de cores RGBA. Essa representação foi criada para simplificar a conversão de/para representações de cores em vários idiomas em detrimento. Por exemplo, os campos dessa representação podem ser fornecidos de maneira trivial para o construtor de java.awt.Color em Java. Também podem ser triviais para o método +colorWithRed:green:blue:alpha de UIColor no iOS e, com apenas um pouco de trabalho, eles podem ser facilmente formatados em uma string rgba() de CSS em JavaScript.

Esta página de referência não contém informações sobre o espaço de cor absoluto que deve ser usado para interpretar o valor RGB (por exemplo, sRGB, Adobe RGB, DCI-P3, BT.2020 etc.). Por padrão, os aplicativos precisam presumir o espaço de cores sRGB.

Quando a igualdade de cor precisa ser decidida, as implementações, a menos que documentadas de outra forma, tratam duas cores como iguais se todos os valores vermelho, verde, azul e alfa forem diferentes, no máximo, de 1e-5.

Exemplo (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();
 }
 // ...

Exemplo (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;
}
// ...

Exemplo (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('');
};

// ...

Representação JSON
{ "red": number, "green": number, "blue": number, "alpha": number }

Campos
red	number A quantidade de vermelho na cor como um valor no intervalo [0, 1].
green	number A quantidade de verde na cor como um valor no intervalo [0, 1].
blue	number A quantidade de azul na cor como um valor no intervalo [0, 1].
alpha	number A fração desta cor que deve ser aplicada ao pixel. Ou seja, a cor final do pixel é definida pela equação: pixel color = alpha * (this color) + (1.0 - alpha) * (background color) Isto significa que um valor de 1,0 corresponde a uma cor sólida, enquanto um valor de 0,0 corresponde a uma cor completamente transparente. Esse recurso usa uma mensagem de wrapper, em vez de um escalar flutuante simples, para que seja possível distinguir entre um valor padrão e o valor que está sendo desativado. Se omitido, esse objeto de cor é renderizado como uma cor sólida (como se o valor alfa tivesse sido explicitamente atribuído a um valor de 1,0).

SwitchControl

Um interruptor no estilo de alternância ou uma caixa de seleção dentro de um widget decoratedText .

Compatível apenas com o widget decoratedText .

Representação JSON
{ "name": string, "value": string, "selected": boolean, "onChangeAction": { object (Action) }, "controlType": enum (ControlType) }

Campos
name	string O nome pelo qual o widget de alternância é identificado em um evento de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .
value	string O valor inserido por um usuário, retornado como parte de um evento de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .
selected	boolean Quando true , a chave é selecionada.
onChangeAction	object ( Action ) A ação a ser executada quando o estado da chave é alterado, por exemplo, qual função executar.
controlType	enum ( ControlType ) Como a chave aparece na interface do usuário.

Tipo de controle

Como a chave aparece na interface do usuário.

Enums
SWITCH	Um interruptor com estilo de alternância.
CHECKBOX	Obsoleto, substituído por CHECK_BOX .
CHECK_BOX	Uma caixa de seleção.

Lista de botões

Uma lista de botões dispostos horizontalmente.

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

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

TextInput

Um campo em que os usuários podem inserir texto. Oferece suporte a sugestões e ações após mudanças.

Os apps de chat recebem e podem processar o valor do texto inserido durante os eventos de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .

Quando precisar coletar dados abstratos dos usuários, use uma entrada de texto. Para coletar dados definidos dos usuários, use o widget de entrada de seleção.

Representação JSON
{ "name": string, "label": string, "hintText": string, "value": string, "type": enum (Type), "onChangeAction": { object (Action) }, "initialSuggestions": { object (Suggestions) }, "autoCompleteAction": { object (Action) } }

Campos
name	string O nome pelo qual a entrada de texto é identificada em um evento de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .
label	string O texto que aparece acima do campo de entrada da interface do usuário. Especifique o texto que ajuda o usuário a inserir as informações necessárias do app. Por exemplo, se você está perguntando o nome de alguém, mas precisa especificamente do sobrenome da pessoa, escreva "sobrenome" em vez de "nome". Obrigatório se hintText não for especificado. Caso contrário, é opcional.
hintText	string O texto que aparece abaixo do campo de entrada de texto serve para ajudar os usuários solicitando que insiram um determinado valor. Este texto está sempre visível. Obrigatório se label não for especificado. Caso contrário, é opcional.
value	string O valor inserido por um usuário, retornado como parte de um evento de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .
type	enum ( Type ) Como um campo de entrada de texto aparece na interface do usuário. Por exemplo, se o campo tem uma ou várias linhas.
onChangeAction	object ( Action ) O que fazer quando ocorrer uma mudança no campo de entrada de texto. Exemplos de alterações incluem a adição de um usuário ao campo ou a exclusão de texto. Alguns exemplos de ações são executar uma função personalizada ou abrir uma caixa de diálogo no Google Chat.
initialSuggestions	object ( Suggestions ) Valores sugeridos que os usuários podem inserir. Esses valores aparecem quando os usuários clicam no campo de entrada de texto. Conforme os usuários digitam, os valores sugeridos filtram dinamicamente o que foi digitado. Por exemplo, um campo de entrada de texto para a linguagem de programação pode sugerir Java, JavaScript, Python e C++. Quando os usuários começam a digitar "Jav", a lista de filtros de sugestões para mostrar apenas Java e JavaScript. Os valores sugeridos ajudam a orientar os usuários a inserir valores que podem ser compreendidos pelo app. Ao se referir ao JavaScript, alguns usuários podem inserir "javascript" e outros "script script". Sugerir "JavaScript" pode padronizar a interação dos usuários com seu app. Quando especificado, TextInput.type é sempre SINGLE_LINE , mesmo que esteja definido como MULTIPLE_LINE .
autoCompleteAction	object ( Action ) Opcional. Especifique o que fazer quando o campo de entrada de texto sugerir algo aos usuários. Se não for especificada, as sugestões serão definidas por initialSuggestions e processadas pelo cliente. Se especificado, o app realiza a ação especificada aqui, como executar uma função personalizada. Com os complementos do Google Workspace, mas não os apps do Chat. O suporte dos apps de chat estará disponível em breve.

Tipo

Como um campo de entrada de texto aparece na interface do usuário. Por exemplo, um campo de entrada de uma ou várias linhas.

Se initialSuggestions for especificado, type será sempre SINGLE_LINE , mesmo que esteja definido como MULTIPLE_LINE .

Enums
SINGLE_LINE	O campo de entrada de texto tem uma altura fixa de uma linha.
MULTIPLE_LINE	O campo de entrada de texto tem uma altura fixa de várias linhas.

Sugestões

Valores sugeridos que os usuários podem inserir. Esses valores aparecem quando os usuários clicam no campo de entrada de texto. Conforme os usuários digitam, os valores sugeridos filtram dinamicamente o que foi digitado.

Por exemplo, um campo de entrada de texto para a linguagem de programação pode sugerir Java, JavaScript, Python e C++. Quando os usuários começam a digitar "Jav", a lista de filtros de sugestões para mostrar apenas Java e JavaScript.

Os valores sugeridos ajudam a orientar os usuários a inserir valores que podem ser compreendidos pelo app. Ao se referir ao JavaScript, alguns usuários podem inserir "javascript" e outros "script script". Sugerir "JavaScript" pode padronizar a interação dos usuários com seu app.

Quando especificado, TextInput.type é sempre SINGLE_LINE , mesmo que esteja definido como MULTIPLE_LINE .

Representação JSON
{ "items": [ { object (SuggestionItem) } ] }

Campos
items[]	object ( SuggestionItem ) Uma lista de sugestões usadas para recomendações de preenchimento automático nos campos de entrada de texto.

Item de sugestão

Um valor sugerido que os usuários podem inserir em um campo de entrada de texto.

Representação JSON
{ // Union field content can be only one of the following: "text": string // End of list of possible types for union field content. }

Campos
Campo de união content . content pode ser apenas de um dos tipos a seguir:
text	string O valor de uma entrada sugerida para um campo de entrada de texto. Isso equivale ao que os usuários inseririam por conta própria.

Entrada de seleção

Um widget que cria um item de IU com opções para os usuários selecionarem. Por exemplo, um menu suspenso ou uma lista de verificação.

Os apps de chat recebem e podem processar o valor do texto inserido durante os eventos de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .

Quando precisar coletar dados de usuários que correspondam às opções definidas, use uma entrada de seleção. Para coletar dados abstratos dos usuários, use o widget de entrada de texto.

Representação JSON
{ "name": string, "label": string, "type": enum (SelectionType), "items": [ { object (SelectionItem) } ], "onChangeAction": { object (Action) } }

Campos
name	string O nome pelo qual a entrada de seleção é identificada em um evento de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .
label	string O texto que aparece acima do campo de entrada da seleção na interface do usuário. Especifique o texto que ajuda o usuário a inserir as informações necessárias do app. Por exemplo, se os usuários selecionarem a urgência de um tíquete de trabalho em um menu suspenso, o rótulo poderá ser "Urgência" ou "Selecionar urgência".
type	enum ( SelectionType ) A forma como uma opção aparece para os usuários. Diferentes opções oferecem suporte a diferentes tipos de interações. Por exemplo, os usuários podem ativar várias caixas de seleção, mas só podem selecionar um valor em um menu suspenso. Cada entrada de seleção é compatível com um tipo de seleção. Não é possível misturar caixas de seleção e interruptores, por exemplo.
items[]	object ( SelectionItem ) Uma matriz dos itens selecionados. Por exemplo, todas as caixas de seleção marcadas.
onChangeAction	object ( Action ) Se especificado, o formulário é enviado quando a seleção muda. Se não for especificado, você precisará especificar um botão separado que envie o formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .

Tipo de seleção

A forma como uma opção aparece para os usuários. Diferentes opções oferecem suporte a diferentes tipos de interações. Por exemplo, os usuários podem ativar várias caixas de seleção, mas só podem selecionar um valor em um menu suspenso.

Cada entrada de seleção é compatível com um tipo de seleção. Não é possível misturar caixas de seleção e interruptores, por exemplo.

Enums
CHECK_BOX	Um conjunto de caixas de seleção. Os usuários podem marcar várias caixas de seleção por entrada.
RADIO_BUTTON	Um conjunto de botões de opção. Os usuários podem selecionar um botão de opção por entrada de seleção.
SWITCH	Um conjunto de interruptores. Os usuários podem ativar vários interruptores de uma vez por entrada de seleção.
DROPDOWN	Um menu suspenso. Os usuários podem selecionar um item de menu suspenso para cada entrada de seleção.

Item de seleção

Um item selecionável em uma entrada de seleção, como uma caixa de seleção ou um interruptor.

Representação JSON
{ "text": string, "value": string, "selected": boolean }

Campos
text	string O texto exibido aos usuários.
value	string O valor associado a este item. O cliente deve usar essa informação como valor de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .
selected	boolean Quando true , mais de um item é selecionado. Se mais de um item for selecionado para os botões de opção e menus suspensos, o primeiro item selecionado será recebido, e os seguintes serão ignorados.

Seletor de data e hora

Permite que os usuários especifiquem uma data, um horário ou uma data e hora.

Aceita entradas de texto de usuários, mas apresenta um seletor de data e hora interativo que ajuda os usuários a inserir datas e horários formatados corretamente. Se os usuários inserirem uma data ou hora incorretamente, o widget mostrará um erro solicitando que os usuários insiram o formato correto.

Não há suporte para os apps de chat. O suporte dos apps de chat estará disponível em breve.

Representação JSON
{ "name": string, "label": string, "type": enum (DateTimePickerType), "valueMsEpoch": string, "timezoneOffsetDate": integer, "onChangeAction": { object (Action) } }

Campos
name	string O nome pelo qual o seletor de data e hora é identificado em um evento de entrada do formulário. Para ver detalhes sobre como trabalhar com entradas de formulário, consulte Receber dados de formulário .
label	string O texto que solicita que os usuários insiram data, hora ou data e hora. Especifique o texto que ajuda o usuário a inserir as informações necessárias do app. Por exemplo, se os usuários estiverem marcando um horário, um marcador como "Data do agendamento" ou "Data e hora do agendamento" pode funcionar.
type	enum ( DateTimePickerType ) Que tipo de entrada de data e hora é compatível com o seletor de data e hora.
valueMsEpoch	string ( int64 format) O valor exibido como padrão antes da entrada do usuário ou da entrada do usuário anterior, representado em milissegundos ( Époch time ). Para o tipo DATE_AND_TIME , o valor de época completo é usado. Para o tipo DATE_ONLY , apenas a data da hora de época é usada. Para o tipo TIME_ONLY , apenas o horário do período é usado. Por exemplo, para representar 3h, defina o horário da época como 3 * 60 * 60 * 1000 .
timezoneOffsetDate	integer O número que representa a diferença de fuso horário em relação ao UTC, em minutos. Se definido, o valueMsEpoch será exibido no fuso horário especificado. Se não for definido, será usada a configuração de fuso horário do usuário no lado do cliente.
onChangeAction	object ( Action ) Acionado quando o usuário clica em Salvar ou Limpar na interface do seletor de data e hora.

TipoDeDataDataData

Que tipo de entrada de data e hora é compatível com o seletor de data e hora.

Enums
DATE_AND_TIME	O usuário pode selecionar uma data e hora.
DATE_ONLY	O usuário só pode selecionar uma data.
TIME_ONLY	O usuário só pode selecionar um horário.

Divisor

Exibe um divisor entre widgets, uma linha horizontal.

Por exemplo, o JSON a seguir cria um divisor:

"divider": {}

Grade

Exibe uma grade com um conjunto de itens.

Uma grade aceita qualquer número de colunas e itens. O número de linhas é determinado por itens divididos por colunas. Uma grade com 10 itens e 2 colunas tem 5 linhas. Uma grade com 11 itens e 2 colunas tem 6 linhas.

Por exemplo, o JSON a seguir cria uma grade de duas colunas com um único item:

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

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

Campos
title	string O texto exibido no cabeçalho da grade.
items[]	object ( GridItem ) Os itens que serão exibidos na grade.
borderStyle	object ( BorderStyle ) O estilo da borda a ser aplicado a cada item da grade.
columnCount	integer O número de colunas a serem exibidas na grade. Um valor padrão será usado se esse campo não for especificado e for diferente dependendo do local em que a grade for exibida (caixa de diálogo ou complementar).
onClick	object ( OnClick ) Esse callback é reutilizado por cada item da grade, mas com o identificador e o índice do item na lista de itens adicionados aos parâmetros do callback.

Item da grade

Representa um único item no layout de grade.

Representação JSON
{ "id": string, "image": { object (ImageComponent) }, "title": string, "subtitle": string, "layout": enum (GridItemLayout) }

Campos
id	string Um identificador especificado pelo usuário para este item da grade. Esse identificador é retornado nos parâmetros de callback onClick da grade pai.
image	object ( ImageComponent ) A imagem que é exibida no item da grade.
title	string O título do item da grade.
subtitle	string O subtítulo do item da grade.
layout	enum ( GridItemLayout ) O layout a ser usado para o item da grade.

Componente de imagem

Representa uma imagem.

Representação JSON
{ "imageUri": string, "altText": string, "cropStyle": { object (ImageCropStyle) }, "borderStyle": { object (BorderStyle) } }

Campos
imageUri	string O URL da imagem.
altText	string O rótulo de acessibilidade para a imagem.
cropStyle	object ( ImageCropStyle ) Estilo do corte a ser aplicado à imagem.
borderStyle	object ( BorderStyle ) Estilo da borda a ser aplicado à imagem.

Estilo de imagem

Representa o estilo de corte aplicado a uma imagem.

Por exemplo, veja como aplicar uma proporção de 16 por 9:

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

Representação JSON
{ "type": enum (ImageCropType), "aspectRatio": number }

Campos
type	enum ( ImageCropType ) O tipo de corte.
aspectRatio	number A proporção a ser usada se o tipo de corte for RECTANGLE_CUSTOM . Por exemplo, veja como aplicar uma proporção de 16 por 9: cropStyle { "type": "RECTANGLE_CUSTOM", "aspectRatio": 16/9 }

Tipo de cultura da imagem

Representa o estilo de corte aplicado a uma imagem.

Enums
IMAGE_CROP_TYPE_UNSPECIFIED	Nenhum valor especificado. Não use.
SQUARE	Valor padrão. Aplica um corte quadrado.
CIRCLE	Aplica um corte circular.
RECTANGLE_CUSTOM	Aplica um corte retangular com uma proporção personalizada. Defina a proporção personalizada com aspectRatio .
RECTANGLE_4_3	Aplica um corte retangular com proporção de 4:3.

BorderStyle

Representa o estilo de borda completo aplicado aos itens em um widget.

Representação JSON
{ "type": enum (BorderType), "strokeColor": { object (Color) }, "cornerRadius": integer }

Campos
type	enum ( BorderType ) O tipo de borda.
strokeColor	object ( Color ) As cores a serem usadas quando o tipo for BORDER_TYPE_STROKE .
cornerRadius	integer O raio do canto para a borda.

Tipo de borda

Representa os tipos de borda aplicados a widgets.

Enums
BORDER_TYPE_UNSPECIFIED	Nenhum valor especificado.
NO_BORDER	Valor padrão. Sem borda.
STROKE	Contorno.

Layout da grade

Representa as várias opções de layout disponíveis para um item da grade.

Enums
GRID_ITEM_LAYOUT_UNSPECIFIED	Nenhum layout especificado.
TEXT_BELOW	O título e o subtítulo são mostrados abaixo da imagem do item na grade.
TEXT_ABOVE	O título e o subtítulo são mostrados acima da imagem do item na grade.

Ação no cartão

Uma ação do cartão é a ação associada ao cartão. Por exemplo, um cartão de fatura pode incluir ações como excluir fatura e fatura por e-mail ou abrir a fatura em um navegador.

Não há suporte para os apps de chat.

Representação JSON
{ "actionLabel": string, "onClick": { object (OnClick) } }

Campos
actionLabel	string O rótulo que é exibido como item de menu de ações.
onClick	object ( OnClick ) A ação onClick para este item de ação.

Rodapé de cartão fixo

Um rodapé persistente (aderente) que aparece na parte inferior do cartão.

Definir fixedFooter sem especificar um primaryButton ou secondaryButton causa um erro.

Os apps de chat são compatíveis com fixedFooter em caixas de diálogo , mas não em mensagens do cartão .

Representação JSON
{ "primaryButton": { object (Button) }, "secondaryButton": { object (Button) } }

Campos
primaryButton	object ( Button ) O botão principal do rodapé fixo. O botão precisa ser um botão de texto com texto e cor definidos.
secondaryButton	object ( Button ) O botão secundário do rodapé fixo. O botão precisa ser um botão de texto com texto e cor definidos. primaryButton precisará ser definido se secondaryButton for definido.

Estilo de exibição

Nos complementos do Google Workspace, determina como um card é exibido.

Não há suporte para os apps de chat.

Enums
DISPLAY_STYLE_UNSPECIFIED	Não use.
PEEK	O cabeçalho do card aparece na parte de baixo da barra lateral, cobrindo parcialmente o cartão superior atual da pilha. Ao clicar no cabeçalho, o card é exibido na pilha. Se o cartão não tiver um cabeçalho, um cabeçalho gerado será usado.
REPLACE	Valor padrão. O card é mostrado substituindo a visualização do card superior na pilha de cards.