Creazione di interfacce Google Drive

I componenti aggiuntivi di Google Workspace possono fornire interfacce personalizzate quando l'utente utilizza Google Drive. In questo modo puoi fornire all'utente ulteriori informazioni pertinenti, automatizzare le attività e collegare sistemi di terze parti a Google Drive.

Accesso all'interfaccia utente del componente aggiuntivo

Puoi aprire un componente aggiuntivo di Google Workspace in Google Drive se la sua icona appare nella colonna delle icone sul lato destro dell'interfaccia utente di Drive. Un componente aggiuntivo di Google Workspace può definire un'interfaccia della home page, un'interfaccia di selezione degli elementi o entrambe:

  • Se un utente fa clic sull'icona del componente aggiuntivo su Google Drive, il componente aggiuntivo esegue la funzione drive.homepageTrigger corrispondente (se presente). Questa funzione crea e restituisce una scheda della home page su Google Drive per la visualizzazione. Se non viene definita alcuna funzione drive.homepageTrigger, viene visualizzata una scheda generica della home page.
  • Se l'utente seleziona uno o più elementi in Google Drive e poi fa clic sull'icona del componente aggiuntivo o seleziona elementi mentre il componente aggiuntivo è aperto, il componente aggiuntivo esegue la funzione contestuale drive.onItemsSelectedTrigger corrispondente (se presente). Questa funzione crea l'interfaccia contestuale "Elementi selezionati" di Google Drive e la restituisce a Google Drive per la visualizzazione.

Creazione dell'interfaccia di Drive per il componente aggiuntivo

Per creare interfacce che estendono Google Drive, segui questi passaggi generali:

  1. Decidi se vuoi che il componente aggiuntivo abbia una home page specifica per Drive. Decidi anche se vuoi fornire un'interfaccia contestuale per quando l'utente seleziona elementi di Drive.
  2. Aggiungi i campi addOns.common e addOns.drive appropriati al manifest del progetto di script per i componenti aggiuntivi, inclusi eventuali ambiti di Drive richiesti.
  3. Se fornisci una home page specifica per Drive, implementa la funzione drive.homepageTrigger per creare l'interfaccia. Puoi anche scegliere di utilizzare l'interfaccia common.homepageTrigger per più host di Google Workspace.
  4. Se fornisci un'interfaccia di selezione degli elementi contestuali di Drive, devi implementare una funzione di attivazione contestuale drive.onItemsSelectedTrigger per creare l'interfaccia. Per i dettagli, consulta Interfaccia contestuale di Drive per gli elementi selezionati.
  5. Implementa le funzioni di callback associate necessarie per rispondere alle interazioni dell'utente con l'interfaccia utente, ad esempio i clic sui pulsanti.

Home page di Drive

Google Drive supporta la visualizzazione delle home page dei componenti aggiuntivi di Google Workspace. Per visualizzare la home page comune del componente aggiuntivo su Google Drive, assicurati che il suo file manifest contenga un campo addOns.drive.

In alternativa, aggiungi un elemento drive.homepageTrigger al file manifest del componente aggiuntivo per fornire una home page specifica per Drive.

In entrambi i casi, devi fornire il nome di una funzione di trigger della home page nel progetto di script del componente aggiuntivo. Questa funzione viene richiamata automaticamente per creare la home page di Drive quando è necessario. Devi implementare questa funzione per creare e restituire un singolo oggetto Card o un array di oggetti Card che compongono la home page. Alla funzione di attivazione della home page viene trasmesso un oggetto evento sotto forma di parametro che contiene alcune informazioni generali come la piattaforma del client. Puoi utilizzare i dati dell'oggetto evento per personalizzare la costruzione della home page.

Interfaccia contestuale di Drive per gli elementi selezionati

Google Drive si basa su un attivatore contestuale per determinare quale interfaccia (se presente) visualizzare quando l'utente seleziona uno o più elementi di Google Drive. Quando l'attivatore si attiva, esegue la funzione dell'attivatore contestuale specificata dal campo drive.onItemsSelectedTrigger.runFunction nel manifest del componente aggiuntivo.

Per creare un'interfaccia di selezione contestuale degli elementi per Drive, devi:

  1. Assicurati che il manifest del componente aggiuntivo includa l'https://www.googleapis.com/auth/drive.addons.metadata.readonly ambito

  2. Assicurati che il file manifest includa una sezione drive.onItemsSelectedTrigger.

  3. Implementa la funzione denominata nel campo drive.onItemsSelectedTrigger. Questa funzione accetta un oggetto evento come argomento e deve restituire un singolo oggetto Card o un array di oggetti Card.

  4. Come con qualsiasi scheda, devi implementare eventuali funzioni di callback utilizzate per fornire interattività del widget per l'interfaccia. Ad esempio, se includi un pulsante nell'interfaccia, a questo deve essere associata un'azione e una funzione di callback implementata che viene eseguita quando l'utente fa clic sul pulsante.

Oggetti evento

Un oggetto evento viene creato e passato alla funzione di trigger drive.homepageTrigger o drive.onItemsSelectedTrigger quando queste funzioni vengono chiamate. La funzione trigger può utilizzare le informazioni in questo oggetto evento per determinare come creare schede di componenti aggiuntivi o controllare in altro modo il comportamento del componente aggiuntivo.

La struttura completa degli oggetti evento è descritta in Oggetti evento. Quando Drive è l'app host del componente aggiuntivo, gli oggetti evento contestuali includono il campo Oggetto evento Drive, che trasporta le informazioni del client specifiche per Drive.

Gli oggetti evento di Drive contestuali per gli attivatori di selezione degli elementi includono informazioni sugli elementi che l'utente ha selezionato quando si attiva l'attivatore. Quando un utente seleziona più di un elemento in Drive, uno degli elementi viene considerato di interesse principale; questo elemento è definito elemento cursore attivo.

L'esempio seguente mostra un oggetto evento di Drive che viene passato a una funzione drive.onItemsSelectedTrigger:

    {
      "commonEventObject": { ... },
      "drive": {
        "activeCursorItem":{
          "addonHasFileScopePermission": true,
          "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
          "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
          "mimeType":"application/pdf",
          "title":"How to get started with Drive"
        },
        "selectedItems": [
          {
            "addonHasFileScopePermission": true,
            "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
            "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
            "mimeType":"application/pdf",
            "title":"How to get started with Drive"
          },
          ...
        ]
      },
      ...
    }