Widgets

Um widget é um elemento da interface que oferece um ou mais dos seguintes elementos:

• estrutura para outros widgets, como cards e seções;
• informações ao usuário, como texto e imagens; ou
• Acessórios para ação, como botões, campos de entrada de texto ou caixas de seleção.

Os conjuntos de widgets adicionados a seções de cards definem o interface do usuário 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.

Tipos de widget

Os widgets de complementos geralmente são categorizados em três grupos: widgets estruturais, widgets informativos e widgets 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: A coleção de um ou mais botões de texto ou imagem, agrupados em um linha horizontal.
• Card: um único contexto cartão que contém uma ou mais seções do cartão. Você define como os usuários podem mover entre os cartões, configurando navegação por card.
• Cabeçalho do card: o cabeçalho de um determinado cartão. Os cabeçalhos do cartão podem ter títulos, subtítulos e um imagem. Ações do card e ações universais aparecem no as cabeçalho do card se o complemento os utilizar.
• Seção do card: A grupo coletado de widgets, dividido das outras seções do cartão por um regra horizontal e, opcionalmente, ter um cabeçalho de seção. Cada cartão deve ter de pelo menos uma seção do cartão. Não é possível adicionar cartões ou cabeçalhos de cartão a um cartão nesta seção.

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

Rodapé fixo

Você pode adicionar uma linha fixa de botões à parte inferior do cartão. Esta linha não se move nem rola com o restante do conteúdo do card.

O seguinte trecho de código 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

Quando novos conteúdos contextuais for acionada por uma ação do usuário, como abrir um mensagem do Gmail, você pode exibir o novo conteúdo contextual imediatamente (comportamento padrão) ou exibir uma notificação de card de exibição na parte inferior da na barra lateral. Se um usuário clicar em Voltar arrow_back para voltar à página inicial enquanto o acionador contextual estiver ativo, um card de exibição vai aparecer para ajudar os usuários a encontrar o o conteúdo contextual novamente.

Para exibir um card de exibição quando novo conteúdo contextual estiver disponível, em vez de exibindo imediatamente o novo conteúdo contextual, adicione .setDisplayStyle(CardService.DisplayStyle.PEEK) para seu CardBuilder . Um card de exibição só aparece se um único objeto de card for retornado com seu acionador contextual caso contrário, os cartões retornados substituirão imediatamente cartão atual.

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

O código a seguir, com base Guia de início rápido do complemento Cats para o Google Workspace, 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 exibir a mensagem do Gmail selecionada assunto da conversa.

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 indicado por um URL hospedado e acessível publicamente fornecido por você.
• DecoratedText: A texto string de conteúdo que pode ser combinada com outros elementos, como superior e inferior rótulos de texto e uma imagem ou ícone. Os widgets DecoratedText também podem incluir um Botão ou Widget Alternar. Interruptores adicionados podem ser botões de alternância ou caixas de seleção. O texto do conteúdo do widget DecoratedText pode usar Formatação HTML principais e os rótulos inferiores devem usar texto simples.
• Parágrafo de texto: A 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 a ações realizadas pelo usuários. É possível configurar esses widgets com respostas de ação para mostrar cards diferentes, abrir URLs, mostrar notificações, escrever rascunhos de e-mails, ou executar outras funções do Apps Script. Consulte a O guia Como criar cards interativos para detalhes.

• Ação do card: um menu 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 que os usuários selecionem uma data, uma hora ou ambos. Consulte Seletores de data e hora abaixo para mais informações.
• Botão de imagem: A que usa uma imagem em vez de texto. É possível usar um dos vários ícones predefinidos ou uma imagem hospedada publicamente indicada por seu URL.
• Entrada de seleção: uma campo de entrada que representa uma coleção de opções. Widgets de entrada de seleção apresentar como caixas de seleção, botões de opção ou caixas de seleção suspensas.
• Chave: um botão de ativação widget. Só é possível usar interruptores com um Widget DecoratedText. Por padrão aparecem como um botão, mas é possível fazer com que sejam exibidas uma caixa de seleção.
• Botão "Texto": A com um rótulo de texto. Você pode especificar uma cor de preenchimento de plano de fundo para o texto (o padrão é transparente). Você também pode desativar o botão necessários.
• Entrada de texto: um texto campo de entrada. O widget pode ter texto de título, texto de dica e texto multilinha. O widget pode acionar ações quando o valor do texto muda.
• Grade: uma com várias colunas um layout que representa uma coleção de itens. É possível representar itens com um imagem, título, subtítulo e uma variedade de opções de personalização, como bordas e estilos de corte.

DecoratedText caixas de seleção

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

O exemplo de código abaixo mostra como definir uma caixa de seleção DecoratedText. 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));

Seletores de data e hora

Você pode definir widgets que permitam aos usuários selecionar um horário, uma data ou ambos. É possível usar setOnChangeAction() para atribuir uma função de gerenciador de widgets a são executados quando o valor do seletor muda.

O exemplo de código a seguir mostra como definir um seletor somente de data, um e um seletor de data e hora, que podem ser adicionados a um cartão:

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"));

Este é um exemplo de função gerenciadora de widget do seletor de data e hora. Isso de dados e registra uma string que representa a data-hora escolhida pelo o 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 do seletor em computadores e dispositivos móveis. dispositivos. Quando selecionado, o seletor de datas abre uma interface da agenda baseada 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 um computador, um menu suspenso é aberto. com uma lista de horários separados em incrementos de 30 minutos que o usuário pode selecionar se originou. O usuário também pode digitar um horário específico. Em dispositivos móveis, ao selecionar um o seletor de horário abre o "relógio" integrado para dispositivos móveis seletor de horário.

Computador	Dispositivo móvel

Grade

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

É possível configurar um item de grade com um identificador que é retornado como um parâmetro até 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.

As tags compatíveis e suas finalidades são mostradas a seguir tabela: