Google Drive-Oberflächen erstellen

Google Workspace-Add-ons können benutzerdefinierte Benutzeroberflächen bereitstellen, wenn der Nutzer Google Drive verwendet. So können Sie Nutzern zusätzliche relevante Informationen zur Verfügung stellen, Aufgaben automatisieren und Systeme von Drittanbietern mit Google Drive verbinden.

Auf die Add-on-Benutzeroberfläche zugreifen

Sie können ein Google Workspace-Add-on in Google Drive öffnen, wenn das Symbol in der Symbolspalte rechts in der Drive-Benutzeroberfläche angezeigt wird. Ein Google Workspace-Add-on kann eine Startseitenoberfläche, eine Oberfläche für die Artikelauswahl oder beides definieren:

  • Wenn ein Nutzer in Google Drive auf das Add-on-Symbol klickt, führt das Add-on die entsprechende drive.homepageTrigger-Funktion aus (falls vorhanden). Diese Funktion erstellt eine Infokarte auf der Startseite und gibt sie zur Anzeige in Google Drive zurück. Wenn keine drive.homepageTrigger-Funktion definiert ist, wird stattdessen eine generische Startseitenkarte angezeigt.
  • Wenn der Nutzer ein oder mehrere Elemente in Google Drive auswählt und dann auf das Add-on-Symbol klickt oder Elemente auswählt, während das Add-on geöffnet ist, führt das Add-on die entsprechende drive.onItemsSelectedTrigger-Kontextfunktion aus (falls vorhanden). Mit dieser Funktion wird die kontextbezogene Benutzeroberfläche „Auswahl“ des Add-ons in Google Drive erstellt und zur Anzeige an Google Drive zurückgegeben.

Drive-Oberfläche für das Add-on erstellen

So erstellen Sie Oberflächen, die Google Drive erweitern:

  1. Legen Sie fest, ob Ihr Add-on eine Drive-spezifische Startseite haben soll. Legen Sie auch fest, ob Sie eine kontextbezogene Benutzeroberfläche für den Fall bereitstellen möchten, dass der Nutzer Drive-Elemente auswählt.
  2. Fügen Sie dem Manifest des Add-on-Scripts die entsprechenden Felder addOns.common und addOns.drive hinzu, einschließlich aller erforderlichen Drive-Bereiche.
  3. Wenn Sie eine Drive-spezifische Startseite bereitstellen, implementieren Sie die Funktion drive.homepageTrigger, um diese Benutzeroberfläche zu erstellen. Sie können die Benutzeroberfläche common.homepageTrigger auch für mehrere Google Workspace-Hosts verwenden.
  4. Wenn Sie eine Benutzeroberfläche für die kontextbezogene Artikelauswahl in Google Drive bereitstellen, müssen Sie eine drive.onItemsSelectedTrigger-Kontexttriggerfunktion implementieren, um diese Benutzeroberfläche zu erstellen. Weitere Informationen finden Sie unter Kontextbezogene Drive-Benutzeroberfläche für ausgewählte Elemente.
  5. Implementieren Sie die zugehörigen Callback-Funktionen, die erforderlich sind, um auf die UI-Interaktionen des Nutzers zu reagieren, z. B. auf Klicks auf Schaltflächen.

Drive-Startseiten

In Google Drive können Startseiten von Google Workspace-Add-ons angezeigt werden. Damit die Startseite Ihres Add-ons in Google Drive angezeigt wird, muss im Manifest des Add-ons das Feld addOns.drive vorhanden sein.

Alternativ können Sie dem Add-on-Manifest ein drive.homepageTrigger hinzufügen, um eine Drive-spezifische Startseite bereitzustellen.

In beiden Fällen müssen Sie den Namen einer Startseiten-Triggerfunktion im Scriptprojekt Ihres Add-ons angeben. Diese Funktion wird automatisch aufgerufen, um die Google Drive-Startseite bei Bedarf zu erstellen. Sie müssen diese Funktion implementieren, um ein einzelnes Card-Objekt oder ein Array von Card-Objekten zu erstellen und zurückzugeben, die die Startseite bilden. Der Triggerfunktion für die Startseite wird als Parameter ein Ereignisobjekt übergeben, das allgemeine Informationen wie die Plattform des Clients enthält. Mit den Daten des Ereignisobjekts können Sie die Erstellung der Startseite anpassen.

Kontextbezogene Drive-Benutzeroberfläche für ausgewählte Elemente

In Google Drive wird anhand eines kontextbezogenen Auslösers festgelegt, welche Benutzeroberfläche angezeigt wird, wenn der Nutzer ein oder mehrere Google Drive-Elemente auswählt. Wenn der Trigger ausgelöst wird, wird die Kontexttriggerfunktion ausgeführt, die im Feld drive.onItemsSelectedTrigger.runFunction im Manifest des Add-ons angegeben ist.

So erstellen Sie eine kontextbezogene Benutzeroberfläche für die Elementauswahl in Google Drive:

  1. Achten Sie darauf, dass das Manifest des Add-ons den Bereich https://www.googleapis.com/auth/drive.addons.metadata.readonly scope enthält.

  2. Das Manifest muss den Abschnitt drive.onItemsSelectedTrigger enthalten.

  3. Implementieren Sie die Funktion, die im Feld drive.onItemsSelectedTrigger angegeben ist. Diese Funktion akzeptiert ein Ereignisobjekt als Argument und muss entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurückgeben.

  4. Wie bei jeder Karte müssen Sie alle Callback-Funktionen implementieren, die für die Interaktivität des Widgets auf der Benutzeroberfläche verwendet werden. Wenn Sie beispielsweise eine Schaltfläche in die Benutzeroberfläche einfügen, sollte sie eine verknüpfte Aktion und eine implementierte Callback-Funktion haben, die ausgeführt wird, wenn auf die Schaltfläche geklickt wird.

Ereignisobjekte

Ein Ereignisobjekt wird erstellt und an die Triggerfunktion drive.homepageTrigger oder drive.onItemsSelectedTrigger übergeben, wenn diese Funktionen aufgerufen werden. Die Triggerfunktion kann die Informationen in diesem Ereignisobjekt verwenden, um zu bestimmen, wie Add-on-Karten erstellt oder das Add-on-Verhalten anderweitig gesteuert werden soll.

Die vollständige Struktur von Ereignisobjekten wird unter Ereignisobjekte beschrieben. Wenn Drive die aktive Host-App des Add-ons ist, enthalten kontextbezogene Ereignisobjekte das Feld Drive-Ereignisobjekt, das Drive-spezifische Kundeninformationen enthält.

Kontextbezogene Drive-Ereignisobjekte für Trigger für die Artikelauswahl enthalten Informationen zu den Elementen, die der Nutzer ausgewählt hat, als der Trigger ausgelöst wurde. Wenn ein Nutzer mehrere Elemente in Drive auswählt, wird eines davon als das Element mit dem Hauptinteresse angesehen. Dieses Element wird als aktives Cursorelement bezeichnet.

Das folgende Beispiel zeigt ein Drive-Ereignisobjekt, das an eine drive.onItemsSelectedTrigger-Funktion übergeben wird:

    {
      "commonEventObject": { ... },
      "drive": {
        "activeCursorItem":{
          "addonHasFileScopePermission": true,
          "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
          "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
          "mimeType":"application/pdf",
          "title":"How to get started with Drive"
        },
        "selectedItems": [
          {
            "addonHasFileScopePermission": true,
            "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
            "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
            "mimeType":"application/pdf",
            "title":"How to get started with Drive"
          },
          ...
        ]
      },
      ...
    }