Azioni dell'editor

Utilizza gli oggetti Azione per integrare un comportamento interattivo nei componenti aggiuntivi di Google Workspace.

Gli oggetti azione 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 collegare un'azione a un widget, utilizza una funzione di gestione dei 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 farle restituire 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 crea e visualizza una nuova scheda quando viene selezionato, segui questi passaggi:

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

Il seguente esempio 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 widget aggiuntiva 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 questa azione del widget e l'oggetto risposta, devono essere soddisfatte tutte le seguenti condizioni:

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

Richiedere 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. Per i casi in cui al componente aggiuntivo non è stato concesso l'ambito drive.file, crea un modo per richiedere agli utenti di concedere l'ambito drive.file per il documento corrente.

Esempio: ottenere l'accesso al documento corrente 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();
}