Creazione di interfacce Google Editor

Con i componenti aggiuntivi di Google Workspace, puoi fornire interfacce personalizzate all'interno degli editor, tra cui Documenti, Fogli e Presentazioni Google. In questo modo puoi fornire all'utente informazioni pertinenti, automatizzare le attività e collegare sistemi di terze parti agli editor.

Accesso all'interfaccia utente del componente aggiuntivo

Puoi aprire un componente aggiuntivo di Google Workspace negli Editor se la sua icona viene visualizzata nel riquadro laterale di accesso rapido di Google Workspace sul lato destro delle interfacce utente di Documenti, Fogli e Presentazioni.

Un componente aggiuntivo di Google Workspace può presentare le seguenti interfacce:

  • Interfacce della home page: se il manifest del componente aggiuntivo include l'attivatore EDITOR_NAME.homepageTrigger per l'Editor in cui l'utente apre il componente aggiuntivo, il componente aggiuntivo crea e restituisce una scheda della home page specifica per l'Editor. Se il file manifest del componente aggiuntivo non include il valore EDITOR_NAME.homepageTrigger per l'editor in cui l'utente lo apre, viene mostrata una scheda home page generica.

  • Interfacce API REST: se il componente aggiuntivo utilizza API REST, puoi includere trigger che richiedono l'accesso a un documento per file utilizzando l'ambito drive.file. Una volta concesso, viene eseguito e visualizzato un altro trigger denominato EDITOR_NAME.onFileScopeGrantedTrigger.

  • Collega interfacce di anteprima: se il componente aggiuntivo si integra con un servizio di terze parti, puoi creare schede che mostrano l'anteprima dei contenuti dagli URL del servizio.

Creare interfacce per i componenti aggiuntivi di Editor

Passaggi per le interfacce aggiuntive dei componenti aggiuntivi dell'editor di build per gli editor:

  1. Aggiungi i campi addOns.common, addOns.docs, addOns.sheets e addOns.slides appropriati al file manifest del progetto di script per il componente aggiuntivo.
  2. Aggiungi eventuali ambiti Editor richiesti al manifest del progetto di script.
  3. Se fornisci una home page specifica di Editor, implementa la funzione EDITOR_NAME.homepageTrigger per creare l'interfaccia. In caso contrario, utilizza l'interfaccia common.homepageTrigger per creare una home page comune per le app host.
  4. Se utilizzi API REST, implementa il flusso di autorizzazione dell'ambito drive.file e attiva la funzione EDITOR_NAME.onFileScopeGrantedTrigger per visualizzare un'interfaccia specifica per il file aperto. Per ulteriori informazioni, consulta la sezione Interfacce dell'API REST.
  5. Se stai configurando le anteprime dei link da un servizio di terze parti, implementa il flusso di autorizzazione dell'ambito https://www.googleapis.com/auth/workspace.linkpreview e la funzione linkPreviewTriggers. Per ulteriori informazioni, consulta Interfacce di anteprima dei link.
  6. 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 degli editor

Devi fornire una funzione di trigger della home page nel progetto di script del componente aggiuntivo che crei e restituisca un singolo elemento Card o un array di oggetti Card che compongono la home page del componente aggiuntivo.

Alla funzione di attivazione della home page viene trasmesso un oggetto evento sotto forma di parametro contenente informazioni come la piattaforma del client. Puoi utilizzare i dati dell'oggetto evento per personalizzare la costruzione della home page.

Puoi presentare una home page comune o una home page specifica per l'Editor in cui l'utente apre il componente aggiuntivo.

Visualizza la home page comune

Per visualizzare la home page comune del componente aggiuntivo negli Editor, includi i campi dell'Editor appropriati, ad esempio addOns.docs, addOns.sheets o addOns.slides, nel file manifest del componente aggiuntivo.

L'esempio seguente mostra la parte addons di un manifest del componente aggiuntivo di Google Workspace. Il componente aggiuntivo estende Documenti, Fogli e Presentazioni e mostra la home page comune in ogni app host.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

