Creazione delle interfacce di 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 informazioni aggiuntive 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 relativa icona viene visualizzata 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 mentre è in Google Drive, il componente aggiuntivo esegue la funzione drive.homepageTrigger corrispondente (se presente). Questa funzione genera 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 della home page generica.
  • 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 corrispondente (se presente) drive.onItemsSelectedTrigger. Questa funzione crea l'interfaccia contestuale "Elementi selezionati" di Google Drive del componente aggiuntivo e la restituisce a Google Drive per la visualizzazione.

Creazione dell'interfaccia di Drive del 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 quando l'utente seleziona gli elementi di Drive.
  2. Aggiungi i campi appropriati addOns.common e addOns.drive al manifest del progetto dello script del componente aggiuntivo, inclusi eventuali scope di Drive richiesti.
  3. Se fornisci una home page specifica per Drive, implementa la funzione drive.homepageTrigger per creare questa interfaccia. Puoi anche scegliere di utilizzare l'interfaccia di common.homepageTrigger per più host Google Workspace.
  4. Se fornisci un'interfaccia di selezione di elementi contestuali di Drive, devi implementare una funzione di trigger contestuale drive.onItemsSelectedTrigger per creare questa interfaccia. Per maggiori 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 mostrare la home page comune del tuo componente aggiuntivo in Google Drive, assicurati che nel file manifest del componente aggiuntivo sia presente un campo addOns.drive.

In alternativa, aggiungi un 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 attivazione della home page nel progetto dello script del componente aggiuntivo. Questa funzione viene chiamata automaticamente per creare la home page di Drive quando è necessario. Devi implementare questa funzione per creare e restituire un singolo Card o un array di Card oggetti che compongono la home page. Alla funzione di attivazione della home page viene passato un oggetto evento come parametro che contiene alcune informazioni generali, come la piattaforma del client. Puoi utilizzare i dati dell'oggetto evento per personalizzare la creazione della home page.

Interfaccia contestuale di Drive per gli elementi selezionati

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

Per creare un'interfaccia di selezione di elementi contestuale per Drive, devi svolgere i seguenti passaggi:

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

  2. Assicurati che il 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 per qualsiasi scheda, devi implementare le funzioni di callback utilizzate per fornire l'interattività del widget per l'interfaccia. Ad esempio, se includi un pulsante nell'interfaccia, deve avere un'azione collegata e una funzione di callback implementata che viene eseguita quando si fa clic sul pulsante.

Eventi

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

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

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

L'esempio seguente mostra un oggetto evento 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"
          },
          ...
        ]
      },
      ...
    }