Creazione delle interfacce di Google Editor

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

Accedere all'interfaccia utente del componente aggiuntivo

Puoi aprire un componente aggiuntivo di Google Workspace negli editor se la sua icona viene visualizzata nel riquadro 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 il trigger EDITOR_NAME.homepageTrigger per l'editor in cui l'utente apre il componente aggiuntivo, quest'ultimo crea e restituisce una scheda della home page specifica per l'editor. Se il 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 per file a un documento 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 si integra con un servizio di terze parti, puoi creare schede che visualizzano in anteprima i contenuti degli URL del servizio.

Creazione di interfacce per i componenti aggiuntivi dell'editor

Crea interfacce dei componenti aggiuntivi dell'editor per gli editor seguendo questi passaggi:

  1. Aggiungi i campi addOns.common, addOns.docs, addOns.sheets, e addOns.slides al manifest del progetto di script del componente aggiuntivo.
  2. Aggiungi eventuali ambiti di 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 app host.
  4. Se utilizzi le API REST, implementa il flusso di autorizzazione dell'ambito drive.file e la funzione di trigger EDITOR_NAME.onFileScopeGrantedTrigger per visualizzare un'interfaccia specifica per il file aperto. Per ulteriori informazioni, consulta Interfacce API REST.
  5. Se configuri 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 attivazione della home page nel progetto di script del componente aggiuntivo che crea e restituisce un singolo Card o un array di oggetti Card che compongono 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 client. Puoi utilizzare i dati dell'oggetto evento per personalizzare la creazione 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.

Visualizzare la home page comune

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

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

Visualizzare una home page specifica per l'editor

Per presentare una home page specifica per un editor, aggiungi EDITOR_NAME.homepageTrigger al manifest dell'add-on.

L'esempio seguente mostra la parte addons di un 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 unica in Fogli. La funzione di callback 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 tuo componente aggiuntivo utilizza API REST, come l'API Google Sheets, 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 scoprire 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 viene attivato il trigger, viene eseguita la funzione di trigger contestuale specificata dal campo EDITOR_NAME.onFileScopeGrantedTrigger.runFunction nel manifest dell'addon.

Per creare un'interfaccia API REST per uno degli editor, segui i passaggi riportati di seguito. Sostituisci EDITOR_NAME con l'app host dell'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 carta, 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 allegata e una funzione di callback implementata che viene eseguita quando viene fatto clic sul pulsante.

L'esempio seguente mostra la parte addons di un manifest di un componente aggiuntivo di Google Workspace. Il componente aggiuntivo utilizza le API REST, quindi onFileScopeGrantedTrigger è incluso per 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 manifest del componente aggiuntivo e creare una funzione che restituisca una scheda di anteprima. Per i servizi che richiedono l'autorizzazione dell'utente, la funzione deve anche richiamare il flusso di autorizzazione.

Per i passaggi per attivare le anteprime dei link, consulta Visualizzare l'anteprima del link con smart chip.

Oggetti evento

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

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

Quando un editor è l'app host dell'add-on, gli oggetti evento includono campi dell'oggetto evento Documenti, Fogli o Presentazioni che contengono informazioni sul client.

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 dispone dell'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 dell'ambito drive.file per il documento corrente:

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