Creazione delle interfacce di Google Editor

Con i componenti aggiuntivi di Google Workspace, puoi fornire interfacce personalizzate all'interno degli editor, inclusi Documenti, Fogli e Presentazioni di 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 in Editor se la relativa 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 file manifest del componente aggiuntivo include l'attivatore EDITOR_NAME.homepageTrigger per l'editor in cui l'utente apre il componente aggiuntivo, il componente aggiuntivo genera e restituisce una scheda della home page specifica per l'editor in questione. Se il file manifest del componente aggiuntivo non include EDITOR_NAME.homepageTrigger per l'editor in cui l'utente lo apre, viene visualizzata una scheda della 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 un altro trigger chiamato EDITOR_NAME.onFileScopeGrantedTrigger e viene visualizzata un'interfaccia specifica per il file.

  • Interfacce di anteprima dei link: se il tuo componente aggiuntivo è integrato con un servizio di terze parti, puoi creare schede che mostrano l'anteprima dei contenuti degli URL del tuo servizio.

Creazione di interfacce per i componenti aggiuntivi dell'editor

Per creare interfacce dei componenti aggiuntivi di Editor per gli editor:

  1. Aggiungi i campi appropriati addOns.common, addOns.docs, addOns.sheets, e addOns.slides al manifest del progetto dello script del componente aggiuntivo.
  2. Aggiungi eventuali ambiti editor richiesti al manifest del progetto di script.
  3. Se fornisci una home page specifica per l'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 tue app host.
  4. Se utilizzi API REST, implementa il drive.file flusso di autorizzazione dell'ambito e la funzione di trigger EDITOR_NAME.onFileScopeGrantedTrigger per visualizzare un'interfaccia specifica per il file aperto. Per ulteriori informazioni, consulta la sezione Interfacce 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 la sezione 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 dell'editor

Devi fornire una funzione di attivazione della home page nel progetto dello script del componente aggiuntivo che genera e restituisce un singolo Card o un array di oggetti Card che costituiscono la home page del componente aggiuntivo.

Alla funzione di attivazione della home page viene passato un oggetto evento come parametro che contiene informazioni come la piattaforma del cliente. Puoi utilizzare i dati dell'oggetto evento per personalizzare la creazione della home page.

Puoi presentare una home page comune o una specifica per l'editor con cui l'utente apre il tuo componente aggiuntivo.

Mostrare la home page comune

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

L'esempio seguente mostra la parte addons del manifest di un 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": {}
  }
}

Mostrare una home page specifica per l'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 è attivato per Documenti, Fogli e Presentazioni. Mostra la home page comune in Documenti e Presentazioni e una home page univoca in Fogli. La funzione callback onSheetsHomepage genera 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 tuo componente aggiuntivo utilizza API REST, ad esempio l'API Google Sheets, puoi utilizzare la funzione onFileScopeGrantedTrigger per visualizzare una nuova interfaccia specifica per il file aperto nell'app host di Editor.

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

Quando un utente concede l'ambito drive.file, viene attivato EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Quando viene attivato, l'attivatore esegue la funzione di attivazione 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 nella sezione Editor appropriata del manifest. Ad esempio, se vuoi creare questa interfaccia in Fogli Google, aggiungi l'attivatore 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 un array di oggetti Card.
  3. Come per qualsiasi scheda, devi implementare le funzioni di callback utilizzate per fornire l'interattività dei 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.

L'esempio seguente mostra la parte addons del manifest di un componente aggiuntivo di Google Workspace. Il componente aggiuntivo utilizza API REST, pertanto onFileScopeGrantedTrigger è incluso per Fogli Google. Quando un utente concede l'ambito drive.file, la funzione di callbackonFileScopeGrantedSheets 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 configurarle nel file manifest del componente aggiuntivo e creare una funzione che restituisca una scheda di anteprima. Per i servizi che richiedono l'autorizzazione utente, la funzione deve anche invocare il flusso di autorizzazione.

Per scoprire come attivare le anteprime dei link, consulta Visualizzare l'anteprima dei link con gli smart chip.

Eventi

Viene creato un oggetto evento e passato alle funzioni di trigger, come EDITOR_NAME.homepageTrigger o EDITOR_NAME.onFileScopeGrantedTrigger. La funzione di attivazione utilizza le informazioni nell'oggetto evento per determinare come creare le schede dei componenti aggiuntivi o per controllare in altro modo il loro comportamento.

La struttura completa degli oggetti evento è descritta in Oggetti evento.

Quando un editor è l'app host in esecuzione del componente aggiuntivo, gli oggetti evento includono i campi degli oggetti evento Documenti, Fogli o Presentazioni che contengono le informazioni del client.

Se il componente aggiuntivo non dispone dell'autorizzazione di 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 l'autorizzazione, l'oggetto evento contiene tutti i campi dell'oggetto evento di Editor.

L'esempio seguente mostra un oggetto evento Editor passato a una funzione sheets.onFileScopeGrantedTrigger. In questo caso, il componente aggiuntivo dispone dell'autorizzazione di ambito drive.file per il documento corrente:

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