Azioni dell'editor

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

Gli oggetti Action definiscono cosa accade 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 gestore 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 trasmesso un oggetto evento che trasporta informazioni sulle interazioni lato client dell'utente. Devi implementare la funzione di callback e fare in modo che restituisca un oggetto di risposta specifico.

Esempio: visualizzare 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, procedi nel seguente modo:

  1. Crea un widget per il pulsante.
  2. Per impostare un'azione per la creazione di schede, aggiungi la funzione di gestore widget dei pulsanti setOnClickAction(action).
  3. Crea una funzione di callback di Apps Script da eseguire e specificala come (action) all'interno della funzione gestore 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.

L'esempio seguente mostra la creazione di un widget del 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 la funzione di callback dell'azione associata per restituire un oggetto di risposta specializzato:

Azione tentata La funzione di callback deve restituire
Richiedi l'accesso al file per il documento_corrente EditorFileScopeActionResponse

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

  • Il componente aggiuntivo utilizza 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 file manifest.

Richiedi l'accesso ai file per il documento corrente

Per richiedere l'accesso al file per il documento corrente, procedi nel seguente modo:

  1. Crea una scheda della home page per verificare 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: come 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 ha l'autorizzazione drive.file, mostra un pulsante per avviare l'autorizzazione nell'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();
}