Websites

Startseiten sind eine neue Google Workspace-Add-on-Funktion, mit der Sie eine oder mehrere nicht kontextbezogene Karten definieren können. Nicht kontextbezogene Karten werden verwendet, um eine Benutzeroberfläche anzuzeigen, wenn sich der Nutzer nicht in einem bestimmten Kontext befindet, z. B. wenn er seinen Gmail-Posteingang aufruft, aber keine Nachricht oder keinen Entwurf geöffnet hat.

Auf Startseiten können Sie nicht kontextbezogene Inhalte anzeigen, genau wie die Google-Apps in der Seitenleiste für den Schnellzugriff (Google Notizen, Google Kalender und Google Tasks). Startseiten können auch ein Ausgangspunkt sein, wenn Nutzer Ihr Add-on zum ersten Mal öffnen. Außerdem sind sie nützlich, um neuen Nutzern zu zeigen, wie sie mit Ihrem Add-on interagieren können.

Sie können eine Startseite für Ihr Add-on definieren, indem Sie sie in Ihrem Projektmanifest angeben und eine oder mehrere homepageTrigger-Funktionen implementieren (siehe Startseitenkonfiguration).

Sie können mehrere Startseiten haben, eine für jede Hostanwendung, die Ihr Add-on erweitert. Sie können auch eine gemeinsame Standardstartseite definieren, die auf Hosts verwendet wird, für die Sie keine benutzerdefinierte Startseite angegeben haben.

Die Startseite Ihres Add-ons wird angezeigt, wenn eine der folgenden Bedingungen erfüllt ist:

  • Wenn das Add-on zum ersten Mal im Host geöffnet wird (nach der Autorisierung).
  • Wenn der Nutzer während des geöffneten Add-ons von einem kontextbezogenen zu einem nicht kontextbezogenen Kontext wechselt. Beispielsweise von der Bearbeitung eines Kalendertermins zum Hauptkalender.
  • Wenn der Nutzer so oft auf die Schaltfläche „Zurück“ klickt, dass jede zweite Karte aus den internen Stapeln herausspringt.
  • Wenn eine UI-Interaktion auf einer nicht kontextbezogenen Karte zu einem Navigation.popToRoot()-Aufruf führt.

Das Entwerfen einer Startseite ist nicht obligatorisch, wird aber dringend empfohlen. Wenn Sie keine Startseite definieren, wird eine generische Karte mit dem Namen Ihres Add-ons verwendet, wenn ein Nutzer andernfalls zur Startseite weitergeleitet würde.

Startseitenkonfiguration

In Google Workspace-Add-ons wird das Feld addOns.common.homepageTrigger verwendet, um die Standardstartseite (nicht kontextbezogenen) Add-on-Inhalte für alle Hostanwendungen im Manifest des Add-ons zu konfigurieren:

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

  • runFunction: Der Name der Apps Script-Funktion, die vom Google Workspace-Add-on-Framework aufgerufen wird, um Add-on-Karten auf der Startseite zu rendern. Diese Funktion ist die Startseiten-Triggerfunktion. Diese Funktion muss ein Array von Card-Objekten erstellen und zurückgeben, die die Benutzeroberfläche der Startseite bilden. Wenn mehrere Karten zurückgegeben werden, zeigt die Hostanwendung die Kartenüberschriften in einer Liste an, aus der der Nutzer auswählen kann (siehe Mehrere Karten zurückgeben).

  • enabled: Ob Startseitenkarten für diesen Umfang aktiviert werden sollen. Dieses Feld ist optional und hat standardmäßig den Wert true. Wenn Sie diese Option auf false festlegen, werden Startseitenkarten für alle Hosts deaktiviert, sofern sie nicht für diesen Host überschrieben werden (siehe unten).

Zusätzlich zur gemeinsamen Konfiguration gibt es in der Konfiguration jeder Hostanwendung unter addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger usw. identisch strukturierte per-Host-Überschreibungen:

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

Dies entspricht dem folgenden Manifestausschnitt:

    {
      ...
      "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": { /* ... */ },
        ...
      }
    }

Keiner der homepageTrigger-Abschnitte ist erforderlich. Die für ein Add-on in einem bestimmten Hostprodukt angezeigte Benutzeroberfläche hängt jedoch davon ab, ob das entsprechende Manifest-Feld vorhanden ist und ob eine zugehörige homepageTrigger vorhanden ist. Im folgenden Beispiel wird gezeigt, welche Add-on-Triggerfunktionen (falls vorhanden) ausgeführt werden, um eine Startseiten-Benutzeroberfläche für verschiedene Manifestkonfigurationen zu erstellen:

Startseitenfluss

Ereignisobjekte auf der Startseite

Wenn die oben beschriebene Triggerfunktion für die Startseite (runFunction) aufgerufen wird, wird ihr ein Ereignisobjekt mit Daten aus dem Aufrufkontext übergeben.

Ereignisobjekte für die Startseite enthalten keine Widget- oder Kontextinformationen. Die übergebenen Informationen sind auf die folgenden Felder von gemeinsamen Ereignisobjekten beschränkt:

Weitere Informationen finden Sie unter Ereignisobjekt.

Andere nicht kontextbezogene Karten

Die Benutzeroberfläche Ihres Add-ons kann zusätzliche nicht kontextbezogene Karten enthalten, die keine Startseiten sind. Auf Ihrer Startseite kann beispielsweise eine Schaltfläche vorhanden sein, über die eine Karte „Einstellungen“ geöffnet wird, in der Nutzer die Add-on-Einstellungen anpassen können. Solche Einstellungen sind in den meisten Fällen kontextunabhängig und daher nicht kontextbezogen.

Nicht kontextbezogene Karten werden wie jede andere Karte erstellt. Der einzige Unterschied besteht darin, durch welche Aktion oder welches Ereignis die Karte generiert und angezeigt wird. Weitere Informationen zum Erstellen von Übergängen zwischen Karten finden Sie unter Navigationsmethoden.