Adicionar elementos de interface interativos a cards

Esta página explica como adicionar widgets e elementos de IU a cartões para que os usuários possam interagir com seu app do Google Chat, como clicar em um botão ou enviar informações.

Os apps do Chat podem usar as seguintes interfaces do Chat para criar cards interativos:

  • Mensagens que contêm um ou mais cards.
  • Páginas iniciais, que é um card que aparece na guia Início do mensagens com o app do Chat.
  • Caixas de diálogo, que são cards que abrem em uma nova janela de mensagens e páginas iniciais.

Quando os usuários interagem com cards, os apps de chat podem usar os dados que que recebem para processar e responder de acordo. Para mais detalhes, consulte Coletar e processar informações dos usuários do Google Chat.

Use o Card Builder para criar e visualizar mensagens e interfaces do usuário para apps do Chat:

Abrir o Card Builder

Pré-requisitos

Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat, conclua um dos seguintes guias de início rápido com base na arquitetura do app que você quer usar:

Adicionar um botão

O Widget ButtonList exibe um conjunto de botões. Os botões podem exibir texto, uma ícone ou texto e ícone. Cada Button oferece suporte a uma OnClick ação que ocorre quando os usuários clicam no botão. Exemplo:

  • Abrir um hiperlink com OpenLink, para oferecer mais informações aos usuários.
  • Execute um action que execute uma função personalizada, como chamar uma API.

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

Adicionar um botão que execute uma função personalizada

Confira abaixo um card que consiste em um widget ButtonList com dois botões. Um botão abre a documentação do desenvolvedor do Google Chat em uma nova guia. O Outro botão executa uma função personalizada chamada goToView() e transmite o parâmetro viewType="BIRD EYE VIEW".

Adicionar um botão com o estilo do Material Design

Confira abaixo um conjunto de botões em diferentes botões do Material Design estilos.

Para aplicar o estilo do Material Design, não inclua o atributo 'cor' .

Adicionar um botão com cor personalizada e um botão desativado

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

O exemplo abaixo mostra um card que consiste em um widget ButtonList com dois botões. Um botão usa o Campo Color para personalizar o plano de fundo do botão cor O outro botão é desativado com o campo Disabled, que impede que o usuário clique no botão e execute a função.

Adicionar um botão com um ícone

O exemplo abaixo mostra um card que consiste em um widget ButtonList com dois ícones. Button. Um botão usa o knownIcon para mostrar o ícone de e-mail integrado do Google Chat. O outro botão usa o iconUrl para exibir uma widget de ícone personalizado.

Adicionar um botão com ícone e texto

O código abaixo mostra um card que consiste em um widget ButtonList que faz solicitações. que o usuário envie um e-mail. O primeiro botão exibe um ícone de e-mail e o segundo botão exibe texto. O usuário pode clicar no ícone ou no texto para executar a função sendEmail.

Personalizar o botão de uma seção recolhível

Personalize o botão de controle que recolhe e expande seções em uma carda. Escolha entre uma variedade de ícones ou imagens para representar visualmente o conteúdo dessa seção, facilitando a compreensão e a interação dos usuários as informações.

Adicionar um menu flutuante

O Overflow menu pode ser usada em cards do Chat para oferecer mais opções e ações. Permite você inclui mais opções sem sobrecarregar a interface do cartão, garantindo uma design limpo e organizado.

Adicionar uma lista de ícones

O ChipList oferece uma maneira versátil e visualmente atraente de exibir informações. Use listas de ícones para representar tags, categorias ou outros dados relevantes, tornando para os usuários navegarem e interagirem com seu conteúdo.

Coletar informações dos usuários

Esta seção explica como você pode adicionar widgets que coletam informações, como texto ou seleções.

Para aprender a processar as informações inseridas pelos usuários, consulte Coletar e processar informações dos usuários do Google Chat.

Coletar texto

