Widgets

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Um widget é um elemento de IU simples que oferece um ou mais dos seguintes itens:

  • Estrutura para outros widgets, como cards e seções,
  • Informações ao usuário, como texto e imagens
  • Recursos para ação, como botões, campos de entrada de texto ou caixas de seleção

Os conjuntos de widgets adicionados às seções do card definem a IU geral dos complementos. Os widgets têm a mesma aparência e função, tanto na Web quanto em dispositivos móveis. A documentação de referência descreve vários métodos para criar conjuntos de widgets.

Usar o kit de design dos complementos do Google Workspace

Para poupar tempo na criação de widgets de complementos, os designers podem usar o kit de design de IU de complementos do Google Workspace disponível no Figma. Você pode criar uma conta do Figma ou solicitar uma licença ao administrador da sua organização.

Navegue pelos componentes e use modelos integrados para criar e visualizar widgets.

Instalar o kit de design

Tipos de widget

Os widgets complementares geralmente são categorizados em três grupos: widgets estruturais, informativos e de interação do usuário.

Widgets estruturais

Os widgets estruturais oferecem contêineres e organização para os outros widgets usados na IA.

Widgets estruturais

  • Conjunto de botões: um conjunto de um ou mais botões de texto ou imagens, agrupados em uma linha horizontal.
  • Card: um único card de contexto que contém uma ou mais seções de cards. Para definir como os usuários podem alternar entre os cards, configure a navegação de cards.
  • Cabeçalho do card: o cabeçalho de um determinado cartão. Os cabeçalhos de cartão podem ter títulos, legendas e uma imagem. As ações de card e as ações universais aparecem no cabeçalho do cartão se forem usadas pelo complemento.
  • Seção de cards: um grupo coletado de widgets, divididos das outras seções de cards por uma regra horizontal e, opcionalmente, com um cabeçalho de seção. Cada cartão precisa ter pelo menos uma seção de cartão. Não é possível adicionar cartões ou cabeçalhos de card a uma seção de cards.

Além desses widgets estruturais básicos, em um complemento do Google Workspace, é possível usar o serviço de cartão para criar estruturas que se sobrepõem ao cartão atual: rodapés fixos e cards de pico:

Agora é possível adicionar uma linha fixa de botões na parte inferior do cartão. Essa linha não se move nem rola com o restante do conteúdo do cartão. O snippet de código abaixo mostra como definir um rodapé fixo de exemplo e como adicioná-lo a um cartão:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();
      

 

Exemplo de widget de rodapé fixo

Exibir card

Exemplo de cartão de visita

Quando um novo conteúdo contextual é acionado por uma ação do usuário, como abrir uma mensagem do Gmail, é possível exibir o novo conteúdo contextual imediatamente (comportamento padrão) ou exibir uma notificação de cartão de visita na parte inferior da barra lateral. Se um usuário clicar em Voltar para retornar à sua página inicial enquanto um acionador de contexto estiver ativo, um card de exibição vai aparecer para ajudar os usuários a encontrar o conteúdo contextual novamente.

Para exibir um cartão de visita quando um novo conteúdo contextual estiver disponível, em vez de exibir imediatamente o novo conteúdo contextual, adicione .setDisplayStyle(CardService.DisplayStyle.PEEK) à classe CardBuilder. Um cartão de visita só aparecerá se um único objeto de cartão for retornado com seu acionador contextual. Caso contrário, os cartões retornados substituem imediatamente o cartão atual.

Para personalizar o cabeçalho do card de exibição, adicione o método .setPeekCardHeader() com um objeto CardHeader padrão ao criar seu cartão contextual. Por padrão, um cabeçalho de cartão Peek contém apenas o nome do complemento.

O código a seguir, baseado no guia de início rápido do Cats Google Workspace, notifica os usuários sobre o novo conteúdo contextual com um cartão Peek e personaliza o cabeçalho do cartão Peek para exibir o assunto da conversa selecionada do Gmail.

