Google Drive-Schnittstellen erstellen

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

Benutzeroberfläche des Google Workspace-Add-ons aufrufen

Sie können ein Add-on in Drive öffnen, wenn sein Symbol in der Symbolspalte auf der rechten Seite der Drive-Benutzeroberfläche angezeigt wird. Ein Add-on kann eine Startseitenoberfläche, eine Oberfläche zur Elementauswahl oder beides definieren:

Drive-Oberfläche des Add-ons erstellen

Führen Sie die folgenden allgemeinen Schritte aus, um Oberflächen zu erstellen, die Drive erweitern:

  1. Legen Sie fest, ob Ihr Add-on eine Drive-spezifische Startseite haben soll. Entscheiden Sie auch, ob Sie eine kontextbezogene Oberfläche bereitstellen möchten, wenn der Nutzer Drive-Elemente auswählt.
  2. Fügen Sie dem Manifest des Add-on-Skriptprojekts die entsprechenden addOns.common und addOns.drive Felder hinzu, einschließlich aller erforderlichen Drive Bereiche.
  3. Wenn Sie eine Drive-spezifische Startseite bereitstellen, implementieren Sie die drive.homepageTrigger Funktion, um diese Oberfläche zu erstellen. Sie können die common.homepageTrigger Oberfläche auch für mehrere Google Workspace-Hosts verwenden.
  4. Wenn Sie eine kontextbezogene Drive-Oberfläche zur Elementauswahl bereitstellen, müssen Sie eine drive.onItemsSelectedTrigger kontextbezogene Triggerfunktion implementieren, um diese Oberfläche zu erstellen. Weitere Informationen finden Sie unter Kontextbezogene Drive-Oberflä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

Drive unterstützt die Anzeige von Add-on Startseiten. Wenn die gemeinsame Startseite Ihres Add-ons in Drive angezeigt werden soll, muss im Manifest des Add-ons ein addOns.drive Feld vorhanden sein.

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

Geben Sie in beiden Fällen den Namen einer Startseiten-Triggerfunktion im Skriptprojekt Ihres Add-ons an. Diese Funktion wird automatisch aufgerufen, um die Drive-Startseite zu erstellen, wenn sie benötigt wird. Implementieren Sie diese Funktion, um eine einzelne Card oder ein Array von Card Objekten zu erstellen und zurückzugeben, aus denen die Startseite besteht. Der Startseiten-Triggerfunktion wird ein Ereignis objekt als Parameter übergeben, das einige allgemeine Informationen wie die Plattform des Clients enthält. Verwenden Sie die Daten des Ereignisobjekts, um die Startseite zu erstellen.

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

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

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

  1. Das Manifest des Add-ons muss den https://www.googleapis.com/auth/drive.addons.metadata.readonly Bereich enthalten.

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

  3. Implementieren Sie die Funktion, die im drive.onItemsSelectedTrigger Feld 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. Implementieren Sie wie bei jeder Karte alle Callback-Funktionen, die verwendet werden, um die Widget-Interaktivität für die Oberfläche bereitzustellen. Wenn Sie beispielsweise eine Schaltfläche in die Oberfläche einfügen, muss sie eine angehängte 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 verwendet die Informationen in diesem Ereignisobjekt, um zu bestimmen, wie Add-on-Karten erstellt werden oder wie das Add-on-Verhalten anderweitig gesteuert wird.

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 Elementauswahl enthalten Informationen zu den Elementen, die der Nutzer ausgewählt hat, als der Trigger ausgelöst wurde. Wenn ein Nutzer in Drive mehrere Elemente auswählt, wird eines der Elemente als primär relevant betrachtet. Dieses Element wird als aktives Cursor-Element bezeichnet.

Wenn das Verhalten des Add-ons auf mehrere ausgewählte Elemente angewendet werden soll, verwenden Sie die Informationen im drive.selectedItems Array im Ereignisobjekt, um alle Elemente zu identifizieren.

Wenn das Verhalten eines Add-ons nur auf ein einzelnes ausgewähltes Element angewendet werden soll, verwenden Sie die Informationen im drive.activeCursorItem Feld des Ereignisobjekts, um das Element aus der vollständigen Auswahl zu identifizieren. Versuchen Sie nicht, das zu verwendende Element aus dem drive.selectedItems Array abzuleiten.

Das folgende Beispiel zeigt ein Drive-Ereignis objekt, 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"
      },
      ...
    ]
  },
  ...
}