Виджет — это элемент пользовательского интерфейса, который обеспечивает одну или несколько из следующих функций:
- Структура для других виджетов, таких как карточки и разделы,
- Информация для пользователя , такая как текст и изображения, или
- Средства для выполнения действий , такие как кнопки, поля ввода текста или флажки.
Наборы виджетов, добавленных в разделы карточек, определяют общий дополнительный пользовательский интерфейс. Виджеты имеют одинаковый внешний вид и функции как на веб-сайтах, так и на мобильных устройствах. В справочной документации описывается несколько методов создания наборов виджетов.
Типы виджетов
Дополнительные виджеты обычно делятся на три группы: структурные виджеты, информационные виджеты и виджеты взаимодействия с пользователем.
Структурные виджеты
Структурные виджеты предоставляют контейнеры и организацию для других виджетов, используемых в пользовательском интерфейсе.
- Набор кнопок — набор из одной или нескольких текстовых или графических кнопок, сгруппированных в горизонтальный ряд.
- Карточка — Единая контекстная карточка, которая содержит один или несколько разделов карточки. Вы определяете, как пользователи могут перемещаться между карточками, настраивая навигацию по карточкам .
- Заголовок карты — заголовок для данной карты. Заголовки карт могут иметь заголовки, подзаголовки и изображение. Действия карты и универсальные действия отображаются в заголовке карты, если дополнение их использует.
- Раздел карточек — собранная группа виджетов, отделенная от других разделов карточек горизонтальной линейкой и опционально имеющая заголовок раздела. Каждая карточка должна иметь по крайней мере один раздел карточек. Вы не можете добавлять карточки или заголовки карточек в раздел карточек.
В дополнение к этим базовым структурным виджетам в дополнении Google Workspace вы можете использовать службу карточек для создания структур, которые перекрывают текущую карточку: фиксированные нижние колонтитулы и обзорные карточки :
Фиксированный нижний колонтитул
Вы можете добавить фиксированный ряд кнопок в нижнюю часть вашей карточки. Этот ряд не перемещается и не прокручивается вместе с остальным содержимым карточки.
В следующем фрагменте кода показано, как определить пример фиксированного нижнего колонтитула и добавить его к карточке:
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();
Подглядеть карту
Когда новый контекстный контент запускается действием пользователя, например открытием сообщения Gmail, вы можете либо отобразить новый контекстный контент немедленно (поведение по умолчанию), либо отобразить уведомление о карточке просмотра в нижней части боковой панели. Если пользователь нажимает Back , чтобы вернуться на домашнюю страницу , пока активен контекстный триггер, появляется карточка просмотра, чтобы помочь пользователям снова найти контекстный контент.
Чтобы отобразить карточку Peek, когда доступен новый контекстный контент, вместо немедленного отображения нового контекстного контента добавьте .setDisplayStyle(CardService.DisplayStyle.PEEK) к вашему классу CardBuilder . Карточка Peek появляется только в том случае, если с вашим контекстным триггером возвращается один объект карты; в противном случае возвращенные карты немедленно заменяют текущую карту.
Чтобы настроить заголовок карты Peek, добавьте метод .setPeekCardHeader() со стандартным объектом CardHeader при создании контекстной карты. По умолчанию заголовок карты Peek содержит только имя вашего дополнения.
Следующий код, основанный на кратком руководстве по работе с надстройкой Cats Google Workspace , уведомляет пользователей о новом контекстном контенте с помощью карточки Peek и настраивает заголовок карточки Peek для отображения темы выбранной цепочки сообщений 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);
Информационные виджеты
Информационные виджеты предоставляют информацию пользователю.
- Изображение — изображение, указанное в предоставленном вами размещенном и общедоступном URL-адресе.
- DecoratedText — текстовая строка содержимого, которую можно связать с другими элементами, такими как верхняя и нижняя текстовые метки, а также изображение или значок. Виджеты DecoratedText также могут включать виджет Button или Switch . Добавленные переключатели могут быть переключателями или флажками . Текст содержимого виджета DecoratedText может использовать форматирование HTML ; верхняя и нижняя метки должны использовать обычный текст.
- Текстовый абзац — текстовый абзац, который может включать элементы в формате HTML .
Виджеты взаимодействия с пользователем
Виджеты взаимодействия с пользователем позволяют надстройке реагировать на действия, предпринимаемые пользователями. Вы можете настроить эти виджеты с ответами на действия для отображения различных карточек, открытия URL-адресов, показа уведомлений, составления черновиков писем или запуска других функций Apps Script. Подробности см. в руководстве Building Interactive Cards .
- Действие карты — пункт меню, размещенный в меню заголовка дополнения. Меню заголовка также может содержать элементы, определенные как универсальные действия , которые появляются на каждой карте, определяемой дополнением.
- DateTime pickers — виджеты, которые позволяют пользователям выбирать дату, время или и то, и другое. Подробнее см. Date and time pickers ниже.
- Кнопка изображения — кнопка, которая использует изображение вместо текста. Вы можете использовать один из нескольких предопределенных значков или общедоступное изображение, указанное по его URL.
- Выбор ввода — Поле ввода, представляющее набор опций. Виджеты выбора ввода представлены в виде флажков, радиокнопок или раскрывающихся списков выбора.
- Switch — виджет-переключатель. Вы можете использовать переключатели только в сочетании с виджетом DecoratedText . По умолчанию они отображаются как переключатель, но вы можете сделать так, чтобы они отображались как флажок .
- Кнопка «Текст» — кнопка с текстовой меткой. Вы можете указать цвет заливки фона для кнопок «Текст» (по умолчанию прозрачный). При необходимости вы также можете отключить кнопку.
- Текстовый ввод — поле ввода текста. Виджет может иметь текст заголовка, текст подсказки и многострочный текст. Виджет может запускать действия при изменении текстового значения.
- Сетка — многоколоночный макет, представляющий коллекцию элементов. Вы можете представлять элементы с помощью изображения, заголовка, подзаголовка и ряда параметров настройки, таких как стили границ и обрезки.
Флажки DecoratedText
Вы можете определить виджет DecoratedText , который имеет прикрепленный флажок вместо кнопки или бинарного переключателя. Как и в случае с переключателями, значение флажка включено в объект события действия , который передается в Action , прикрепленное к этому DecoratedText методом setOnClickAction(action) .
В следующем фрагменте кода показано, как определить виджет DecoratedText с флажком, который затем можно добавить на карточку:
var decoratedText = CardService.newDecoratedText()
// (...)
.setSwitch(CardService.newSwitch()
.setFieldName('form_input_switch_key')
.setValue('switch_is_on')
.setControlType(
CardService.SwitchControlType.CHECK_BOX));
Выбор даты и времени
Вы можете определить виджеты, которые позволяют пользователям выбирать время, дату или и то, и другое. Вы можете использовать setOnChangeAction() чтобы назначить функцию обработчика виджета для выполнения при изменении значения селектора.
В следующем фрагменте кода показано, как определить выбор только даты, выбор только времени и выбор даты и времени, которые затем можно добавить на карточку:
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"));
Ниже приведен пример функции обработчика виджета выбора даты и времени. Этот обработчик форматирует и регистрирует строку, представляющую дату и время, выбранные пользователем в виджете выбора даты и времени с идентификатором "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);
}
}
В следующей таблице показаны примеры UI выбора выбора на настольных компьютерах и мобильных устройствах. При выборе выбора даты открывается UI календаря на основе месяца, чтобы пользователь мог быстро выбрать новую дату.
Когда пользователь выбирает выбор времени на настольных устройствах, открывается раскрывающееся меню со списком времени, разделенного на 30-минутные интервалы, из которых пользователь может выбирать. Пользователь также может ввести определенное время. На мобильных устройствах выбор выбора времени открывает встроенный мобильный выбор времени «часы».
| Рабочий стол | Мобильный |
|---|---|
 |  |
 |  |