var peekHeader = CardService.newCardHeader()
    .setTitle('Contextual Cat')
    .setImageUrl('https://www.gstatic.com/images/
        icons/material/system/1x/pets_black_48dp.png')
    .setSubtitle(text);

. . .

var card = CardService.newCardBuilder()
    .setDisplayStyle(CardService.DisplayStyle.PEEK)
    .setPeekCardHeader(peekHeader);
      

 

Exemplo de card de visualização personalizado

Widgets informativos

Widgets informativos

Os widgets informativos apresentam informações ao usuário.

  • Imagem: uma imagem indicada por um URL hospedado e de acesso público fornecido por você.
  • DecoratedText: uma string de conteúdo de texto que pode ser pareada com outros elementos, como rótulos de texto na parte superior e inferior, e uma imagem ou ícone. Os widgets DecoratedText também podem incluir um widget Button ou Switch. Os interruptores adicionados podem ser botões ou caixas de seleção simples. O texto de conteúdo do widget DecoratedText pode usar a formatação HTML. Os rótulos superior e inferior precisam usar texto simples.
  • Parágrafo de texto: um parágrafo de texto simples, que pode incluir elementos formatados em HTML.




Widgets de interação do usuário

Widget de ação do card

Os widgets de interação do usuário permitem que o complemento responda às ações realizadas pelos usuários. Você pode configurar esses widgets com respostas de ação para exibir diferentes cards, abrir URLs, mostrar notificações, escrever e-mails de rascunho ou executar outras funções do Apps Script. Consulte o guia Criar cards interativos para ver mais detalhes.

Widgets de interação do usuário

  • Ação do card: um item de menu colocado no menu da barra de cabeçalho dos complementos. O menu da barra de cabeçalho também pode conter itens definidos como ações universais, que aparecem em todos os cards que o complemento define.
  • Seletores de data e hora: widgets que permitem que os usuários selecionem uma data, hora ou ambos. Consulte Seletores de data e hora abaixo para ver mais informações.
  • Botão de imagem: um botão que usa uma imagem em vez de texto. É possível usar um dos vários ícones predefinidos ou uma imagem hospedada publicamente indicada pelo URL dele.
  • Entrada de seleção: um campo de entrada que representa um conjunto de opções. Os widgets de entrada da seleção são exibidos como caixas de seleção, botões de opção ou caixas de seleção suspensas.
  • Switch: um widget de alternância. Só é possível usar interruptores em conjunto com um widget DecoratedText. Por padrão, eles são exibidos como um interruptor, mas é possível fazer com que sejam exibidos como uma caixa de seleção.
  • Botão de texto: um botão com um rótulo de texto. É possível especificar um preenchimento de cor de fundo para botões de texto. O padrão é transparente. Também é possível desativar o botão conforme necessário.
  • Entrada de texto: um campo de entrada de texto. O widget pode ter texto de título, dica e texto com várias linhas. O widget pode acionar ações quando o valor do texto é alterado.
  • Grade: um layout de várias colunas que representa uma coleção de itens. Você pode representar itens com uma imagem, título, subtítulo e uma variedade de opções de personalização, como estilos de borda e corte.

Caixas de seleção DecoratedText

Você pode definir um widget DecoratedText que tenha uma caixa de seleção anexada, em vez de um botão ou interruptor de alternância binário. Assim como nos interruptores, o valor da caixa de seleção é incluído no objeto de eventos de ação transmitido para o Action anexado a este DecoratedText pelo método setOnClickAction(action).

O snippet de código a seguir mostra como definir um widget de caixa de seleção DecoratedText, que pode ser adicionado a um cartão:

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));
      

 

Exemplo de widget de caixa de seleção de texto decorado

Seletores de data e hora

Você pode definir widgets que permitam que os usuários selecionem uma hora, uma data ou ambos. Use setOnChangeAction() para atribuir uma função de gerenciador de widget a ser executada quando o valor do seletor mudar.

