Azioni dell'editor

Utilizza gli oggetti Action per creare elementi interattivi il comportamento dei componenti aggiuntivi di Google Workspace.

Gli oggetti di 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 associare un'azione a un widget, utilizza una funzione di gestore dei widget. che definisce anche la condizione che attiva l'azione. Quando viene attivato, esegue una funzione di callback designata. Alla funzione di callback viene passato un oggetto evento che trasporta informazioni sulle interazioni lato client dell'utente. Devi a implementare la funzione callback e fare in modo che restituisca un oggetto di risposta specifico.

Esempio: mostrare una nuova scheda quando un utente fa clic su un pulsante

Se vuoi aggiungere al tuo componente aggiuntivo un pulsante che crei e mostri una nuova scheda quando fai clic su questo pulsante, procedi nel seguente modo:

  1. Crea un widget per il pulsante.
  2. Per impostare un'azione di creazione delle schede, aggiungi la funzione di gestore del widget del pulsante setOnClickAction(action)
  3. Crea una funzione di callback di Apps Script da eseguire e specificarla come (action) all'interno della funzione di gestore del widget. In questo caso, la funzione di callback creare la carta desiderata 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 con pulsanti. Le richieste di azione 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 un'ulteriore azione del widget per richiedere l'accesso ai file. Questa azione richiede funzione di callback di azione associata per restituire un oggetto risposta specializzato:

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

Per utilizzare questo oggetto azione e risposta del widget, è necessario che tutti i seguenti elementi essere vero:

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

Richiedi 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 verifichi 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 per richiedere agli utenti di concedere drive.file ambito per il documento corrente.

Esempio: ottenere l'accesso attuale ai documenti 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 dei 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();
}