Visualizzare una home page specifica di Editor

Per presentare una home page specifica per un editor, aggiungi EDITOR_NAME.homepageTrigger al manifest del componente aggiuntivo.

L'esempio seguente mostra la parte addons del manifest di un componente aggiuntivo di Google Workspace. Il componente aggiuntivo è abilitato per Documenti, Fogli e Presentazioni. Visualizza la home page comune in Documenti e Presentazioni e un'unica home page in Fogli. La funzione di callback onSheetsHomepage crea la scheda della home page specifica di Fogli.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

Interfacce API REST

Se il componente aggiuntivo utilizza API REST, come l'API Fogli Google, puoi utilizzare la funzione onFileScopeGrantedTrigger per visualizzare una nuova interfaccia specifica per il file aperto nell'app host Editor.

Per utilizzare la funzione onFileScopeGrantedTrigger, devi includere il flusso di autorizzazione dell'ambito drive.file. Per informazioni su come richiedere l'ambito drive.file, vedi Richiedere l'accesso ai file per il documento corrente.

Quando un utente concede l'ambito drive.file, viene attivato EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Quando si attiva, l'attivatore esegue la funzione di trigger contestuale specificata dal campo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction nel manifest del componente aggiuntivo.

Per creare un'interfaccia API REST per uno degli editor, segui i passaggi riportati di seguito. Sostituisci EDITOR_NAME con l'app host di Editor che scegli di utilizzare, ad esempio sheets.onFileScopeGrantedTrigger.

  1. Includi EDITOR_NAME.onFileScopeGrantedTrigger nell'apposita sezione del file manifest. Ad esempio, se vuoi creare questa interfaccia in Fogli Google, aggiungi il trigger alla sezione "sheets".
  2. Implementa la funzione denominata nella sezione EDITOR_NAME.onFileScopeGrantedTrigger. Questa funzione accetta un oggetto evento come argomento e deve restituire un singolo oggetto Card o una matrice di oggetti Card.
  3. Come con qualsiasi scheda, devi implementare le 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 viene fatto clic sul pulsante.

L'esempio seguente mostra la parte addons del manifest di un componente aggiuntivo di Google Workspace. Il componente aggiuntivo utilizza le API REST, quindi onFileScopeGrantedTrigger è incluso in Fogli Google. Quando un utente concede l'ambito drive.file, la funzione di callback onFileScopeGrantedSheets crea un'interfaccia specifica per il file.

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

Per attivare le anteprime dei link per un servizio di terze parti, devi configurare le anteprime dei link nel file manifest del tuo componente aggiuntivo e creare una funzione che restituisca una scheda di anteprima. Per i servizi che richiedono l'autorizzazione dell'utente, la funzione deve richiamare anche il flusso di autorizzazione.

Per conoscere la procedura per attivare le anteprime dei link, consulta Visualizzare l'anteprima dei link con smart chip.

Oggetti evento

Un oggetto evento viene creato e passato per attivare funzioni come EDITOR_NAME.homepageTrigger o EDITOR_NAME.onFileScopeGrantedTrigger. La funzione trigger utilizza le informazioni nell'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 un Editor è l'app di hosting del componente aggiuntivo, gli oggetti evento includono i campi degli oggetti evento di Documenti, Fogli o Presentazioni contenenti le informazioni del cliente.

Se il componente aggiuntivo non dispone dell'autorizzazione dell'ambito drive.file per l'utente o il documento corrente, l'oggetto evento contiene solo il campo docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission o slides.addonHasFileScopePermission. Se il componente aggiuntivo ha un'autorizzazione, l'oggetto evento contiene tutti i campi dell'oggetto evento Editor.

L'esempio seguente mostra un oggetto evento Editor passato a una funzione sheets.onFileScopeGrantedTrigger. Qui, il componente aggiuntivo ha l'autorizzazione dell'ambito drive.file per il documento corrente:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }