Con i componenti aggiuntivi di Google Workspace, puoi fornire interfacce personalizzate all'interno degli editor, tra cui Documenti, Fogli e Presentazioni Google. Questo ti consente di fornire all'utente informazioni pertinenti, automatizzare le attività e collegare sistemi di terze parti Editor
Accesso all'interfaccia utente del componente aggiuntivo
Puoi aprire un componente aggiuntivo di Google Workspace negli editor se la relativa icona appare nella finestra rapida di Google Workspace riquadro laterale di accesso sul lato destro dell'utente di Documenti, Fogli e Presentazioni interfacce.
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 esegue le build e restituisce un scheda home page specifica per l'editor. Se il file manifest del componente aggiuntivo non includeEDITOR_NAME.homepageTrigger
per l'editor che l'utente apre viene visualizzata una scheda generica della home page.Interfacce dell'API REST: se il componente aggiuntivo utilizza REST API, puoi includere trigger che richiedono l'accesso a un documento per ogni file utilizzando l'ambito
drive.file
. Una volta concesso, un altro triggerEDITOR_NAME.onFileScopeGrantedTrigger
esegue e visualizza un'interfaccia specifica per il file.Interfacce di anteprima dei link: se il componente aggiuntivo si integra con un servizio di terze parti, puoi creare schede che contenuti dagli URL del tuo servizio.
Creazione di interfacce per componenti aggiuntivi Editor
Crea interfacce del componente aggiuntivo Editor di build per gli editor seguendo questa procedura:
- Aggiungi il token appropriato
addOns.common
,addOns.docs
,addOns.sheets
, eaddOns.slides
al progetto di script del componente aggiuntivo manifest. - Aggiungi eventuali ambiti Editor obbligatori a del file manifest del tuo progetto di script.
- Se fornisci una home page specifica dell'Editor,
di implementare
EDITOR_NAME.homepageTrigger
: per creare l'interfaccia. In caso contrario, utilizzacommon.homepageTrigger
per creare una home page comune per le app host. - Se utilizzi le API REST, implementa il flusso di autorizzazione dell'ambito
drive.file
eEDITOR_NAME.onFileScopeGrantedTrigger
attiva la funzione 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
linkPreviewTriggers
personalizzata. Per ulteriori informazioni, vedi Interfacce di anteprima dei link. - Implementare le funzioni di callback associate necessarie per rispondere alla richiesta Interazioni con l'interfaccia utente, come 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 crea e restituisce un singolo elemento Card
oppure un array di Card
oggetti che compongono la home page del componente aggiuntivo.
Alla funzione trigger della home page viene trasmesso un oggetto evento. come parametro contenente informazioni come la piattaforma del cliente. Puoi Utilizzare i dati dell'oggetto evento per personalizzare la costruzione della home page.
Puoi presentare una home page comune o specifica dell'Editor l'utente apre il tuo componente aggiuntivo.
Visualizza la home page comune
Per visualizzare la home page comune del componente aggiuntivo negli editor, includi i dettagli
Campi dell'editor, ad esempio addOns.docs
,
addOns.sheets
,
o addOns.slides
,
nel file manifest del componente aggiuntivo.
L'esempio seguente mostra la parte addons
di un componente aggiuntivo di Google Workspace
del file manifest. Il componente aggiuntivo estende Documenti, Fogli e Presentazioni e mostra le
nella home page di 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": {} } }
Visualizza una home page specifica di Editor
Per presentare una home page specifica a un editor, aggiungi EDITOR_NAME.homepageTrigger
al componente aggiuntivo
del file manifest.
L'esempio seguente mostra la parte addons
di un manifest del componente aggiuntivo di Google Workspace.
Il componente aggiuntivo è attivato per Documenti, Fogli e Presentazioni. Mostra le caratteristiche comuni
la home page in Documenti e Presentazioni e una home page unica in Fogli. Il callback
La funzione onSheetsHomepage
crea la scheda della home page specifica per 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, ad esempio l'API Fogli Google,
puoi usare la funzione onFileScopeGrantedTrigger
per visualizzare una nuova interfaccia
specifico per il file aperto nell'app host dell'Editor.
Per utilizzare la funzionalità, devi includere il flusso di autorizzazione dell'ambito drive.file
Funzione onFileScopeGrantedTrigger
. Per scoprire come richiedere l'autorizzazione drive.file
consulta l'articolo Richiedere l'accesso ai file per il documento corrente.
Quando un utente concede l'ambito drive.file
, la classe
EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
incendi. Quando l'attivatore si attiva, esegue la funzione di attivazione contestuale
specificato dal campo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
nel
del componente aggiuntivo.
Per creare un'interfaccia API REST per uno degli editor, segui questi passaggi.
Sostituisci EDITOR_NAME
con l'app host che hai scelto per l'Editor
utilizzare, ad esempio sheets.onFileScopeGrantedTrigger
.
- Includi
EDITOR_NAME.onFileScopeGrantedTrigger
nella sezione dell'Editor appropriata del tuo manifest. Ad esempio, se vuoi creare questa interfaccia in Fogli Google, aggiungi l'attivatore sezione"sheets"
. - Implementa la funzione denominata nel
EDITOR_NAME.onFileScopeGrantedTrigger
. Questa funzione accetta un oggetto evento come argomento e deve restituire un singoloCard
: o un array diCard
oggetti. - 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, questo deve avere un'azione Action e una funzione di callback implementata che viene eseguita quando il pulsante viene fatto clic su di te.
L'esempio seguente mostra la parte addons
di un manifest del componente aggiuntivo di Google Workspace.
Il componente aggiuntivo utilizza le API REST, quindi onFileScopeGrantedTrigger
è incluso per
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" } }
Interfacce di anteprima dei link per servizi di terze parti
Per attivare le anteprime dei link per un servizio di terze parti, devi configurare il link visualizza l'anteprima nel manifest del componente aggiuntivo e crea una funzione che restituisca un'anteprima . Per i servizi che richiedono l'autorizzazione dell'utente, la funzione deve richiamare anche nel 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 nella
per determinare come costruire schede aggiuntive o controllare in altro modo
il comportamento del componente aggiuntivo.
La struttura completa degli oggetti evento è descritta in Oggetti evento.
Se un editor è l'app ospitante del componente aggiuntivo, gli oggetti evento includono Documenti, Fogli o Presentazioni campi dell'oggetto evento che contengono informazioni sul client.
Se il componente aggiuntivo non dispone dell'autorizzazione di ambito di drive.file
per l'utente corrente
o documento, l'oggetto evento contiene solo
docs.addonHasFileScopePermission
, sheets.addonHasFileScopePermission
o
slides.addonHasFileScopePermission
. Se il componente aggiuntivo ha
, l'oggetto evento contiene tutti i campi dell'oggetto evento Editor.
L'esempio seguente mostra un oggetto evento Editor che viene passato a un
Funzione sheets.onFileScopeGrantedTrigger
. Qui il componente aggiuntivo ha
Autorizzazione dell'ambito drive.file
per il documento corrente:
` { "commonEventObject": { ... }, "sheets": { "addonHasFileScopePermission": true, "id":"A_24Q3CDA23112312ED52", "title":"How to get started with Sheets" }, ... }