Виджеты

Виджет — это простой элемент пользовательского интерфейса, который обеспечивает одно или несколько из следующих действий:

  • Структура других виджетов , таких как карточки и разделы,
  • Информация для пользователя , такая как текст и изображения, или
  • Возможности для действий , такие как кнопки, поля ввода текста или флажки.

Наборы виджетов, добавленные в разделы карточек, определяют общий пользовательский интерфейс надстройки. Виджеты имеют одинаковый внешний вид и функции как в Интернете, так и на мобильных устройствах. Справочная документация описывает несколько методов создания наборов виджетов.

Используйте конструктор надстроек Google Workspace

Чтобы сэкономить время на разработке виджетов надстройки, дизайнеры могут использовать комплект для разработки пользовательского интерфейса надстроек Google Workspace, доступный на Figma . Вы можете создать учетную запись Figma или запросить лицензию у администратора вашей организации.

Просмотрите компоненты и используйте встроенные шаблоны для создания и визуализации виджетов.

Получить набор дизайнеров

Типы виджетов

Дополнительные виджеты обычно делятся на три группы: структурные виджеты, информационные виджеты и виджеты взаимодействия с пользователем.

Структурные виджеты

Структурные виджеты обеспечивают контейнеры и организацию для других виджетов, используемых в ИИ.

Структурные виджеты

  • Набор кнопок — набор из одной или нескольких текстовых или графических кнопок, сгруппированных в горизонтальный ряд.
  • Карточка — отдельная контекстная карточка, содержащая один или несколько разделов карточки. Вы определяете, как пользователи могут перемещаться между карточками, настроив навигацию по карточкам .
  • Заголовок карты — заголовок данной карты. Заголовки карточек могут иметь заголовки, подзаголовки и изображение. Карточные действия и универсальные действия отображаются в шапке карточки, если надстройка их использует.
  • Раздел карточки — собранная группа виджетов, отделенная от других разделов карточки горизонтальной линейкой и опционально имеющая заголовок раздела. Каждая карта должна иметь хотя бы один раздел карты. Вы не можете добавлять карточки или заголовки карточек в раздел карточек.

В дополнение к этим базовым структурным виджетам в надстройке Google Workspace вы можете использовать сервис карточек для создания структур, перекрывающих текущую карточку: фиксированные нижние колонтитулы и карточки просмотра :

Теперь вы можете добавить фиксированный ряд кнопок в нижнюю часть карточки. Эта строка не перемещается и не прокручивается вместе с остальным содержимым карточки. В следующем фрагменте кода показано, как определить пример фиксированного нижнего колонтитула и добавить его на карточку:

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

Пример исправленного виджета нижнего колонтитула

Посмотреть карту

Пример подсказки

Когда новый контекстный контент инициируется действием пользователя, например открытием сообщения Gmail, вы можете либо немедленно отобразить новый контекстный контент (поведение по умолчанию), либо отобразить уведомление о подсказке в нижней части боковой панели. Если пользователь нажимает Назад» для возврата на главную страницу при активном контекстном триггере, появляется карточка просмотра, помогающая пользователям снова найти контекстный контент.

Чтобы отображать карточку просмотра, когда доступно новое контекстное содержимое, вместо немедленного отображения нового контекстного содержимого, добавьте .setDisplayStyle(CardService.DisplayStyle.PEEK) в свой класс CardBuilder . Карта просмотра появляется только в том случае, если один объект карты возвращается с вашим контекстным триггером; в противном случае возвращенные карты немедленно заменяют текущую карту.

Чтобы настроить заголовок карты просмотра, добавьте метод .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 также могут включать в себя виджет « Кнопка» или « Переключатель ». Добавленные переключатели могут быть простыми переключателями или флажками . Текст содержимого виджета DecoratedText может использовать форматирование HTML ; верхняя и нижняя метки должны использовать обычный текст.
  • Текстовый абзац — простой текстовый абзац, который может включать элементы в формате HTML .




Виджеты взаимодействия с пользователем

Виджет действия карты

Виджеты взаимодействия с пользователем позволяют надстройке реагировать на действия, предпринимаемые пользователями. Вы можете настроить эти виджеты с ответами действий для отображения различных карточек, открытия URL-адресов, отображения уведомлений, составления черновиков электронных писем или запуска других функций Apps Script. Подробнее см. в руководстве по созданию интерактивных карт .

Виджеты взаимодействия с пользователем

  • Действие карты — пункт меню, размещенный в меню панели заголовка надстройки. Меню строки заголовка также может содержать элементы, определенные как универсальные действия , которые отображаются на каждой карточке, определяемой надстройкой.
  • Средства выбора даты и времени — виджеты , которые позволяют пользователям выбирать дату, время или и то, и другое. Дополнительные сведения см. в разделе Средства выбора даты и времени ниже.
  • Кнопка изображения — кнопка, которая использует изображение вместо текста. Вы можете использовать один из нескольких предопределенных значков или общедоступное изображение, указанное по его URL-адресу.
  • Ввод выбора — поле ввода, представляющее набор опций. Виджеты ввода выбора представлены в виде флажков, переключателей или раскрывающихся окон выбора.
  • Переключатель — виджет переключения. Вы можете использовать переключатели только в сочетании с виджетом 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 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"));
      

Пример персонализированной карты просмотра

Ниже приведен пример функции обработчика виджета средства выбора даты и времени. Этот обработчик просто форматирует и регистрирует строку, представляющую дату и время, выбранную пользователем в виджете выбора даты и времени с идентификатором «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);
  }
}

В таблице ниже показаны примеры пользовательского интерфейса выбора средств выбора на настольных и мобильных устройствах. При выборе средства выбора даты открывается пользовательский интерфейс календаря на основе месяца, чтобы пользователь мог быстро выбрать новую дату.

Когда пользователь выбирает средство выбора времени на настольных устройствах, открывается раскрывающееся меню со списком времени, разделенного с шагом 30 минут, из которого пользователь может выбирать. Пользователь также может ввести конкретное время. На мобильных устройствах при выборе средства выбора времени открывается встроенное средство выбора времени мобильных «часов».

Рабочий стол Мобильный
пример выбора средства выбора датыпример выбора мобильного средства выбора даты
пример выбора временипример выбора мобильного устройства выбора времени

Сетка

Отображение элементов в многоколоночном макете с помощью виджета сетки. Каждый элемент может отображать изображение, заголовок и подзаголовок. Используйте дополнительные параметры конфигурации, чтобы установить положение текста относительно изображения в элементе сетки.

Вы можете настроить элемент сетки с идентификатором, который возвращается в качестве параметра действия, определенного в сетке.

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

Пример виджета сетки

Форматирование текста

Некоторые текстовые виджеты могут поддерживать простое форматирование текста HTML. При настройке текстового содержимого этих виджетов просто включите соответствующие теги HTML. Поддерживаются следующие форматы:

Формат Пример Визуализированный результат
Смелый <b>test</b> тест
Курсив <i>test</i> тест
Подчеркнуть <u>test</u> тест
Зачеркнутый <s>test</s> тест
Цвет шрифта <font color="#ea9999">test</font> тест
Гиперссылка <a href="http://www.google.com">google</a> Google
Время <time>2020-02-16 15:00</time> 2020-02-16 15:00
Новая линия test <br> test тест
тест