Creazione delle interfacce di Google Editor

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 include EDITOR_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 trigger EDITOR_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:

  1. Aggiungi il token appropriato addOns.common, addOns.docs, addOns.sheets, e addOns.slides al progetto di script del componente aggiuntivo manifest.
  2. Aggiungi eventuali ambiti Editor obbligatori a del file manifest del tuo progetto di script.
  3. Se fornisci una home page specifica dell'Editor, di implementare EDITOR_NAME.homepageTrigger: per creare l'interfaccia. In caso contrario, utilizza common.homepageTrigger per creare una home page comune per le app host.
  4. Se utilizzi le API REST, implementa il flusso di autorizzazione dell'ambito drive.file e EDITOR_NAME.onFileScopeGrantedTrigger di trigger 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 linkPreviewTriggers personalizzata. Per ulteriori informazioni, vedi Interfacce di anteprima dei link.
  6. 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.

  1. 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".
  2. Implementa la funzione denominata nel EDITOR_NAME.onFileScopeGrantedTrigger . Questa funzione accetta un oggetto evento come argomento e deve restituire un singolo Card: o un array di Card oggetti.
  3. 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"
     }
   }

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"
          },
          ...
        }