Домашние страницы

Домашние страницы – это новая функция надстроек Google Workspace, которая позволяет определять одну или несколько неконтекстных карточек . Неконтекстные карточки используются для отображения пользовательского интерфейса, когда пользователь находится вне определенного контекста, например, когда пользователь просматривает свой почтовый ящик Gmail, но не открыл сообщение или черновик.

Домашние страницы позволяют отображать неконтекстный контент, как и приложения Google, на боковой панели быстрого доступа (Keep, Календарь и Задачи). Домашние страницы также могут служить отправной точкой, когда пользователь впервые открывает ваше дополнение, и полезны для обучения новых пользователей тому, как взаимодействовать с вашим дополнением.

Вы можете определить домашнюю страницу для своего дополнения, указав ее в манифесте проекта и реализовав одну или несколько функций homepageTrigger (см. Конфигурация домашней страницы ).

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

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

• При первом открытии дополнения на хосте (после авторизации).
• Когда пользователь переключается с контекстного контекста на неконтекстный контекст, когда надстройка открыта. Например, от редактирования события Календаря до основного Календаря.
• Когда пользователь нажимает кнопку «Назад» достаточное количество раз, чтобы вытащить все остальные карты из внутренних стопок .
• Когда взаимодействие пользовательского интерфейса с неконтекстной карточкой приводит к вызову Navigation.popToRoot() .

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

Конфигурация домашней страницы

Дополнения Google Workspace используют поле addOns.common.homepageTrigger для настройки содержания надстройки домашней страницы по умолчанию (неконтекстного) для всех хост-приложений в манифесте надстройки:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

• runFunction : имя функции Apps Script, которую вызывает платформа надстроек Google Workspace для отображения дополнительных карточек главной страницы. Эта функция является триггерной функцией домашней страницы . Эта функция должна создавать и возвращать массив объектов Card , составляющих пользовательский интерфейс домашней страницы. Если возвращается более одной карты, ведущее приложение отображает заголовки карт в списке, из которого пользователь может выбрать (см. Возврат нескольких карт ).

• enabled : следует ли включать карточки домашней страницы для этой области. Это поле является необязательным и по умолчанию имеет значение true . Установка значения false приводит к отключению карточек домашней страницы для всех хостов (если только они не переопределены для этого хоста; см. ниже).

Примечание. Чтобы хост мог использовать общую домашнюю страницу, в манифесте надстройки должны присутствовать как addOns.common.homepageTrigger , так и ресурс верхнего уровня хоста. Например, если addOns.gmail отсутствует в манифесте, надстройка отключена для Gmail и не будет отображать домашнюю страницу (или любые другие функции на этом хосте).

В дополнение к общей конфигурации в конфигурации каждого хост-приложения доступны также переопределения с одинаковой структурой для каждого хоста: addOns.gmail.homepageTrigger , addOns.calendar.homepageTrigger и т. д.:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

Обратите внимание, что это эквивалентно следующему фрагменту манифеста:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

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

Объекты событий домашней страницы

При вызове триггерной функции домашней страницы ( runFunction ), описанной выше, передается объект события , содержащий данные из контекста вызова.

Объекты событий домашней страницы не включают виджеты или контекстную информацию; передаваемая информация ограничена следующими общими полями объекта события :

• commonEventObject.clientPlatform
• commonEventObject.hostApp
• commonEventObject.userLocale и commonEventObject.userTimezone (но сведения об ограничениях см. в разделе Доступ к языковому стандарту и часовому поясу пользователя ).

См. объект Event для более подробной информации.

Другие неконтекстные карты

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

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