Widgets

Um widget é um elemento da interface 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, ou
• Affordances para ação, 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 interface geral do complemento. Os widgets têm a mesma aparência e função em dispositivos móveis e na Web. A documentação de referência descreve vários métodos para criar conjuntos de widgets.

Tipos de widget

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

Widgets estruturais

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

• Conjunto de botões: uma coleção 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. Defina como os usuários se movem entre os cards configurando a navegação dos cards.
• Cabeçalho do card: O cabeçalho de um card específico. Os cabeçalhos de cards podem ter títulos, subtítulos e uma imagem. As ações de cards e as ações universais aparecem no cabeçalho do card, se usadas.
• Seção do card: um grupo de widgets coletados, divididos de outras seções de cards por uma regra horizontal e, opcionalmente, com um cabeçalho de seção. Cada card precisa ter pelo menos uma seção. Não é possível adicionar cards ou cabeçalhos de cards a uma seção.

Ao adicionar um widget a um dos contêineres, você cria e adiciona uma cópia dele. Se você mudar o widget depois de adicioná-lo, a mudança não será refletida na interface. Verifique se o widget está completo antes de adicioná-lo. Se você precisar mudar um widget depois de adicioná-lo, recrie toda a seção ou o card. Consulte Criar cards para mais detalhes.

Além desses widgets estruturais básicos, em um complemento do Google Workspace, você pode usar o serviço Card para criar estruturas que se sobrepõem ao card atual: rodapés fixos e cards de visualização:

Rodapé fixo

É possível adicionar uma linha fixa de botões à parte de baixo do card. Essa linha não se move nem rola com o restante do conteúdo do card.

O trecho de código a seguir mostra como definir um rodapé fixo de exemplo e adicioná-lo a um card:

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

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

Exibir card

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

Para mostrar um card de visualização quando um novo conteúdo contextual estiver disponível, adicione .setDisplayStyle(CardService.DisplayStyle.PEEK) à sua CardBuilder classe. Um card de visualização só aparece se um único objeto de card for retornado com o acionador contextual. Caso contrário, os cards retornados vão substituir o card atual.

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

Com base no guia de início rápido do complemento Cats do Google Workspace, o código a seguir notifica os usuários sobre o novo conteúdo contextual com um card de visualização e personaliza o cabeçalho do card de visualização para mostrar 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);

Widgets informativos

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

• Imagem: uma imagem indicada por um URL hospedado e acessível publicamente.
• DecoratedText Os widgets DecoratedText também podem incluir um Button ou Switch widget. Os switches adicionados podem ser alternadores ou caixas de seleção. O texto do conteúdo pode usar formatação HTML. Os rótulos superior e inferior precisam usar texto simples.
• Parágrafo de texto: um parágrafo de texto que pode incluir elementos formatados em HTML.

Widgets de interação do usuário

Os widgets de interação do usuário permitem que o complemento responda às ações do usuário. Configure esses widgets com respostas de ação para mostrar cards diferentes, abrir URLs, mostrar notificações, criar rascunhos de e-mails ou executar outras funções do Apps Script. Consulte o guia Criar cards interativos para mais detalhes.

• Ação do 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 e hora: widgets que permitem aos usuários selecionar uma data, hora ou ambos. Consulte Seletores de data e hora para mais informações.
• Botão de imagem: um botão que usa uma imagem em vez de texto. Use um dos vários ícones predefinidos ou uma imagem hospedada publicamente.
• Entrada de seleção: um campo de entrada que representa uma coleção de opções. Os widgets de entrada de seleção são apresentados como caixas de seleção, botões de opção ou caixas de seleção suspensas.
• Switch: um widget de alternância usado com um widget DecoratedText. Por padrão, eles são mostrados como um switch, mas é possível mostrá-los como uma caixa de seleção.
• Botão de texto: um botão com um rótulo de texto. Especifique um preenchimento de cor de plano 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, texto de dica e texto de várias linhas. O widget pode acionar ações quando o valor do texto muda.
• Grade: um layout de várias colunas. Represente itens com uma imagem, título, subtítulo e opções de personalização, como estilos de borda e corte.

Caixas de seleção DecoratedText

É possível definir um DecoratedText widget que tenha uma caixa de seleção anexada, em vez de um botão ou um switch binário. Semelhante aos switches, o valor da caixa de seleção é incluído no objeto de evento de ação transmitido para a Action anexada a esse DecoratedText pelo método setOnClickAction.

O trecho de código a seguir mostra como definir um widget DecoratedText de caixa de seleção para adicionar a um card:

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

Seletores de data e hora

Defina widgets que permitam aos usuários selecionar uma hora, data ou ambos. Use setOnChangeAction para atribuir uma função de gerenciador de widgets a ser executada quando o valor do seletor mudar.

O trecho de código a seguir mostra como definir um seletor de data, um seletor de hora e um seletor de data e hora para adicionar a um card:

var dateOnlyPicker = CardService.newDatePicker()
    .setTitle("Enter a 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 a 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 a date and 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"));

Confira a seguir um exemplo de função de gerenciador de widgets de seletor de data e hora. Esse gerenciador formata e registra uma string que representa a data e a hora escolhidas pelo usuário em um widget de 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/workspace/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 a seguir mostra exemplos das interfaces de seleção de seletor em computadores e dispositivos móveis. Quando selecionado, o seletor de data abre uma interface de calendário mensal para permitir que o usuário selecione uma nova data.

Quando o usuário seleciona o seletor de hora em computadores, 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, selecionar um seletor de hora abre o seletor de hora "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 mostrar 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 de grade.

Configure um item de 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("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

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

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

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

Formatação do texto

Alguns widgets baseados em texto oferecem suporte à formatação HTML básica de texto. Ao definir o conteúdo de texto desses widgets, inclua as tags HTML correspondentes.

As tags com suporte e a finalidade delas são mostradas na tabela a seguir: