Виджеты

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

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

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

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

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

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

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

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

В дополнение к этим базовым структурным виджетам в надстройке 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, вы можете либо немедленно отобразить новый контекстный контент (поведение по умолчанию), либо отобразить уведомление о просмотренной карточке в нижней части боковой панели. Если пользователь нажимает кнопку «Назад» arrow_back , чтобы вернуться на домашнюю страницу , когда активен контекстный триггер, появляется карточка просмотра, которая помогает пользователям снова найти контекстное содержимое.

Чтобы отобразить карточку просмотра при наличии нового контекстного содержимого, вместо немедленного отображения нового контекстного содержимого добавьте .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

Вы можете определить виджет 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);
  }
}

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

Когда пользователь выбирает средство выбора времени на настольных устройствах, открывается раскрывающееся меню со списком времен, разделенных интервалами по 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-теги.

Поддерживаемые теги и их назначение показаны в следующей таблице: