Google Workspace-Add-ons können benutzerdefinierte Oberflächen bereitstellen, wenn ein Nutzer Drive öffnet. So können Sie dem Nutzer zusätzliche relevante Informationen zur Verfügung stellen, Aufgaben automatisieren und Drittanbietersysteme mit Drive verbinden.
Auf die Benutzeroberfläche des Google Workspace-Add‑ons zugreifen
Sie können ein Add-on in Drive öffnen, wenn sein Symbol in der Symbolspalte rechts in der Drive-Benutzeroberfläche angezeigt wird. Ein Add-on kann eine Startseitenoberfläche, eine Elementauswahloberfläche oder beides definieren:
- Wenn ein Nutzer in Drive auf das Add-on-Symbol klickt, wird die entsprechende
drive.homepageTrigger-Funktion des Add-ons (falls vorhanden) ausgeführt. Diese Funktion erstellt und gibt eine Startseitenkarte für die Anzeige in Drive zurück. Wenn keinedrive.homepageTrigger-Funktion definiert ist, wird stattdessen eine generische Startseitenkarte angezeigt. - Wenn der Nutzer ein oder mehrere Elemente in 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.onItemsSelectedTriggeraus (falls vorhanden). Diese Funktion erstellt die kontextbezogene Benutzeroberfläche „Ausgewählte Elemente“ des Add-ons in Drive und gibt sie zur Anzeige an Drive zurück.
Add-on-Schnittstelle für Google Drive erstellen
So erstellen Sie Schnittstellen, die Drive erweitern:
- Legen Sie fest, ob Ihr Add-on eine Drive-spezifische Startseite haben soll. Legen Sie außerdem fest, ob Sie eine kontextbezogene Benutzeroberfläche bereitstellen möchten, wenn der Nutzer Drive-Elemente auswählt.
- Fügen Sie dem Add-on-Skriptprojekt manifest die entsprechenden Felder
addOns.commonundaddOns.drivehinzu, einschließlich aller erforderlichen Drive-Bereiche. - Wenn Sie eine Drive-spezifische Startseite bereitstellen, implementieren Sie die Funktion
drive.homepageTrigger, um diese Benutzeroberfläche zu erstellen. Sie können diecommon.homepageTrigger-Oberfläche auch für mehrere Google Workspace-Hosts verwenden. - Wenn Sie eine Schnittstelle zur Auswahl von kontextbezogenen Drive-Elementen bereitstellen, müssen Sie eine kontextbezogene Triggerfunktion
drive.onItemsSelectedTriggerimplementieren, um diese Schnittstelle zu erstellen. Weitere Informationen finden Sie unter Kontextbezogene Drive-Benutzeroberfläche für ausgewählte Elemente. - 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. Damit die gemeinsame Startseite Ihres Add-ons in 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.
Geben Sie in beiden Fällen den Namen einer Homepage-Triggerfunktion im Scriptprojekt 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 ein einzelnes Card-Objekt oder ein Array von Card-Objekten zu erstellen und zurückzugeben, aus denen die Startseite besteht. Der Homepage-Triggerfunktion wird ein Ereignisobjekt 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-Benutzeroberfläche für ausgewählte Elemente
In Drive wird ein kontextbezogener Trigger verwendet, um zu bestimmen, welche Benutzeroberfläche (falls vorhanden) angezeigt werden soll, wenn der Nutzer ein oder mehrere Drive-Elemente auswählt. Wenn der Trigger ausgelöst wird, wird die kontextbezogene Triggerfunktion ausgeführt, die im Manifest des Add-ons durch das Feld drive.onItemsSelectedTrigger.runFunction angegeben wird.
So erstellen Sie eine Benutzeroberfläche für die kontextbezogene Auswahl von Elementen für Drive:
Achten Sie darauf, dass das Manifest des Add-ons den
https://www.googleapis.com/auth/drive.addons.metadata.readonlyGeltungsbereich enthält.Achten Sie darauf, dass das Manifest einen Abschnitt
drive.onItemsSelectedTriggerenthält.Implementieren Sie die Funktion, die im Feld
drive.onItemsSelectedTriggerangegeben ist. Diese Funktion akzeptiert ein Ereignisobjekt als Argument und muss entweder ein einzelnesCard-Objekt oder ein Array vonCard-Objekten zurückgeben.Wie bei jeder Karte müssen Sie alle Callback-Funktionen implementieren, die für die Interaktivität von Widgets in der Benutzeroberfläche 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 verwendet die Informationen in diesem Ereignisobjekt, 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 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 ausgewählt hat, als der Trigger ausgelöst wurde. 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.
Wenn das Verhalten des Add-ons auf mehrere ausgewählte Elemente angewendet werden soll, verwenden Sie die Informationen im Array drive.selectedItems 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 Feld drive.activeCursorItem des Ereignisobjekts, um das Element aus der gesamten Auswahl zu identifizieren. Versuchen Sie nicht, aus dem Array drive.selectedItems 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"
},
...
]
},
...
}