Виджеты

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

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

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

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

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

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

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

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

При добавлении виджета в один из контейнеров вы создаете и добавляете копию этого виджета. Если вы измените виджет после его добавления, изменения не отобразятся в интерфейсе. Убедитесь, что виджет полностью готов, прежде чем добавлять его. Если вам нужно изменить виджет после его добавления, перестройте весь раздел карточки или саму карточку. Дополнительные сведения см. в разделе «Создание карточек» .

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

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

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

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

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

• Действие на карточке : пункт меню, размещенный в верхней панели меню дополнения. Верхняя панель меню также может содержать элементы, определенные как универсальные действия , которые отображаются на каждой карточке, определенной дополнением.
• Виджеты выбора даты и времени : позволяют пользователям выбирать дату, время или и то, и другое. Дополнительную информацию см. в разделе «Виджеты выбора даты и времени» .
• Кнопка с изображением : кнопка, использующая изображение вместо текста. Можно использовать один из нескольких предопределенных значков или общедоступное изображение.
• Поле ввода для выбора : поле ввода, представляющее собой набор вариантов. Виджеты поля ввода для выбора могут быть представлены в виде флажков, переключателей или раскрывающихся списков.
• Switch : виджет-переключатель, используемый с виджетом DecoratedText . По умолчанию он отображается как переключатель, но вы можете отобразить его как флажок .
• Текстовая кнопка : кнопка с текстовой меткой. Укажите цвет заливки для текстовых кнопок (по умолчанию — прозрачный). При необходимости кнопку можно также отключить.
• Текстовое поле ввода : Поле ввода текста. Виджет может содержать заголовок, подсказку и многострочный текст. Виджет может запускать действия при изменении значения текста.
• Сетка : Многоколоночная компоновка. Представляет элементы с изображением, заголовком, подзаголовком и параметрами настройки, такими как границы и стили обрезки.

флажки DecoratedText

Вы можете определить виджет DecoratedText , к которому вместо кнопки или бинарного переключателя прикреплен флажок. Аналогично переключателям, значение флажка включается в объект события действия, передаваемый методу setOnClickAction виджету 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-теги.

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