O widget TextInput. fornece um campo em que os usuários podem inserir texto. O oferece suporte a sugestões, que ajudam os usuários a inserir dados uniformes e ao mudar ações, que são Actions executados quando ocorre uma mudança no campo de entrada de texto, como um usuário adicionando ou excluindo texto.

Quando precisar coletar dados abstratos ou desconhecidos dos usuários, use esse Widget TextInput. Para coletar dados definidos dos usuários, use o SelectionInput widget.

Confira abaixo um card que consiste em um widget TextInput:

Coletar datas ou horários

O Widget DateTimePicker permite que os usuários insiram uma data, uma hora ou uma data e por vez. Os usuários também podem usar o seletor para selecionar datas e horários. Se os usuários inserirem uma data ou hora inválida, o seletor mostrará um erro que solicita que os usuários insiram as informações corretamente.

Confira abaixo um card que consiste em três tipos diferentes de Widgets DateTimePicker:

Permitir que os usuários selecionem itens

O widget SelectionInput. fornece um conjunto de itens selecionáveis, como caixas de seleção, botões de opção, chaves, ou um menu suspenso. Você pode usar este widget coletar dados definidos e padronizados dos usuários. Coletar dados indefinidos dos usuários, use o widget TextInput.

O widget SelectionInput oferece suporte a sugestões, que ajudam os usuários a inserir valores dados e ações durante mudanças, que são Actions que são executados quando ocorre uma mudança em um campo de entrada de seleção, como um usuário para marcar ou desmarcar um item.

Os apps de chat podem receber e processar o valor de itens selecionados. Para detalhes sobre como trabalhar com entradas de formulário, consulte Processar as informações inseridas pelos usuários.

Esta seção fornece exemplos de cards que usam o widget SelectionInput. Os exemplos usam diferentes tipos de entradas de seção:

Adicionar uma caixa de seleção

O código a seguir exibe um cartão que pede ao usuário para especificar se um o contato é profissional, pessoal ou ambos, com um widget SelectionInput que usa caixas de seleção:

Adicionar um botão de opção

O código a seguir exibe um cartão que pede ao usuário para especificar se um o contato é profissional ou pessoal com um widget SelectionInput que usa botões de opção:

Adicionar uma chave

O código a seguir exibe um cartão que pede ao usuário para especificar se um o contato é profissional, pessoal ou ambos com um widget SelectionInput que usa interruptores:

O código a seguir exibe um cartão que pede ao usuário para especificar se um o contato é profissional ou pessoal com um widget SelectionInput que usa em um menu suspenso:

Adicionar um menu de seleção múltipla

O código a seguir exibe um card que solicita que o usuário selecione os contatos. em um menu de seleção múltipla:

Você pode preencher itens para um menu de seleção múltipla com base nos seguintes dados fontes no Google Workspace:

  • Usuários do Google Workspace: você só pode preencher usuários no na mesma organização do Google Workspace.
  • Espaços do Chat: o usuário insere itens na seleção múltipla. só podem ver e selecionar os espaços aos quais pertencem organização do Google Workspace.

Para usar fontes de dados do Google Workspace, você especifica o platformDataSource . Ao contrário de outros tipos de entrada de seleção, você omite SectionItem , pois esses itens de seleção são dinamicamente originados de Google Workspace.

O código a seguir mostra um menu de seleção múltipla de usuários do Google Workspace. Para preencher usuários, a entrada de seleção define commonDataSource como USER:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

O código abaixo mostra um menu de seleção múltipla do Chat. espaços Para preencher espaços, a entrada de seleção especifica o hostAppDataSource. O menu de seleção múltipla também define defaultToCurrentSpace como true, o que torna o espaço atual o padrão no menu:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Os menus de seleção múltipla também podem preencher itens de dados externos ou de terceiros fonte. Por exemplo, você pode usar menus de seleção múltipla para ajudar um usuário a selecionar de uma lista de leads de vendas de um sistema de gestão de relacionamento com o cliente (CRM).

Para usar uma fonte de dados externa, use o campo externalDataSource para especificar uma função que retorne itens da fonte de dados.

