Создание интерфейсов Google Editor

С помощью надстроек Google Workspace вы можете предоставлять настраиваемые интерфейсы в редакторах, включая Документы, Таблицы и Слайды Google. Это позволяет предоставлять пользователю актуальную информацию, автоматизировать задачи и подключать к Редакторам сторонние системы.

Доступ к пользовательскому интерфейсу дополнения

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

Надстройка Google Workspace может предоставлять следующие интерфейсы:

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

• Интерфейсы REST API . Если надстройка использует REST API, вы можете включить триггеры, которые запрашивают пофайловый доступ к документу, используя область drive.file . После предоставления выполняется другой триггер с именем EDITOR_NAME .onFileScopeGrantedTrigger и отображает интерфейс, специфичный для файла.

• Интерфейсы предварительного просмотра ссылок . Если ваша надстройка интегрируется со сторонней службой, вы можете создавать карточки, которые просматривают контент из URL-адресов вашей службы.

Создание интерфейсов для надстроек редактора

Создайте интерфейсы надстроек редактора для редакторов, выполнив следующие действия:

1. Добавьте соответствующие поля addOns.common , addOns.docs , addOns.sheets и addOns.slides в манифест проекта сценария надстройки.
2. Добавьте все необходимые области редактора в манифест проекта скрипта.
3. Если вы предоставляете домашнюю страницу для конкретного редактора , реализуйте функцию EDITOR_NAME .homepageTrigger для создания интерфейса. Если нет, используйте интерфейс common.homepageTrigger для создания общей домашней страницы для ваших хост-приложений.
4. Если вы используете REST API, реализуйте поток авторизации области drive.file и триггерную функцию EDITOR_NAME .onFileScopeGrantedTrigger для отображения интерфейса, специфичного для открытого файла. Дополнительные сведения см. в разделе Интерфейсы REST API .
5. Если вы настраиваете предварительный просмотр ссылок из сторонней службы, реализуйте https://www.googleapis.com/auth/workspace.linkpreview поток авторизации области и функцию linkPreviewTriggers . Дополнительную информацию см. в разделе Интерфейсы предварительного просмотра ссылок .
6. Реализуйте связанные функции обратного вызова, необходимые для реагирования на взаимодействия пользователя с пользовательским интерфейсом, например нажатия кнопок.

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

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

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

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

Отобразить общую домашнюю страницу

Чтобы отобразить общую домашнюю страницу вашего дополнения в редакторах, включите соответствующие поля редактора, такие как addOns.docs , addOns.sheets или addOns.slides , в манифест дополнения.

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

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

Отобразить домашнюю страницу, специфичную для редактора

Чтобы представить домашнюю страницу, специфичную для редактора, добавьте EDITOR_NAME .homepageTrigger в манифест надстройки.

В следующем примере показана часть манифеста addons Google Workspace, посвященная надстройкам. Надстройка включена для Документов, Таблиц и Презентаций. Он отображает общую домашнюю страницу в Документах и ​​​​Презентации и уникальную домашнюю страницу в Таблицах. Функция обратного вызова onSheetsHomepage создает карточку домашней страницы, специфичную для Sheets.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

REST API-интерфейсы

Если ваша надстройка использует API-интерфейсы REST, такие как API Google Sheets , вы можете использовать функцию onFileScopeGrantedTrigger для отображения нового интерфейса, специфичного для файла, открытого в главном приложении Editor.

Чтобы использовать функцию onFileScopeGrantedTrigger , необходимо включить поток авторизации области drive.file . Чтобы узнать, как запросить область drive.file , см. раздел Запрос доступа к файлу для текущего документа .

Когда пользователь предоставляет область drive.file , срабатывает EDITOR_NAME .onFileScopeGrantedTrigger.runFunction . Когда триггер срабатывает, он выполняет контекстную функцию триггера, указанную в поле EDITOR_NAME .onFileScopeGrantedTrigger.runFunction в манифесте надстройки.

Чтобы создать интерфейс REST API для одного из редакторов, выполните следующие действия. Замените EDITOR_NAME хост-приложением Editor, которое вы решите использовать, например, sheets.onFileScopeGrantedTrigger .

1. Включите EDITOR_NAME .onFileScopeGrantedTrigger в соответствующий раздел редактора вашего манифеста. Например, если вы хотите создать этот интерфейс в Google Sheets, добавьте триггер в раздел "sheets" .
2. Реализуйте функцию, указанную в разделе EDITOR_NAME .onFileScopeGrantedTrigger . Эта функция принимает объект события в качестве аргумента и должна возвращать либо один объект Card , либо массив объектов Card .
3. Как и в случае с любой картой, вы должны реализовать функции обратного вызова, используемые для обеспечения интерактивности виджета для интерфейса. Например, если вы включаете кнопку в интерфейс, к ней должно быть прикреплено действие и реализована функция обратного вызова, которая запускается при нажатии кнопки.

В следующем примере показана часть манифеста addons Google Workspace, посвященная надстройкам. Надстройка использует REST API, поэтому для Google Sheets включен onFileScopeGrantedTrigger . Когда пользователь предоставляет область drive.file , функция обратного вызова onFileScopeGrantedSheets создает интерфейс для конкретного файла.

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

Интерфейсы предварительного просмотра ссылок для сторонних сервисов

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

Инструкции по включению предварительного просмотра ссылок см. в разделе Предварительный просмотр ссылок с помощью смарт-чипов .

Объекты событий

Объект события создается и передается функциям триггера, таким как EDITOR_NAME .homepageTrigger или EDITOR_NAME .onFileScopeGrantedTrigger . Функция триггера использует информацию в объекте события, чтобы определить, как создавать дополнительные карты или иным образом управлять поведением надстройки.

Полная структура объектов событий описана в Объекты событий .

Если редактор является действующим ведущим приложением надстройки, объекты событий включают поля объектов событий «Документы» , «Таблицы » или «Слайды », которые содержат информацию о клиенте.

Если надстройка не имеет авторизации области drive.file для текущего пользователя или документа, объект события содержит только поле docs.addonHasFileScopePermission , sheets.addonHasFileScopePermission или slides.addonHasFileScopePermission . Если надстройка имеет авторизацию, объект события содержит все поля объекта события Editor.

В следующем примере показан объект события Editor, который передается в sheets.onFileScopeGrantedTrigger . Здесь надстройка имеет полномочия области drive.file для текущего документа:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }