Mit Google Workspace-Add-ons können Sie benutzerdefinierte Benutzeroberflächen in den Editoren bereitstellen, einschließlich Google Docs, Google Tabellen und Google Präsentationen. Auf diese Weise können Sie dem Nutzer relevante Informationen zur Verfügung stellen, Aufgaben automatisieren und Drittanbietersysteme mit den Bearbeitern verbinden.
Auf die Add-on-UI zugreifen
Sie können ein Google Workspace-Add-on in den Editoren öffnen, wenn das zugehörige Symbol in der Seitenleiste für den Schnellzugriff von Google Workspace auf der rechten Seite der Benutzeroberfläche von Google Docs, Google Tabellen und Google Präsentationen angezeigt wird.
Ein Google Workspace-Add-on kann die folgenden Oberflächen enthalten:
Oberflächenoberflächen: Wenn das Manifest des Add-ons den Trigger
EDITOR_NAME.homepageTrigger
für den Editor enthält, in dem der Nutzer das Add-on öffnet, wird über das Add-on eine Startseitenkarte speziell für diesen Editor erstellt. Wenn das Manifest des Add-ons nichtEDITOR_NAME.homepageTrigger
für den Editor enthält, in dem der Nutzer es öffnet, wird stattdessen eine generische Startseitenkarte angezeigt.REST API-Schnittstellen: Wenn das Add-on REST APIs verwendet, können Sie Trigger einbinden, die dateigebundenen Zugriff auf ein Dokument mit dem Bereich
drive.file
anfordern. Anschließend wird ein anderer Trigger namensEDITOR_NAME.onFileScopeGrantedTrigger
ausgeführt und zeigt eine für die Datei spezifische Schnittstelle an.Linkvorschau-Oberflächen: Wenn Ihr Add-on in einen Drittanbieterdienst eingebunden werden kann, können Sie Karten erstellen, die eine Vorschau von Inhalten aus den URLs Ihres Dienstes anzeigen.
Schnittstellen für Editor-Add-ons erstellen
Erstellen Sie Editor-Add-ons für Bearbeiter. Gehen Sie dazu so vor:
- Fügen Sie dem Manifest des Add-on-Skriptprojekts die entsprechenden Felder
addOns.common
,addOns.docs
,addOns.sheets
undaddOns.slides
hinzu. - Fügen Sie dem Manifest des Skriptprojekts alle erforderlichen Editor-Bereiche hinzu.
- Wenn Sie eine editorspezifische Startseite bereitstellen, implementieren Sie die Funktion
EDITOR_NAME.homepageTrigger
, um die Schnittstelle zu erstellen. Falls nicht, erstellen Sie über diecommon.homepageTrigger
-Oberfläche eine gemeinsame Startseite für Ihre Hostanwendungen. - Wenn Sie REST APIs verwenden, implementieren Sie den Autorisierungsvorgang für den Bereich
drive.file
und die TriggerfunktionEDITOR_NAME.onFileScopeGrantedTrigger
, um eine für die geöffnete Datei spezifische Schnittstelle anzuzeigen. Weitere Informationen finden Sie unter REST API-Oberflächen. - Wenn Sie die Linkvorschau über einen Drittanbieterdienst konfigurieren, implementieren Sie den Autorisierungsvorgang für den Bereich
https://www.googleapis.com/auth/workspace.linkpreview
und die FunktionlinkPreviewTriggers
. Weitere Informationen finden Sie unter Linkvorschau-Oberflächen. - 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.
Editor-Startseiten
Sie müssen im Skriptprojekt des Add-ons eine Triggerfunktion für die Startseite bereitstellen, die ein einzelnes Card
-Objekt oder ein Array von Card
-Objekten auf der Startseite des Add-ons erstellt und zurückgibt.
An die Triggerfunktion für die Startseite wird ein Ereignisobjekt als Parameter übergeben, der Informationen wie die Plattform des Clients enthält. Mit den Ereignisobjektdaten können Sie die Startseite anpassen.
Sie können eine gemeinsame Startseite oder eine Startseite speziell für den Editor angeben, in dem der Nutzer Ihr Add-on öffnet.
Allgemeine Startseite anzeigen
Fügen Sie die entsprechenden Editor-Felder wie addOns.docs
, addOns.sheets
oder addOns.slides
in das Manifest des Add-ons ein, um die allgemeine Startseite des Add-ons in den Editoren anzuzeigen.
Das folgende Beispiel zeigt den Teil addons
eines Google Workspace-Add-on-Manifests. Das Add-on erweitert Google Docs, Google Tabellen und Google Präsentationen und zeigt die gemeinsame Startseite in jeder Host-App an.
"addOns": { "common": { "name": "Translate", "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png", "layoutProperties": { "primaryColor": "#2772ed" }, "homepageTrigger": { "runFunction": "onHomepage" } }, "docs": {}, "sheets": {}, "slides": {} } }
Editor-spezifische Startseite anzeigen
Wenn Sie eine Startseite speziell für einen Bearbeiter anzeigen möchten, fügen Sie dem Add-on-Manifest EDITOR_NAME.homepageTrigger
hinzu.
Das folgende Beispiel zeigt den addons
-Teil eines Google Workspace-Add-on-Manifests.
Das Add-on ist für Google Docs, Google Tabellen und Google Präsentationen aktiviert. Sie zeigt die gemeinsame Startseite in Google Docs und Google Präsentationen und eine eigene Startseite in Google Tabellen an. Die Callback-Funktion onSheetsHomepage
erstellt die Google Tabellen-spezifische Startseitenkarte.
"addOns": { "common": { "name": "Translate", "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png", "layoutProperties": { "primaryColor": "#2772ed" }, "homepageTrigger": { "runFunction": "onHomepage" } }, "docs": {}, "slides": {}, "sheets": { "homepageTrigger": { "runFunction": "onSheetsHomepage" }, } }
REST API-Schnittstellen
Wenn Ihr Add-on REST APIs wie die Google Sheets API verwendet, können Sie mit der Funktion onFileScopeGrantedTrigger
eine neue Schnittstelle speziell für die Datei anzeigen, die in der Host-App des Editors geöffnet ist.
Sie müssen den Autorisierungsvorgang für den Bereich drive.file
einbeziehen, um die Funktion onFileScopeGrantedTrigger
verwenden zu können. Informationen zum Anfordern des Bereichs drive.file
finden Sie unter Dateizugriff für aktuelles Dokument anfordern.
Wenn ein Nutzer den Bereich drive.file
gewährt, wird EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
ausgelöst. Wenn der Trigger ausgelöst wird, führt er die kontextabhängige Triggerfunktion aus, die im Feld EDITOR_NAME.onFileScopeGrantedTrigger.runFunction
im Add-on-Manifest angegeben ist.
Führen Sie die folgenden Schritte aus, um eine REST API-Schnittstelle für einen der Bearbeiter zu erstellen.
Ersetzen Sie EDITOR_NAME
durch die Editor-Hostanwendung, die Sie verwenden möchten, z. B. sheets.onFileScopeGrantedTrigger
.
- Fügen Sie
EDITOR_NAME.onFileScopeGrantedTrigger
in den entsprechenden Editor-Abschnitt Ihres Manifests ein. Wenn Sie diese Schnittstelle beispielsweise in Google Tabellen erstellen möchten, fügen Sie den Trigger im Abschnitt"sheets"
hinzu. - Implementieren Sie die im Abschnitt
EDITOR_NAME.onFileScopeGrantedTrigger
benannte Funktion. 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 die Callback-Funktionen implementieren, die zur Bereitstellung der Widget-Interaktivität für die Schnittstelle verwendet werden. Wenn Sie beispielsweise eine Schaltfläche in die Benutzeroberfläche einfügen, sollte dieser ein Action-Element und eine implementierte Callback-Funktion zugeordnet sein, die ausgeführt wird, wenn auf die Schaltfläche geklickt wird.
Das folgende Beispiel zeigt den addons
-Teil eines Google Workspace-Add-on-Manifests.
Das Add-on verwendet REST APIs. Daher ist onFileScopeGrantedTrigger
in Google Tabellen enthalten. Wenn ein Nutzer den Bereich drive.file
gewährt, erstellt die Callback-Funktion onFileScopeGrantedSheets
eine dateispezifische Schnittstelle.
"addOns": { "common": { "name": "Productivity add-on", "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png", "layoutProperties": { "primaryColor": "#669df6", "secondaryColor": "#ee675c" } }, "sheets": { "homepageTrigger": { "runFunction": "onEditorsHomepage" }, "onFileScopeGrantedTrigger": { "runFunction": "onFileScopeGrantedSheets" } }
Linkvorschauoberflächen für Drittanbieterdienste
Wenn Sie die Linkvorschau für einen Drittanbieterdienst aktivieren möchten, müssen Sie im Manifest des Add-ons Linkvorschauen konfigurieren und eine Funktion erstellen, die eine Vorschaukarte zurückgibt. Bei Diensten, für die eine Nutzerautorisierung erforderlich ist, muss die Funktion auch den Autorisierungsvorgang aufrufen.
Eine Anleitung zum Aktivieren der Linkvorschau finden Sie unter Vorschau von Links mit Smartchips ansehen.
Ereignisobjekte
Ein Ereignisobjekt wird erstellt und an Triggerfunktionen wie EDITOR_NAME.homepageTrigger
oder EDITOR_NAME.onFileScopeGrantedTrigger
übergeben. Die Triggerfunktion bestimmt anhand der Informationen im Ereignisobjekt, wie Add-on-Karten erstellt oder das Add-on-Verhalten anderweitig gesteuert wird.
Die vollständige Struktur von Ereignisobjekten wird unter Ereignisobjekte beschrieben.
Wenn ein Bearbeiter die aktive Host-App des Add-ons ist, umfassen die Ereignisobjekte Ereignisobjektfelder in Google Docs, Google Tabellen oder Google Präsentationen, die Clientinformationen enthalten.
Wenn das Add-on keine Autorisierung des Umfangs drive.file
für den aktuellen Nutzer oder das aktuelle Dokument hat, enthält das Ereignisobjekt nur das Feld docs.addonHasFileScopePermission
, sheets.addonHasFileScopePermission
oder slides.addonHasFileScopePermission
. Wenn das Add-on über eine entsprechende Autorisierung verfügt, enthält das Ereignisobjekt alle Felder für Editor-Ereignisobjekte.
Das folgende Beispiel zeigt ein Editor-Ereignisobjekt, das an eine sheets.onFileScopeGrantedTrigger
-Funktion übergeben wird. Hier hat das Add-on die Autorisierung des Umfangs drive.file
für das aktuelle Dokument:
` { "commonEventObject": { ... }, "sheets": { "addonHasFileScopePermission": true, "id":"A_24Q3CDA23112312ED52", "title":"How to get started with Sheets" }, ... }