O snippet de código a seguir mostra como definir um seletor somente de data, um seletor de horário e um seletor de data e hora, que você pode adicionar a um cartão:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter the date.")
    .setFieldName("date_field")
    // Set default value as May 24 2019. Either a
    // number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateChange"));

var timeOnlyPicker = CardService.newTimePicker()
    .setTitle("Enter the time.")
    .setFieldName("time_field")
    // Set default value as 23:30.
    .setHours(23)
    .setMinutes(30)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleTimeChange"));

var dateTimePicker = CardService.newDateTimePicker()
    .setTitle("Enter the date and time in EDT time.")
    .setFieldName("date_time_field")
    // Set default value as May 24 2019 03:30 AM UTC.
    // Either a number or string is acceptable.
    .setValueInMsSinceEpoch(1558668600000)
    // EDT time is 4 hours behind UTC.
    .setTimeZoneOffsetInMins(-4 * 60)
    .setOnChangeAction(CardService.newAction()
        .setFunctionName("handleDateTimeChange"));
      

 

Exemplo de card de visualização personalizado

Este é um exemplo de função do gerenciador de widgets de seletor de data e hora. Esse gerenciador simplesmente formata e registra uma string que representa a data-hora escolhida pelo usuário em um widget do seletor de data e hora com o ID "myDateTimePickerWidgetID":

function handleDateTimeChange(event) {
  var dateTimeInput =
    event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
  var msSinceEpoch = dateTimeInput.msSinceEpoch;
  var hasDate = dateTimeInput.hasDate;
  var hasTime = dateTimeInput.hadTime;

  // The following requires you to configure the add-on to read user locale
  // and timezone.
  // See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
  var userTimezoneId = event.userTimezone.id;

  // Format and log the date-time selected using the user's timezone.
  var formattedDateTime;
  if (hasDate && hasTime) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
  } else if (hasDate) {
    formattedDateTime = Utilities.formatDate(
      new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
      + ", Time unspecified";
  } else if (hasTime) {
    formattedDateTime = "Date unspecified, "
      + Utilities.formatDate(
          new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
  }

  if (formattedDateTime) {
    console.log(formattedDateTime);
  }
}

 

A tabela abaixo mostra exemplos das IUs de seleção de seletor em dispositivos móveis e computadores. Quando selecionado, o seletor de datas abre uma IU de calendário com base no mês para permitir que o usuário selecione rapidamente uma nova data.

Quando o usuário seleciona o seletor de horário em dispositivos desktop, um menu suspenso é aberto com uma lista de horários separados em incrementos de 30 minutos. O usuário também pode digitar um horário específico. Em dispositivos móveis, a seleção de um seletor de tempo abre o seletor de tempo de "clock" móvel integrado.

Computador Dispositivos móveis
exemplo de seleção de seletor de data exemplo de seleção do seletor de data para dispositivos móveis
exemplo de seleção de seletor de horário exemplo de seleção do seletor de horário para dispositivos móveis

Grade

Mostre itens em um layout de várias colunas com o widget de grade. Cada item pode exibir uma imagem, um título e um subtítulo. Use outras opções de configuração para definir o posicionamento do texto em relação à imagem em um item da grade.

É possível configurar um item da grade com um identificador retornado como um parâmetro para a ação definida na grade.

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));
      

 

Exemplo de widget de grade

Formatação do texto

Alguns widgets baseados em texto oferecem suporte à formatação HTML de texto simples. Ao configurar o conteúdo de texto desses widgets, basta incluir as tags HTML correspondentes. Os seguintes formatos são compatíveis:

Formatar Exemplo Resultado renderizado
Negrito <b>test</b> test
Itálico <i>test</i> test
Sublinhado <u>test</u> test
Tachado <s>test</s> test
Cor da fonte <font color="#ea9999">test</font> test
Hiperlink <a href="http://www.google.com">google</a> google
Tempo <time>2020-02-16 15:00</time> 16/02/2020 15:00
Nova linha test <br> test teste
teste