Home page

Le home page sono una nuova funzionalità dei componenti aggiuntivi di Google Workspace che consente di definire una o più schede non contestuali. Le schede non contestuali vengono utilizzate per mostrare un'interfaccia utente quando l'utente si trova al di fuori di un contesto specifico, ad esempio quando visualizza la posta in arrivo di Gmail ma non ha aperto un messaggio o una bozza.

Le home page ti consentono di mostrare contenuti non contestuali, proprio come le app Google nel riquadro laterale ad accesso rapido (Keep, Calendar e Tasks). Le home page possono anche fornire un punto di partenza iniziale per la prima apertura del componente aggiuntivo da parte degli utenti e sono utili per insegnare ai nuovi utenti come interagire con il componente aggiuntivo.

Puoi definire una home page per il tuo componente aggiuntivo specificandola nel file manifest del progetto e implementando una o più funzioni homepageTrigger (consulta la sezione sulla configurazione della home page).

Puoi avere più home page, una per ogni applicazione host estesa dal tuo componente aggiuntivo. Puoi anche decidere di definire una singola home page predefinita comune da utilizzare negli host per cui non hai specificato una home page personalizzata.

La home page del componente aggiuntivo viene visualizzata quando si verifica una delle seguenti condizioni:

  • Quando il componente aggiuntivo viene aperto per la prima volta nell'host (dopo l'autorizzazione).
  • Quando l'utente passa da un contesto contestuale a uno non contestuale mentre il componente aggiuntivo è aperto. ad esempio dalla modifica di un evento nel calendario al calendario principale.
  • Quando l'utente fa clic sul pulsante Indietro abbastanza volte da separare tutte le schede dagli stack interni.
  • Quando un'interazione con l'interfaccia utente in una scheda non contestuale genera una chiamata a Navigation.popToRoot().

La progettazione di una home page non è obbligatoria, ma vivamente consigliata; se non la definisci, viene utilizzata una scheda generica contenente il nome del tuo componente aggiuntivo ogni volta che un utente visita la home page.

Configurazione della home page

I componenti aggiuntivi di Google Workspace utilizzano il campo addOns.common.homepageTrigger per configurare i contenuti aggiuntivi predefiniti della home page (non contestuali) per tutte le applicazioni host nel manifest del componente aggiuntivo:

    {
      // ...
      "addOns": {
        // ...
        "common": {
          // ...
          "homepageTrigger": {
            "runFunction": "myFunction",
            "enabled": true
          }
        }
      }
    }

  • runFunction: il nome della funzione Apps Script richiamata dal framework dei componenti aggiuntivi di Google Workspace per visualizzare le schede dei componenti aggiuntivi della home page. Questa funzione è la funzione di attivazione della home page. Questa funzione deve creare e restituire un array di oggetti Card che compongono l'interfaccia utente della home page. Se vengono restituite più schede, l'applicazione host mostra le intestazioni delle schede in un elenco dal quale l'utente può selezionare (consulta la sezione Restituzione di più schede).

  • enabled: indica se le schede della home page devono essere attivate per questo ambito. Questo campo è facoltativo e il valore predefinito è true. Se viene impostata su false, le schede della home page vengono disattivate per tutti gli host (a meno che non vengano sostituite per l'host; vedi di seguito).

Oltre alla configurazione comune, sono disponibili anche override per host con struttura identica nella configurazione di ogni applicazione host, in addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger e così via:

    {
      ...
      "addOns": {
        ...
        "common": {
          // By default, call 'buildHomePage' to render homepage content
          // in all hosts. Since calendar.homepageTrigger below overrides
          // this in Calendar and Drive and the homepageTrigger is disabled
          // for Gmail, this homepage function never executes.
          "homepageTrigger": { "runFunction": "buildHomePage" }
        },
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "buildDriveHomepage" }
        }
        "gmail": {
          // Disable homepage add-on content in Gmail.
          "homepageTrigger": { "enabled": false }
        },
        ...
      }
    }

Tieni presente che ciò equivale al seguente estratto del file manifest:

    {
      ...
      "addOns": {
        ...
        "common": { /* ... */ }, // Omitted a default homepageTrigger specification.
        "calendar": {
          // Show customized homepage content for Calendar only.
          "homepageTrigger": { "runFunction": "myCalendarFunction" }
        },
        "drive": {
          // Show customized homepage content for Drive only.
          "homepageTrigger": { "runFunction": "myDriveFunction" }
        }
        "gmail": { /* ... */ },
        ...
      }
    }

Nessuna delle sezioni homepageTrigger è obbligatoria. Tuttavia, la UI mostrata per un componente aggiuntivo in un determinato prodotto host dipende dalla presenza del campo manifest corrispondente e dalla presenza di un homepageTrigger associato. L'esempio seguente mostra quali funzioni trigger dei componenti aggiuntivi vengono eseguite (se presenti) per creare un'UI della home page per diverse configurazioni dei manifest:

Flusso della home page

Oggetti evento della home page

Quando viene chiamata, alla funzione di trigger della home page (runFunction) descritta sopra viene passato un oggetto evento contenente dati del contesto di chiamata.

Gli oggetti evento della home page non includono widget o informazioni contestuali; le informazioni trasmesse sono limitate ai seguenti campi di oggetto evento comune:

Per ulteriori dettagli, consulta Oggetto evento.

Altre schede non contestuali

L'interfaccia utente dei componenti aggiuntivi può contenere schede aggiuntive non contestuali che non sono home page. Ad esempio, la tua home page potrebbe avere un pulsante che apre una scheda "Impostazioni" in cui l'utente può modificare le impostazioni dei componenti aggiuntivi (nella maggior parte dei casi queste impostazioni sarebbero indipendenti dal contesto e quindi non contestuali).

Le schede non contestuali sono create come qualsiasi altra scheda; l'unica differenza è l'azione o l'evento che genera e mostra la scheda. Consulta Metodi di navigazione per informazioni dettagliate su come creare transizioni tra le schede.