Działania w edytorze

Używanie obiektów Action do tworzenia interakcji w dodatkach do Google Workspace.

Obiekty działań określają, co się dzieje, gdy użytkownik wchodzi w interakcję z widżetem (na przykład przycisku) w interfejsie dodatku.

Dodawanie działania do widżetu

Aby dołączyć działanie do widżetu, użyj funkcji obsługi widżetów. który definiuje również warunek wyzwalający działanie. Po uruchomieniu wykonuje wyznaczoną funkcję wywołania zwrotnego. Funkcja wywołania zwrotnego jest przekazywana do obiektu zdarzenia. który zawiera informacje o interakcjach po stronie klienta. Musisz zaimplementujesz funkcję wywołania zwrotnego tak, by zwracała ona określony obiekt odpowiedzi.

Przykład: wyświetlanie nowej karty po kliknięciu przycisku

Jeśli chcesz dodać do dodatku przycisk, który tworzy i wyświetla nową kartę wykonaj te czynności:

1. Utwórz widżet przycisku.
2. Aby ustawić działanie tworzenia karty, dodaj funkcję obsługi widżetu przycisku setOnClickAction(action)
3. Utwórz funkcję wywołania zwrotnego Apps Script do wykonania i określ ją jako (action) w ramach funkcji obsługi widżetu. W tym przypadku funkcja wywołania zwrotnego powinien utworzyć odpowiednią kartę i zwrócić obiekt ActionResponse. Obiekt odpowiedzi informuje dodatek, że ma wyświetlić kartę utworzoną przez funkcję wywołania zwrotnego.

Poniższy przykład pokazuje proces tworzenia widżetu przycisku. Prośby dotyczące działania zakres drive.file bieżącego pliku w imieniu dodatku.

/**
 * 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();

Interakcje z dostępem do plików w interfejsach API typu REST

Dodatki do Google Workspace, które rozszerzają funkcje edytorów i korzystają z interfejsów API REST, mogą zawierać komponent dodatkowe działanie widżetu, aby poprosić o dostęp do pliku. To działanie wymaga powiązana funkcja wywołania zwrotnego działania, która zwraca specjalistyczny obiekt odpowiedzi:

Podjęto próbę wykonania działania	Funkcja wywołania zwrotnego powinna zwrócić
Prośba o dostęp do pliku current_document	EditorFileScopeActionResponse

Aby można było korzystać z tego działania widżetu i obiektu odpowiedzi, muszą być spełnione wszystkie poniższe warunki. być prawda:

• Dodatek używa interfejsów REST API.
• Dodatek wyświetla okno zakresu pliku żądania za pomocą metody CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
• Dodatek obejmuje https://www.googleapis.com/auth/drive.file zakres edytora i Wyzwalacz onFileScopeGranted w pliku manifestu.

Poproś o dostęp do bieżącego dokumentu

Aby poprosić o dostęp do bieżącego dokumentu, wykonaj te czynności:

1. Utwórz kartę strony głównej, która sprawdza, czy dodatek ma zakres drive.file.
2. W przypadku, gdy dodatek nie ma zakresu drive.file, utwórz jak poprosić użytkowników o przyznanie zakresu drive.file dla bieżącego dokumentu.

Przykład: uzyskanie bieżącego dostępu do dokumentów w Dokumentach Google

Poniższy przykład pokazuje interfejs Dokumentów Google, który wyświetla rozmiar bieżącego dokumentu. Jeśli dodatek nie ma autoryzacji drive.file, wyświetla przycisk umożliwiający rozpoczęcie autoryzacji zakresu plików.

/**
 * 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();
}