Para reduzir as solicitações a uma fonte de dados externa, inclua itens sugeridos que aparecem no menu de seleção múltipla antes que os usuários digitem; o menu. Por exemplo, você pode preencher contatos pesquisados recentemente para o usuário. Para preencher itens sugeridos usando uma fonte de dados externa, especifique SelectionItem objetos.

O código a seguir mostra um menu de seleção múltipla de itens de um um conjunto externo de contatos para o usuário. O menu exibe um contato por padrão e executa a função getContacts para recuperar e preencher itens da fonte de dados externa:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

Nas fontes de dados externas, também é possível preencher automaticamente os itens iniciados pelos usuários. digitando no menu de seleção múltipla. Por exemplo, se um usuário começar a digitar Atl para um que preenche cidades nos Estados Unidos, sua O app de chat pode sugerir automaticamente Atlanta antes que o usuário terminar de digitar. Você pode preencher automaticamente até 100 itens.

Para preencher automaticamente itens, você cria uma função que consulta os dados externos origem e retorna itens sempre que um usuário digita no menu de seleção múltipla. O precisa fazer o seguinte:

  • Transmita um objeto de evento que represente a interação do usuário com o menu.
  • Identifique se o evento de interação invokedFunction corresponde à função do campo externalDataSource.
  • Quando as funções corresponderem, retornar itens sugeridos de dados externos fonte. Para sugerir itens com base no que o usuário digita, confira o valor do atributo Tecla autocomplete_widget_query. Esse valor representa o que o usuário digita no menu.

O código a seguir preenche automaticamente itens de um recurso de dados externo. Usando o exemplo anterior, o app Chat sugere itens com base quando a função getContacts for acionada:

Apps Script

apps-script/selection-input/on-widget-update.gs
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

Validar dados inseridos em cartões

Esta página explica como validar os dados inseridos no action de um cartão e widgets. Por exemplo, você pode validar se um campo de entrada de texto tem um texto inserido pelo ou que contém um determinado número de caracteres.

Definir os widgets necessários para ações

Como parte do action do cartão, adicionar nomes de widgets que uma ação precisa à lista requiredWidgets.

Se algum widget listado aqui não tiver um valor quando essa ação for invocada, o envio da ação do formulário será cancelado.

Quando "all_widgets_are_required": "true" é definido para uma ação, todos os widgets no card são exigidas por essa ação.

Definir uma ação all_widgets_are_required em seleção múltipla

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "value": "contact-1",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 1",
                "bottomText": "Contact one description",
                "selected": false
              },
              {
                "value": "contact-2",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 2",
                "bottomText": "Contact two description",
                "selected": false
              },
              {
                "value": "contact-3",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 3",
                "bottomText": "Contact three description",
                "selected": false
              },
              {
                "value": "contact-4",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 4",
                "bottomText": "Contact four description",
                "selected": false
              },
              {
                "value": "contact-5",
                "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
                "text": "Contact 5",
                "bottomText": "Contact five description",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}
Definir uma ação all_widgets_are_required em dateTimePicker

JSON

{
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}
Defina uma ação all_widgets_are_required no menu suspenso

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

Definir a validação de um widget de entrada de texto

No textInput campo de validação do widget, ele pode especificar o limite de caracteres e o tipo de entrada para neste widget de entrada de texto.

Definir um limite de caracteres para um widget de entrada de texto

JSON

{
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"character_limit":15},
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        }
      ]
    }
  ]
}
Definir o tipo de entrada para um widget de entrada de texto

JSON

{
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

Resolver problemas

Quando um app ou card retornar um erro, o A interface do chat mostra a mensagem "Algo deu errado". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não exibe nenhuma mensagem de erro, mas o app do Chat ou produz um resultado inesperado; por exemplo, uma mensagem de cartão pode não aparecer.

Embora uma mensagem de erro possa não aparecer na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar você a corrigir os erros quando a geração de registros de erros nos apps do Chat está ativada. Para receber ajuda com a visualização, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.