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

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

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

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

 "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 создаёт карточку домашней страницы, специфичную для Таблиц.

 "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

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

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

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

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

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

В следующем примере показана часть манифеста надстройки Google Workspace, относящаяся к addons . Дополнение использует REST API, поэтому для Google Таблиц включён триггер 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 . Функция-триггер использует информацию из объекта события, чтобы определить, как создавать карты дополнений, или иным образом управлять поведением дополнений.

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

Когда редактор является действующим хост-приложением надстройки, объекты событий включают поля объектов событий Docs , Sheets или Slides , которые содержат информацию о клиенте.

Если у дополнения нет разрешения на доступ к области 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"
          },
          ...
        }