Azioni dell'editor

Utilizza gli oggetti Action per creare un comportamento interattivo nei componenti aggiuntivi di Google Workspace.

Gli oggetti Action definiscono cosa succede quando un utente interagisce con un widget (ad esempio un pulsante) nell'interfaccia utente del componente aggiuntivo.

Aggiungere un'azione a un widget

Per associare un'azione a un widget, utilizza una funzione di gestore del widget, che definisce anche la condizione che attiva l'azione. Quando viene attivata, l'azione esegue una funzione di callback designata. Alla funzione di callback viene passato un oggetto evento che contiene informazioni sulle interazioni lato client dell'utente. Devi implementare la funzione di callback e impostarla in modo che restituisca un oggetto di risposta specifico.

Esempio: visualizzare una nuova scheda quando viene fatto clic su un pulsante

Se vuoi aggiungere un pulsante al tuo componente aggiuntivo che crei e mostri una nuova scheda quando viene fatto clic, segui questi passaggi:

  1. Crea un widget pulsante.
  2. Per impostare un'azione di creazione della scheda, aggiungi la funzione di gestore del widget del pulsante setOnClickAction(action).
  3. Crea una funzione di callback di Apps Script da eseguire e specificala come (action) all'interno della funzione di gestore del widget. In questo caso, la funzione di callback deve creare la scheda che ti interessa e restituire un oggetto ActionResponse. L'oggetto response indica al componente aggiuntivo di visualizzare la scheda creata dalla funzione di callback.

L'esempio seguente mostra la creazione di un widget pulsante. L'azione richiede l'ambito drive.file per il file corrente per conto del componente aggiuntivo.

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

Interazioni di accesso ai file per le API REST

I componenti aggiuntivi di Google Workspace che estendono gli editor e utilizzano le API REST possono includere un'azione aggiuntiva del widget per richiedere l'accesso ai file. Questa azione richiede che la funzione di callback dell'azione associata restituisca un oggetto di risposta specializzato:

Azione tentata La funzione di callback deve restituire
Richiedi l'accesso ai file per current_document EditorFileScopeActionResponse

Per utilizzare questo oggetto di risposta e azione del widget, devono essere soddisfatte tutte le seguenti condizioni:

  • Il componente aggiuntivo utilizza API REST.
  • Il componente aggiuntivo mostra la finestra di dialogo dell'ambito del file della richiesta utilizzando il metodo CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
  • Il componente aggiuntivo include lo scopo editor https://www.googleapis.com/auth/drive.file e l'attivatore onFileScopeGranted nel file manifest.

Richiedi l'accesso al file per il documento corrente

Per richiedere l'accesso ai file per il documento corrente:

  1. Crea una scheda della home page che controlli se il componente aggiuntivo ha l'ambito drive.file.
  2. Nei casi in cui al componente aggiuntivo non sia stato concesso l'ambito drive.file, crea un modo per chiedere agli utenti di concedere l'ambito drive.file per il documento corrente.

Esempio: ottenere l'accesso ai documenti correnti in Documenti Google

L'esempio seguente crea un'interfaccia per Documenti Google che mostra le dimensioni del documento corrente. Se il componente aggiuntivo non dispone dell'autorizzazione drive.file, viene visualizzato un pulsante per avviare l'autorizzazione dell'ambito del 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();
}