Esta página foi traduzida pela API Cloud Translation.

Widgets

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 para o usuário, como texto e imagens.
Valores para ações como botões, campos de entrada de texto ou caixas de seleção.

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

Usar o kit de design de complementos do Google Workspace

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

Procure os componentes e use modelos integrados para criar e visualizar widgets.

Instalar o kit de design

Tipos de widget

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

Widgets estruturais

Os widgets estruturais fornecem 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 imagem, agrupados em uma linha horizontal.
Card: um único card de contexto que contém uma ou mais seções. Você define como os usuários podem se mover entre os cards configurando a navegação do card.
Cabeçalho do card: o cabeçalho de um card específico. Os cabeçalhos de cartão podem ter títulos, legendas e uma imagem. As ações do card e as ações universais vão aparecer no cabeçalho do card se forem usadas pelo complemento.
Seção de cartão: um grupo coletado de widgets, dividido das outras seções do cartão por uma regra horizontal e, opcionalmente, com um cabeçalho da 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 cartões a uma seção de cards.

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

Rodapé fixo

Agora é possível adicionar uma linha fixa de botões à parte inferior do seu cartão. Essa linha não se move nem rola com o restante do conteúdo do cartão. O trecho de código a seguir mostra como definir um exemplo de rodapé fixo e 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();

Exibir card

Exemplo de card de análise

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

Para exibir um card de visualização quando um novo conteúdo contextual estiver disponível, em vez de exibir imediatamente o novo conteúdo, adicione .setDisplayStyle(CardService.DisplayStyle.PEEK) à classe CardBuilder. Um card de exibição só aparece se um único objeto de cartão é 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, adicione o método .setPeekCardHeader() com um objeto CardHeader padrão ao criar o card contextual. Por padrão, um cabeçalho de card mostra apenas o nome do complemento.

O código a seguir, baseado no guia de início rápido do Cats Google Workspace Add-on, notifica os usuários sobre novos conteúdos contextuais com um cartão Peek e personaliza o cabeçalho do cartão Peek para exibir o assunto da linha de execução de mensagem 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

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

Imagem: uma imagem indicada por um URL hospedado e acessível publicamente.
DecoratedText: uma string de conteúdo de texto que você pode combinar com outros elementos, como rótulos de texto na parte superior e inferior, e uma imagem ou um ícone. Os widgets DecoratedText também podem incluir um widget Button ou Switch. Os interruptores adicionados podem ser alternados ou caixas de seleção simples. O texto do 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 simples, que pode incluir elementos formatados em HTML.

Widgets de interação do usuário

Widget de ação de cartão

Os widgets de interação do usuário permitem que o complemento responda às ações realizadas pelos usuários. É possível 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 no card: um item de menu colocado no menu da barra de cabeçalho do complemento. O menu da barra de cabeçalho também pode conter itens definidos como ações universais, que aparecem em todos os cards definidos pelo complemento.
Seletores de data/hora: widgets que permitem aos usuários selecionar uma data, hora ou ambos. Consulte Seletores de data e hora abaixo para 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.
Entrada de seleção: um campo de entrada que representa uma coleção de opções. Os widgets de entrada da seleção apresentam caixas de seleção, botões de opção ou caixas de seleção suspensas.
Alternar: um widget de alternância. Só é possível usar interruptores com um widget DecoratedText. Por padrão, eles são exibidos como um botão de alternância, mas é possível exibi-los como uma caixa de seleção.
Botão de texto: um botão com um rótulo de texto. Você pode especificar um preenchimento de cor de segundo plano 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, texto de dica e texto de 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

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

O trecho de código a seguir mostra como definir um widget DecoratedText de caixa de seleção que você pode adicionar 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 selecionar um horário, uma data ou ambos. É possível usar setOnChangeAction() para atribuir uma função de gerenciador de widget a ser executada quando o valor do seletor mudar.

O trecho de código a seguir mostra como definir um seletor somente de data, um seletor de somente tempo e um seletor de data e hora, que podem ser adicionados 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"));

Veja a seguir o exemplo de uma função de gerenciador de widgets de seleção de data e hora. Esse gerenciador simplesmente formata e registra uma string que representa a data e hora escolhidas pelo usuário em um widget de seleção 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 do seletor em computadores e dispositivos móveis. Quando selecionado, o seletor de data abre uma IU da agenda baseada em mês para permitir que o usuário selecione rapidamente uma nova data.

Quando o usuário seleciona o seletor de tempo em computadores, um menu suspenso é aberto com uma lista de vezes 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 horário abre o seletor de tempo "relógio" integrado.

Computador	Dispositivo móvel

Grade

Mostre itens em um layout de várias colunas com o widget de grade. Cada item pode exibir uma imagem, título e 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 que é 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"));

Formatação do texto

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

Formato	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