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

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

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

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

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

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

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

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

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

В следующем примере показана часть addons в манифесте надстройки Google Workspace. Надстройка использует REST API, поэтому onFileScopeGrantedTrigger включен для Google Sheets. Когда пользователь предоставляет область 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 scope для текущего пользователя или документа, объект события содержит только поле 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"
          },
          ...
        }