Działania w edytorze

Używaj obiektów Action, aby tworzyć interaktywne działania w dodatkach do Google Workspace.

Obiekty działania określają, co się dzieje, gdy użytkownik wchodzi w interakcję z widżetem (np. przyciskiem) w interfejsie dodatku.

Dodawanie działania do widżetu

Aby dołączyć działanie do widżetu, użyj funkcji obsługi widżetu, która określa też warunek wywołujący działanie. Po wywołaniu działania wykonuje ono wyznaczone wywołanie zwrotne. Funkcja wywołania zwrotnego otrzymuje obiekt zdarzenia, który zawiera informacje o interakcjach użytkownika po stronie klienta. Musisz zaimplementować funkcję wywołania zwrotnego i sprawić, aby zwracała określony obiekt odpowiedzi.

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

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

1. Utwórz widżet przycisku.
2. Aby ustawić działanie związane z tworzeniem karty, dodaj funkcję obsługi widżetu przycisku setOnClickAction.
3. Utwórz funkcję wywołania zwrotnego Apps Script, która ma zostać wykonana, i określ ją jako action w funkcji obsługi widżetu. W takim przypadku wywołanie zwrotne powinno utworzyć żądaną kartę i zwrócić obiekt ActionResponse. Obiekt odpowiedzi informuje dodatek, że ma wyświetlić kartę utworzoną przez funkcję wywołania zwrotnego.

W przykładzie poniżej pokazujemy, jak utworzyć widżet przycisku. Czynność żąda zakresu drive.file dla 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
    // lets the user 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 związane z dostępem do plików w przypadku interfejsów API REST

Dodatki do Google Workspace, które rozszerzają Edytory i korzystają z interfejsów API REST, mogą zawierać dodatkowe działanie widżetu umożliwiające żądanie dostępu do pliku. To działanie wymaga, aby powiązana funkcja wywołania zwrotnego działania zwracała specjalny obiekt odpowiedzi:

Podjęte działanie	Funkcja wywołania zwrotnego powinna zwracać
Wysyłanie prośby o dostęp do pliku	EditorFileScopeActionResponse

Aby użyć tego działania widżetu i obiektu odpowiedzi, muszą być spełnione wszystkie te warunki:

• Dodatek korzysta z interfejsów REST API.
• Dodatek wyświetla okno zakresu pliku żądania za pomocą metody CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
• Dodatek zawiera w swoim manifeście zakres https://www.googleapis.com/auth/drive.file edytora i onFileScopeGranted aktywator.

Wysyłanie prośby o dostęp do pliku w bieżącym dokumencie

Aby poprosić o dostęp do plików w bieżącym dokumencie:

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

Przykład: uzyskiwanie dostępu do bieżącego dokumentu w Dokumentach

W przykładzie poniżej tworzymy interfejs Dokumentów, który wyświetla rozmiar bieżącego dokumentu. Jeśli dodatek nie ma drive.file autoryzacji, wyświetla przycisk umożliwiający rozpoczęcie autoryzacji zakresu pliku.

/**
 * Build a 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 lets the user 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
    // lets the user 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();
}