Виджет — это элемент пользовательского интерфейса, который предоставляет одну или несколько из следующих возможностей:
- Структура для других виджетов, таких как карточки и разделы.
- Информация для пользователя, такая как текст и изображения, или
- Возможности для выполнения действий , такие как кнопки, текстовые поля ввода или флажки.
Наборы виджетов, добавляемые в разделы карточек, определяют общий пользовательский интерфейс дополнения. Виджеты имеют одинаковый внешний вид и функциональность как на веб-версии, так и на мобильных устройствах. В справочной документации описаны несколько методов создания наборов виджетов.
Типы виджетов
Дополнительные виджеты, как правило, делятся на три группы: структурные виджеты, информационные виджеты и виджеты для взаимодействия с пользователем.
Структурные виджеты
Структурные виджеты обеспечивают контейнеры и организацию для других виджетов, используемых в пользовательском интерфейсе.
- Набор кнопок — это совокупность одной или нескольких текстовых или графических кнопок, сгруппированных в горизонтальный ряд.
- Карточка — это контекстная карточка, содержащая один или несколько разделов. Способы перемещения пользователей между карточками определяются путем настройки навигации по карточкам .
- Заголовок карточки — заголовок для данной карточки. Заголовки карточек могут содержать заголовки, подзаголовки и изображение. Действия карточки и универсальные действия отображаются в заголовке карточки, если дополнение их использует.
- Раздел карточек — группа виджетов, отделенная от других разделов карточек горизонтальной линией и, при необходимости, имеющая заголовок раздела. Каждая карточка должна содержать как минимум один раздел. В раздел карточек нельзя добавлять карточки или заголовки карточек.
В дополнение к этим базовым структурным виджетам, в надстройке Google Workspace вы можете использовать службу 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();
Карта Peek
Когда пользователь активирует новый контекстный контент , например, открывает сообщение в Gmail, вы можете либо отобразить его немедленно (поведение по умолчанию), либо показать всплывающее уведомление в нижней части боковой панели. Если пользователь нажимает «Назад» (или «Назад»), чтобы вернуться на главную страницу, пока активен контекстный триггер, появляется всплывающее уведомление, помогающее пользователю снова найти нужный контент.
Чтобы отображать всплывающую карточку при появлении нового контекстного контента, вместо немедленного отображения этого контента добавьте в класс CardBuilder .setDisplayStyle(CardService.DisplayStyle.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. Подробности см. в руководстве по созданию интерактивных карточек .
- Действие на карточке — пункт меню, размещаемый в верхнем меню дополнения. Верхнее меню также может содержать пункты, определенные как универсальные действия , которые отображаются на каждой карточке, определенной дополнением.
- Виджеты выбора даты и времени — это инструменты, позволяющие пользователям выбирать дату, время или и то, и другое. Дополнительную информацию см. в разделе «Виджеты выбора даты и времени» ниже.
- Кнопка с изображением — это кнопка, которая использует изображение вместо текста. Вы можете использовать один из нескольких предопределенных значков или общедоступное изображение, указанное по его URL-адресу.
- Поле ввода выбора — это поле ввода, представляющее собой набор вариантов. Виджеты поля ввода выбора могут быть представлены в виде флажков, переключателей или раскрывающихся списков.
- Переключатель — виджет-переключатель. Переключатели можно использовать только в сочетании с виджетом DecoratedText . По умолчанию они отображаются как переключатель, но вы можете настроить их отображение на флажок .
- Текстовая кнопка — кнопка с текстовой меткой. Для текстовых кнопок можно указать цвет заливки фона (по умолчанию — прозрачный). При необходимости кнопку можно также отключить.
- Текстовое поле ввода — это текстовое поле ввода. Виджет может содержать заголовок, подсказку и многострочный текст. Виджет может запускать действия при изменении текстового значения.
- Сетка — многоколоночная структура, представляющая собой набор элементов. Вы можете отображать элементы с помощью изображения, заголовка, подзаголовка, а также ряда параметров настройки, таких как границы и стили обрезки.
флажки DecoratedText
Вы можете определить виджет DecoratedText , к которому прикреплен флажок вместо кнопки или бинарного переключателя. Как и в случае с переключателями, значение флажка включается в объект события действия , который передается методу setOnClickAction(action) виджету Action , прикрепленному к этому DecoratedText .
Приведённый ниже фрагмент кода показывает, как определить виджет 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);
}
}
В таблице ниже приведены примеры пользовательского интерфейса выбора даты в окне выбора даты на настольных и мобильных устройствах. При выборе даты открывается календарь с указанием месяца, позволяющий пользователю быстро выбрать новую дату.
На настольных устройствах при выборе средства выбора времени открывается выпадающее меню со списком временных интервалов с шагом в 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. » | Это первая строка. Это новая строка. |