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 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 farla restituire un oggetto di risposta specifico.

Esempio: visualizzare una nuova scheda quando si fa clic su un pulsante

Se vuoi aggiungere un pulsante al componente aggiuntivo che crea e visualizza una nuova scheda quando si fa clic, segui questi passaggi:

  1. Crea un widget pulsante.
  2. Per impostare un'azione di creazione di schede, aggiungi la funzione di gestione dei widget pulsante setOnClickAction.
  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 ActionResponse oggetto. L'oggetto di risposta 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
    // 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();
}

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 EditorFileScopeActionResponse

Per utilizzare questa azione widget e l'oggetto di 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 ai file per il documento corrente

Per richiedere l'accesso ai file per il documento corrente, segui questi passaggi:

  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 è 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

L'esempio seguente crea un'interfaccia per Documenti che mostra le dimensioni del documento corrente. Se il componente aggiuntivo non ha l'autorizzazione drive.file, viene visualizzato un pulsante per avviare l'autorizzazione dell'ambito del file.

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