Действия редактора

Используйте объекты Action для создания интерактивного поведения в надстройках Google Workspace.

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

Добавить действие в виджет

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

Пример: отображение новой карточки при нажатии кнопки.

Если вы хотите добавить в свое дополнение кнопку, которая при нажатии создает и отображает новую карточку, выполните следующие действия:

  1. Создайте виджет -кнопку.
  2. Чтобы задать действие по созданию карточки, добавьте функцию обработчика виджета кнопки setOnClickAction(action) .
  3. Создайте функцию обратного вызова Apps Script для выполнения и укажите её как (action) в функции-обработчике виджета. В этом случае функция обратного вызова должна создать нужную карточку и вернуть объект ActionResponse . Объект ответа сообщает дополнению о необходимости отобразить карточку, созданную функцией обратного вызова.

В следующем примере показано создание виджета-кнопки. Действие запрашивает область действия drive.file для текущего файла от имени дополнения.

/**
 * Adds a section to the Card Builder that displays a "REQUEST PERMISSION" button.
 * When it's clicked, the callback triggers file scope permission flow. This is used in
 * the add-on when the home-page displays basic data.
 */
function addRequestFileScopeButtonToBuilder(cardBuilder) {
    var buttonSection = CardService.newCardSection();
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClickedInEditor");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setBackgroundColor("#4285f4")
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
      .setOnClickAction(buttonAction);

    buttonSection.addWidget(button);
    cardBuilder.addSection(buttonSection);
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the 
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClickedInEditor(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();

Взаимодействие с доступом к файлам для REST API

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

Попытка действия Функция обратного вызова должна возвращать
Запросить доступ к файлу current_document EditorFileScopeActionResponse

Чтобы использовать этот объект действия и ответа виджета, должны выполняться все следующие условия:

  • Дополнение использует REST API.
  • Дополнение представляет диалоговое окно области действия файла запроса с помощью метода CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();
  • Дополнение включает в свой манифест область редактора https://www.googleapis.com/auth/drive.file и триггер onFileScopeGranted .

Запросить доступ к файлу для текущего документа

Чтобы запросить доступ к файлу текущего документа, выполните следующие действия:

  1. Создайте карточку домашней страницы, которая проверяет, имеет ли дополнение область действия drive.file .
  2. Для случаев, когда надстройке не предоставлена область действия drive.file , создайте способ запрашивать у пользователей предоставление области действия drive.file для текущего документа.

Пример: получить текущий доступ к документу в Google Docs

В следующем примере создается интерфейс для Google Docs, отображающий размер текущего документа. Если у надстройки нет авторизации drive.file , она отображает кнопку для инициализации авторизации области действия файла.

/**
 * Build a simple card that checks selected items' quota usage. Checking
 * quota usage requires user-permissions, so this add-on provides a button
 * to request `drive.file` scope for items the add-on doesn't yet have
 * permission to access.
 *
 * @param e The event object passed containing information about the
 *   current document.
 * @return {Card}
 */
function onDocsHomepage(e) {
  return createAddOnView(e);
}

function onFileScopeGranted(e) {
  return createAddOnView(e);
}

/**
 * For the current document, display either its quota information or
 * a button that allows the user to provide permission to access that
 * file to retrieve its quota details.
 *
 * @param e The event containing information about the current document
 * @return {Card}
 */
function createAddOnView(e) {
  var docsEventObject = e['docs'];
  var builder =  CardService.newCardBuilder();

  var cardSection = CardService.newCardSection();
  if (docsEventObject['addonHasFileScopePermission']) {
    cardSection.setHeader(docsEventObject['title']);
    // This add-on uses the recommended, limited-permission `drive.file`
    // scope to get granular per-file access permissions.
    // See: https://developers.google.com/drive/api/v2/about-auth
    // If the add-on has access permission, read and display its quota.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "This file takes up: " + getQuotaBytesUsed(docsEventObject['id'])));
  } else {
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "The add-on needs permission to access this file's quota."));

    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClicked");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setOnClickAction(buttonAction);

    cardSection.addWidget(button);
  }
  return builder.addSection(cardSection).build();
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClicked(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}