Genera azioni

Gli oggetti Action consentono di creare un comportamento interattivo nei componenti aggiuntivi di Google Workspace. Definiscono cosa accade quando un utente interagisce con un widget (ad esempio, un pulsante) nell'interfaccia utente del componente aggiuntivo.

Un'azione viene associata a un determinato widget utilizzando 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.

Ad esempio, supponiamo che tu voglia un pulsante che crei e visualizzi una nuova scheda quando viene fatto clic. Per farlo, devi creare un nuovo widget dei pulsanti e utilizzare la funzione di gestione del widget setOnClickAction(action) per impostare una creazione di schede Action. Il valore Action che definisci specifica una funzione di callback di Apps Script che viene eseguita quando viene fatto clic sul pulsante. In questo caso, implementerai la funzione di callback per creare la scheda che ti interessa e restituire un oggetto ActionResponse. L'oggetto risposta indica al componente aggiuntivo di visualizzare la scheda creata dalla funzione di callback.

In questa pagina vengono descritte le azioni dei widget specifiche per Drive che puoi includere nel componente aggiuntivo.

Generare interazioni

I componenti aggiuntivi di Google Workspace che estendono Drive possono includere un'azione widget aggiuntiva specifica per Drive. 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 ai file selezionati	DriveItemsSelectedActionResponse

Per utilizzare queste azioni widget e questi oggetti risposta, tutte le seguenti condizioni devono essere vere:

• L'azione viene attivata quando per l'utente sono selezionati uno o più elementi di Drive.
• Il componente aggiuntivo include l'https://www.googleapis.com/auth/drive.file ambito di Drive nel file manifest.

Richiedi l'accesso ai file selezionati

L'esempio seguente mostra come creare un'interfaccia contestuale per Google Drive che viene attivata quando l'utente seleziona uno o più elementi di Drive. L'esempio testa ogni elemento per verificare se al componente aggiuntivo è stata concessa l'autorizzazione di accesso. In caso contrario, utilizza un oggetto DriveItemsSelectedActionResponse per richiedere l'autorizzazione all'utente. Dopo aver concesso l'autorizzazione per un elemento, il componente aggiuntivo mostra l'utilizzo della quota di Drive dell'elemento.

/**
 * 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 contextual information about
 *    the Drive items selected.
 * @return {Card}
 */
function onDriveItemsSelected(e) {
  var builder =  CardService.newCardBuilder();

  // For each item the user has selected in Drive, display either its
  // quota information or a button that allows the user to provide
  // permission to access that file to retrieve its quota details.
  e['drive']['selectedItems'].forEach(
    function(item){
      var cardSection = CardService.newCardSection()
          .setHeader(item['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 (item['addonHasFileScopePermission']) {
        // If the add-on has access permission, read and display its
        // quota.
        cardSection.addWidget(
          CardService.newTextParagraph().setText(
              "This file takes up: " + getQuotaBytesUsed(item['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")
          .setParameters({id: item.id});

        var button = CardService.newTextButton()
          .setText("Request permission")
          .setOnClickAction(buttonAction);

        cardSection.addWidget(button);
      }

      builder.addSection(cardSection);
    });

  return builder.build();
}

/**
 * Callback function for a button action. Instructs Drive to display a
 * permissions dialog to the user, requesting `drive.file` scope for a
 * specific item on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the item's
 *   Drive ID.
 * @return {DriveItemsSelectedActionResponse}
 */
function onRequestFileScopeButtonClicked (e) {
  var idToRequest = e.parameters.id;
  return CardService.newDriveItemsSelectedActionResponseBuilder()
      .requestFileScope(idToRequest).build();
}

/**
 * Use the Advanced Drive Service
 * (See https://developers.google.com/apps-script/advanced/drive),
 * with `drive.file` scope permissions to request the quota usage of a
 * specific Drive item.
 *
 * @param {string} itemId The ID of the item to check.
 * @return {string} A description of the item's quota usage, in bytes.
 */
function getQuotaBytesUsed(itemId) {
  try {
    return Drive.Files.get(itemId,{fields: "quotaBytesUsed"})
        .quotaBytesUsed + " bytes";
  } catch (e) {
    return "Error fetching how much quota this item uses. Error: " + e;
  }
}