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 valoreEDITOR_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 denominatoEDITOR_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:
- Aggiungi i campi
addOns.common
,addOns.docs
,addOns.sheets
eaddOns.slides
appropriati al file manifest del progetto di script per il componente aggiuntivo. - Aggiungi eventuali ambiti Editor richiesti al manifest del progetto di script.
- Se fornisci una home page specifica di Editor, implementa la funzione
EDITOR_NAME.homepageTrigger
per creare l'interfaccia. In caso contrario, utilizza l'interfacciacommon.homepageTrigger
per creare una home page comune per le app host. - Se utilizzi API REST, implementa il flusso di autorizzazione dell'ambito
drive.file
e attiva la funzioneEDITOR_NAME.onFileScopeGrantedTrigger
per visualizzare un'interfaccia specifica per il file aperto. Per ulteriori informazioni, consulta la sezione Interfacce dell'API REST. - 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 funzionelinkPreviewTriggers
. Per ulteriori informazioni, consulta Interfacce di anteprima dei link. - 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
.
- 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"
. - Implementa la funzione denominata nella sezione
EDITOR_NAME.onFileScopeGrantedTrigger
. Questa funzione accetta un oggetto evento come argomento e deve restituire un singolo oggettoCard
o una matrice di oggettiCard
. - 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" } }
Collega le interfacce di anteprima per i servizi di terze parti
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" }, ... }