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

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

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

Вы можете задать домашнюю страницу для своего дополнения, указав её в манифесте проекта и реализовав одну или несколько функций 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.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 .

Другие карты, не имеющие отношения к контексту.

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

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