Сетка
Отображение элементов в многоколоночном макете с помощью виджета сетки. Каждый элемент может отображать изображение, заголовок и подзаголовок. Используйте дополнительные параметры конфигурации, чтобы задать расположение текста относительно изображения в элементе сетки.
Вы можете настроить элемент сетки с идентификатором, который возвращается в качестве параметра для действия, определенного в сетке.
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"));
Форматирование текста
Некоторые текстовые виджеты могут поддерживать простое форматирование текста HTML. При настройке текстового содержимого этих виджетов просто включите соответствующие теги HTML.
Поддерживаемые теги и их назначение показаны в следующей таблице:
| Формат | Пример | Результат визуализации |
|---|---|---|
| Смелый | "This is <b>bold</b>." | Это смело . |
| Курсив | "This is <i>italics</i>." | Это курсив . |
| Подчеркнуть | "This is <u>underline</u>." | Это подчеркивание . |
| Зачеркивание | "This is <s>strikethrough</s>." | Это |
| Цвет шрифта | "This is <font color=\"#FF0000\">red font</font>." | Это красный шрифт . |
| Гиперссылка | "This is a <a href=\"https://www.google.com\">hyperlink</a>." | Это гиперссылка . |
| Время | "This is a time format: <time>2023-02-16 15:00</time>." | Это формат времени: . |
| Новая строка | "This is the first line. <br> This is a new line. » | Это первая строка. Это новая линия. |