Um widget é um elemento de IU simples que fornece 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
- Dificuldades de 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.
Usar o kit de design de complementos do Google Workspace
Para economizar tempo ao projetar widgets de um complemento, os designers podem usar o kit de design de IU dos complementos do Google Workspace, disponível no Figma. É possível criar uma conta do Figma ou solicitar uma licença ao administrador da sua organização.
Navegue pelos componentes e use modelos integrados para criar e visualizar widgets.
Tipos de widget
Os widgets de complemento 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 IA.
- 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. Você define como os usuários podem alternar entre os cartões configurando a navegação do cartão.
- Cabeçalho do card: o cabeçalho de um determinado card. Os cabeçalhos de cartão podem ter títulos, legendas e uma imagem. Ações de cards e ações universais aparecem no cabeçalho do card se forem usadas pelo complemento.
- Seção do cartão: um grupo de widgets coletado, 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ão a uma seção de cartão.
Além desses widgets estruturais básicos, em um complemento do Google Workspace, é possível usar o serviço Card para criar estruturas que se sobrepõem ao cartão atual: rodapés fixos e cards de consulta:
Rodapé fixo
Agora você pode adicionar uma linha fixa de botões na 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
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 do card de visualização 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 cartão de exibição aparecerá para ajudar os usuários a encontrar o conteúdo contextual novamente.
Para exibir um card de exibição quando novo conteúdo contextual estiver disponível, em vez de
exibir imediatamente o novo conteúdo contextual, adicione
.setDisplayStyle(CardService.DisplayStyle.PEEK) à sua classe
CardBuilder. Um cartão de exibição só aparecerá se um único objeto de cartão for retornado com seu
acionador contextual. Caso contrário, os cartões retornados substituirão imediatamente o
cartão 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 cartão contextual. Por padrão, um cabeçalho de cartão Peek
contém apenas o nome do complemento.
O código a seguir, baseado no guia de início rápido do complemento Cats Google Workspace, notifica os usuários sobre novos conteúdos contextuais com um cartão Peek e personaliza o cabeçalho desse cartão para exibir o assunto da conversa 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 fornecido por você.
- DecoratedText: uma string de conteúdo de texto que você pode parear com outros elementos, como rótulos de texto na parte superior e inferior, e uma imagem ou ícone. Os widgets DecoratedText também podem incluir um widget Button ou Switch. Interruptores adicionados podem ser botões ativar 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
Os widgets de interação do usuário permitem que o complemento responda às ações realizadas pelos usuários. Configure esses widgets com respostas de ação para exibir cartões diferentes, abrir URLs, mostrar notificações, escrever e-mails de rascunho 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 que fica 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, 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. Widgets de entrada de seleção presentes 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 um botão de alternância, mas é possível fazer com que elas sejam exibidas 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 fundo para os 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 multilinha. O widget pode acionar ações quando o valor do texto é alterado.
- Grid: 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 de corte.
Caixas de seleção DecoratedText
Você pode definir um widget DecoratedText
com uma caixa de seleção anexada, em vez de um botão ou botão 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 para o Action
anexado a esse DecoratedText
pelo
método
setOnClickAction(action).
O trecho de código a seguir 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 que os usuários selecionem uma hora, uma data ou ambas.
Você pode usar setOnChangeAction() para atribuir uma função de gerenciador de widget para
executar quando o valor do seletor mudar.
O trecho de código a seguir mostra como definir um seletor de somente data, um seletor de horário e um seletor de data e hora, que você pode adicionar 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 datas abre uma IU de calendário baseada em mês para permitir que o usuário selecione uma nova data rapidamente.
Quando o usuário seleciona o seletor de tempo em computadores, um menu suspenso é aberto com uma lista de horários separados por 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 relógio.
| Computador | Dispositivo móvel |
|---|---|
|
|
|
|
Grade
Exibir 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 da grade.
É possível configurar um item da grade com um identificador 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, inclua apenas as tags HTML correspondentes.
As tags compatíveis e a finalidade delas são mostradas na tabela a seguir:
| Formato | Exemplo | Resultado renderizado |
|---|---|---|
| Negrito | "This is <b>bold</b>." |
Essa opção está em negrito. |
| Itálico | "This is <i>italics</i>." |
Ela está em itálico. |
| Sublinhado | "This is <u>underline</u>." |
Isso é um sublinhado. |
| Tachado | "This is <s>strikethrough</s>." |
Isso é |
| Cor da fonte | "This is <font color=\"#FF0000\">red font</text>." |
Esta é 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." |
Esta é a primeira linha. Esta é uma nova linha. |