Google Drive-Oberflächen erstellen

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

Auf die Add-on-Benutzeroberfläche zugreifen

Sie können ein Google Workspace-Add-on in Google Drive öffnen, wenn sein Symbol in der Symbolspalte auf der rechten Seite der Drive-Benutzeroberfläche angezeigt wird. Ein Google Workspace-Add-on kann eine Startseite, eine Schnittstelle zur Auswahl von Elementen oder beides definieren:

  • Wenn ein Nutzer in Google Drive auf das Add-on-Symbol klickt, wird die entsprechende drive.homepageTrigger-Funktion (falls vorhanden) ausgeführt. Diese Funktion erstellt und gibt eine Infokarte für die Startseite für die 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 kontextbezogene Funktion drive.onItemsSelectedTrigger (falls vorhanden) aus. Diese Funktion erstellt die kontextbezogene Benutzeroberfläche „Ausgewählte Elemente“ des Add-ons in Google Drive und gibt sie zur Anzeige an Google Drive zurück.

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

Sie können Schnittstellen erstellen, die Google Drive erweitern, indem Sie die folgenden allgemeinen Schritte ausführen:

  1. Entscheiden Sie, ob Ihr Add-on eine Drive-spezifische Startseite haben soll. Entscheiden Sie auch, ob Sie eine kontextbezogene Benutzeroberfläche bereitstellen möchten, wenn der Nutzer Drive-Elemente auswählt.
  2. Fügen Sie dem Add-on-Skriptprojekt Manifest 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 Oberfläche zu erstellen. Sie können auch die common.homepageTrigger-Schnittstelle für mehrere Google Workspace-Hosts verwenden.
  4. Wenn Sie eine Benutzeroberfläche zur Auswahl von kontextbezogenen Drive-Elementen bereitstellen, müssen Sie eine kontextbezogene Triggerfunktion drive.onItemsSelectedTrigger 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 Schaltflächenklicks.

Drive-Startseiten

In Google Drive können Startseiten von Google Workspace-Add-ons angezeigt werden. Damit die gemeinsame Startseite Ihres Add-ons in Google Drive angezeigt wird, muss im Manifest des Add-ons ein addOns.drive-Feld 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 Homepage-Triggerfunktion im Skriptprojekt Ihres Add-ons angeben. Diese Funktion wird automatisch aufgerufen, um die Drive-Startseite zu erstellen, wenn sie benötigt wird. Sie müssen diese Funktion implementieren, um eine einzelne Card oder ein Array von Card-Objekten zu erstellen und zurückzugeben, aus denen die Startseite besteht. An die Homepage-Triggerfunktion wird ein Ereignisobjekt als Parameter übergeben, das einige allgemeine Informationen wie die Plattform des Clients enthält. Mithilfe der Daten des Ereignisobjekts können Sie die Erstellung der Startseite anpassen.

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

Google Drive verwendet einen kontextbezogenen Trigger, um zu bestimmen, welche Benutzeroberfläche (falls vorhanden) angezeigt wird, wenn der Nutzer ein oder mehrere Google Drive-Elemente auswählt. Wenn der Trigger ausgelöst wird, wird die kontextbezogene Triggerfunktion ausgeführt, die im Feld drive.onItemsSelectedTrigger.runFunction des Manifests des Add-ons angegeben ist.

So erstellen Sie eine Benutzeroberfläche für die kontextbezogene Auswahl von Elementen für Drive:

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

  2. Achten Sie darauf, dass das Manifest einen Abschnitt drive.onItemsSelectedTrigger enthält.

  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 von Widgets für die Schnittstelle verwendet werden. Wenn Sie beispielsweise eine Schaltfläche in die Benutzeroberfläche einfügen, sollte sie eine zugehörige 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 gesteuert werden soll.

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

Kontextbezogene Drive-Ereignisobjekte für Trigger zur Auswahl von Elementen enthalten Informationen zu den Elementen, die der Nutzer ausgewählt hat, wenn der Trigger ausgelöst wird. Wenn ein Nutzer in Drive mehrere Elemente auswählt, wird eines der Elemente als primäres Element betrachtet. Dieses Element wird als aktives Cursorelement bezeichnet.

abzuleiten, welches Element verwendet werden soll.

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