Google Drive-Oberflächen erstellen

Google Workspace-Add-ons können angepasste Oberflächen bereitstellen, wenn Nutzer Google Drive verwenden. Auf diese Weise können Sie dem Nutzer zusätzliche relevante Informationen bereitstellen, Aufgaben automatisieren und Systeme von Drittanbietern mit Google Drive verbinden.

Auf die Add-on-UI zugreifen

Sie können ein Google Workspace-Add-on in Google Drive öffnen, wenn das zugehörige Symbol in der Symbolspalte auf der rechten Seite der Drive-Benutzeroberfläche angezeigt wird. Ein Google Workspace-Add-on kann eine Oberfläche für die Startseite, eine Oberfläche zur Elementauswahl 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 Startseitenkarte und gibt sie zur Anzeige an 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 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 Kontextfunktion drive.onItemsSelectedTrigger aus (falls vorhanden). Diese Funktion erstellt die Google Drive-Schnittstelle für kontextuelle „Elemente ausgewählt“ des Add-ons und gibt sie zur Anzeige an Google Drive zurück.

Drive-Add-on-Oberfläche erstellen

Mit den folgenden allgemeinen Schritten können Sie Schnittstellen erstellen, die Google Drive erweitern:

  1. Legen Sie fest, ob das Add-on eine Drive-spezifische Startseite haben soll. Entscheiden Sie außerdem, ob Sie eine kontextbezogene Oberfläche für die Auswahl von Drive-Elementen bereitstellen möchten.
  2. Fügen Sie dem Manifest des Add-on-Skripts 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 Schnittstelle zu erstellen. Sie können auch die Schnittstelle common.homepageTrigger für mehrere Google Workspace-Hosts verwenden.
  4. Wenn Sie eine Oberfläche für die Auswahl von kontextbezogenen Drive-Elementen bereitstellen, müssen Sie zum Erstellen dieser Schnittstelle eine kontextabhängige Triggerfunktion drive.onItemsSelectedTrigger implementieren. Weitere Informationen finden Sie unter Drive-Kontextoberfläche für ausgewählte Elemente.
  5. Implementieren Sie die zugehörigen Callback-Funktionen, die erforderlich sind, um auf die UI-Interaktionen des Nutzers, z. B. Klicks auf Schaltflächen, zu reagieren.

Drive-Startseiten

Google Drive unterstützt das Anzeigen von Google Workspace-Add-on-Startseiten. Damit die allgemeine Startseite des 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 einen drive.homepageTrigger hinzufügen, um eine Drive-spezifische Startseite bereitzustellen.

In beiden Fällen müssen Sie im Skriptprojekt des Add-ons den Namen einer Homepage-Triggerfunktion angeben. Diese Funktion wird bei Bedarf automatisch zur Erstellung der Drive-Startseite aufgerufen. Du musst diese Funktion implementieren, um ein einzelnes Card-Objekt oder ein Array von Card-Objekten zu erstellen und zurückzugeben, die die Startseite bilden. An die Triggerfunktion für die Startseite wird ein Ereignisobjekt als Parameter übergeben, der einige allgemeine Informationen enthält, z. B. die Plattform des Clients. Mit den Ereignisobjektdaten können Sie den Aufbau der Startseite anpassen.

Kontextabhängige Oberfläche von Drive für ausgewählte Elemente

Google Drive verwendet einen kontextbezogenen Trigger, um zu bestimmen, welche Oberfläche (falls vorhanden) angezeigt wird, wenn der Nutzer ein oder mehrere Google Drive-Elemente auswählt. Wenn der Trigger ausgelöst wird, führt er die kontextabhängige Triggerfunktion aus, die im Feld drive.onItemsSelectedTrigger.runFunction im Add-on-Manifest angegeben ist.

So erstellen Sie eine Oberfläche zur kontextbezogenen Elementauswahl für Drive:

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

  2. Das Manifest muss einen drive.onItemsSelectedTrigger-Abschnitt enthalten.

  3. Implementieren Sie die im Feld drive.onItemsSelectedTrigger benannte Funktion. 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 zur Bereitstellung von Widget-Interaktivität für die Schnittstelle verwendet werden. Wenn Sie beispielsweise eine Schaltfläche in die Benutzeroberfläche einfügen, sollte dieser eine Aktion und eine implementierte Callback-Funktion zugeordnet sein, 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 anhand der Informationen in diesem Ereignisobjekt 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 event object (Drive-Ereignisobjekt), das Drive-spezifische Clientinformationen enthält.

Kontextbezogene Drive-Ereignisobjekte für Trigger zur Elementauswahl enthalten Informationen zu den Elementen, die der Nutzer beim Auslösen des Triggers ausgewählt hat. Wenn ein Nutzer mehr als ein Element in Drive auswählt, gilt eines der Elemente als eines von primärem Interesse. 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"
          },
          ...
        ]
      },
      ...
    }