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 para o usuário, como textos 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 interface geral do complemento. Eles 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 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 alternar entre eles, configure a navegação de cards.
- Cabeçalho do card: o cabeçalho de um determinado card. Os cabeçalhos do cartão podem ter títulos, subtítulos e uma imagem. Ações de card e ações universais aparecem no cabeçalho do card se elas forem usadas pelo complemento.
- Seção de cards: um grupo coletado de widgets, dividido das outras seções do card por uma regra horizontal e, opcionalmente, um cabeçalho de seção. Cada card precisa ter pelo menos uma seção. Não é possível adicionar cartões ou cabeçalhos a uma seção de cartões.
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 exibidos:
Rodapé fixo
É possível adicionar uma linha fixa de botões na parte inferior 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 cartão:
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 exibir o novo conteúdo contextual imediatamente (comportamento padrão) ou exibir uma notificação de card de exibição na parte de baixo 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 de exibição só vai aparecer 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 de exibição, adicione o método .setPeekCardHeader() com
um objeto CardHeader
padrão ao criar seu card contextual. Por padrão, um cabeçalho "Peek card"
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 gatos, 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 de mensagem 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);
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ê fornece.
- DecoratedText: uma string de conteúdo de texto que pode ser pareada com outros elementos, como rótulos de texto de cima e de baixo, e uma imagem ou ícone. Os widgets DecoratedText também podem incluir um widget Button ou Switch. Chaves adicionadas podem ser botões de alternância ou caixas de seleção. O texto de conteúdo do widget DecoratedText pode usar 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 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 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 a seção 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 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 com um widget DecoratedText. Por padrão, eles são mostrados como uma chave de ativação, mas podem ser mostrados 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 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 multilinha. 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. Você pode representar itens com uma imagem, um título, um subtítulo e diversas opções de personalização, como estilos de borda e 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 um interruptor
binário. Assim como nas chaves, o valor da caixa de seleção é incluído no
objeto de evento de ação
que é transmitido ao Action
anexado a esse DecoratedText
pelo
método
setOnClickAction(action).
O trecho de código abaixo 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));
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 de 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 hora e um seletor de data-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"));
Este é um exemplo de uma função do gerenciador de widgets de seletor de data e hora. Esse gerenciador 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 a seguir mostra exemplos das IUs de seleção do seletor em computadores e dispositivos móveis. Quando selecionado, o seletor de data abre uma interface de calendário com base em 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 em que o usuário pode selecionar. O usuário também pode digitar um horário específico. Em dispositivos móveis, a ação de um seletor de horário abre o seletor de horário integrado do dispositivo móvel.
| Computador | Dispositivo móvel |
|---|---|
|
|
|
|
Grade
Exiba 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 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 podem ser compatíveis com formatação HTML de texto simples. Ao definir o conteúdo de texto desses widgets, inclua apenas as tags HTML correspondentes.
A tabela a seguir mostra as tags compatíveis e as finalidades delas:
| Formato | Exemplo | Resultado renderizado |
|---|---|---|
| Negrito | "This is <b>bold</b>." |
Isso 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 é |
| Cor da fonte | "This is <font color=\"#FF0000\">red font</font>." |
Essa é a 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: . |
| Nova linha | "This is the first line. <br> This is a new line. pol. |
Esta é a primeira linha. Esta é uma nova linha. |