Esta página foi traduzida pela API Cloud Translation.

Widgets

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

Estrutura para outros widgets, como cards e seções.
Informações ao usuário, como texto e imagens.
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 do cartão definem a IU geral do complemento. Os widgets têm a mesma aparência e função na Web e em dispositivos móveis. A documentação de referência descreve vários métodos para criar conjuntos de widgets.

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

Widgets estruturais

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

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 do card. Para definir como os usuários podem se mover entre cartões, configure a navegação do cartão.
Cabeçalho do card: o cabeçalho de um determinado card. Os cabeçalhos dos cards podem ter títulos, subtítulos e uma imagem. Ações de cards e ações universais aparecem no cabeçalho do card se o complemento as usar.
Seção de cards: um grupo coletado de widgets, dividido das outras seções do card por uma regra horizontal e, opcionalmente, ter um cabeçalho de seção. Cada card precisa ter pelo menos uma seção. Não é possível adicionar cards ou cabeçalhos a uma seção de cards.

Widgets estruturais

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

Rodapé fixo

Agora você pode adicionar uma linha fixa de botões na parte de baixo do seu 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 exemplo de rodapé fixo 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

Exemplo de card de exibição

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 uma notificação de card de exibição na parte inferior da barra lateral. Se um usuário clicar em "Voltar" para retornar à página inicial enquanto um acionador contextual estiver ativo, um card de exibição será exibido para ajudar a encontrar o conteúdo contextual novamente.

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

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

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

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 exibiçã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 que você fornecer.
DecoratedText: uma string de conteúdo de texto que pode ser pareada com outros elementos, como rótulos de texto na parte de cima e de baixo e uma imagem ou ícone. Os widgets DecoratedText também podem incluir um widget Button ou Switch. As chaves adicionadas podem ser botões de alternância ou caixas de seleção. O texto de conteúdo do widget DecoratedText pode usar a formatação HTML. As etiquetas de cima e de baixo precisam usar texto simples.
Parágrafo de texto: um parágrafo de texto que pode incluir elementos formatados em HTML.

Widgets informativos

Widgets de interação do usuário

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 rascunhos de e-mails ou executar outras funções do Apps Script. Consulte o guia Como criar cards interativos para ver mais detalhes.

Ação do card: um item 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.
Seletor de data e hora: widgets que permitem que os usuários selecionem uma data, uma hora ou ambas. 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 um conjunto 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. Só é possível usar chaves em conjunto com um widget DecoratedText. Por padrão, elas são exibidas como uma chave, mas é possível fazer com que sejam exibidas como uma caixa de seleção.
Botão de texto: um botão com um rótulo de texto. É possível especificar uma cor de preenchimento de plano de fundo para botões de texto (o padrão é transparente). Você também pode 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 que representa uma coleção de itens. É possível representar itens com uma imagem, um título, um subtítulo e uma variedade de opções de personalização, como estilos de borda e de corte.

`DecoratedText` caixas de seleção

Você pode definir um widget DecoratedText que tenha uma caixa de seleção anexada, em vez de um botão ou uma chave binária. Assim como acontece com chaves, 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 abaixo mostra como definir um widget DecoratedText de caixa de seleção, que você pode 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));

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

Seletores de data e hora

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

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

Veja a seguir um exemplo de função do gerenciador de widgets do seletor de data e hora. Esse gerenciador simplesmente formata e registra uma string que representa a data e hora escolhida 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/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 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 horário abre o seletor de horário integrado do dispositivo móvel.

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

É possível configurar 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 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.

A tabela a seguir mostra as tags compatíveis e a finalidade delas:

Formato	Exemplo	Resultado renderizado
Negrito	`"This is <b>bold</b>."`	Esta opção está em negrito.
Itálico	`"This is <i>italics</i>."`	Está em itálico.
Sublinhado	`"This is <u>underline</u>."`	Isso é sublinhado.
Tachado	`"This is <s>strikethrough</s>."`	Isso está ~~tachado~~.
Cor da fonte	`"This is <font color=\"#FF0000\">red font</font>."`	Esta é uma fonte vermelha.
Hiperlink	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	Este é um hiperlink.
Tempo	`"This is a time format: <time>2023-02-16 15:00</time>."`	Este é um formato de hora: 2023-02-16 15:00.
Nova linha	`"This is the first line. <br> This is a new line.`"	Esta é a primeira linha. Esta é uma nova linha.

Widgets

Tipos de widget

Widgets estruturais

Rodapé fixo

Exibir card

Widgets informativos

Widgets de interação do usuário

DecoratedText caixas de seleção

Seletores de data e hora

Grade

Formatação do texto

`DecoratedText` caixas de seleção