Google Editor-Oberflächen erstellen

Mit Google Workspace-Add‑ons können Sie benutzerdefinierte Oberflächen in den Editoren bereitstellen, darunter Google Docs, Sheets und Präsentationen. So können Sie dem Nutzer relevante Informationen zur Verfügung stellen, Aufgaben automatisieren und Drittanbietersysteme mit den Editoren verbinden.

Auf die Add-on-Benutzeroberfläche zugreifen

Sie können ein Google Workspace-Add-on in den Editoren öffnen, wenn sein Symbol in der Seitenleiste für den Google Workspace-Schnellzugriff auf der rechten Seite der Benutzeroberflächen von Docs, Sheets und Präsentationen angezeigt wird.

Ein Google Workspace-Add-on kann die folgenden Oberflächen präsentieren:

  • Startseitenoberflä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 eine Startseitenkarte speziell für diesen Editor erstellt und zurückgegeben. Wenn das Manifest des Add-ons nicht die EDITOR_NAME.homepageTrigger für den Editor enthält, in dem der Nutzer es öffnet, wird stattdessen eine allgemeine Startseitenkarte angezeigt.

  • REST API-Schnittstellen: Wenn das Add-on REST APIs verwendet, können Sie Trigger einfügen, die mit dem Bereich drive.file den Zugriff auf einzelne Dateien in einem Dokument anfordern. Nachdem die Berechtigung erteilt wurde, wird ein weiterer Trigger namens EDITOR_NAME.onFileScopeGrantedTrigger ausgeführt und eine für die Datei spezifische Benutzeroberfläche wird angezeigt.

  • Schnittstellen für die Linkvorschau: Wenn Ihr Add-on in einen Drittanbieterdienst eingebunden ist, können Sie Karten erstellen, auf denen Inhalte aus den URLs Ihres Dienstes in der Vorschau angezeigt werden.

Benutzeroberflächen für Editor-Add-ons erstellen

So erstellen Sie Add-on-Schnittstellen für die Editoren:

  1. Fügen Sie dem Add-on-Skriptprojekt Manifest die entsprechenden Felder addOns.common, addOns.docs, addOns.sheets und addOns.slides hinzu.
  2. Fügen Sie dem Manifest Ihres Skriptprojekts alle erforderlichen Editor-Bereiche hinzu.
  3. Wenn Sie eine editorspezifische Startseite bereitstellen, implementieren Sie die Funktion EDITOR_NAME.homepageTrigger, um die Benutzeroberfläche zu erstellen. Andernfalls können Sie mit der common.homepageTrigger-Schnittstellecommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTriggercommon.homepageTrigger�
  4. Wenn Sie REST APIs verwenden, implementieren Sie den Autorisierungsablauf für den drive.file-Bereich und die EDITOR_NAME.onFileScopeGrantedTrigger-Triggerfunktion, um eine Schnittstelle anzuzeigen, die für die geöffnete Datei spezifisch ist. Weitere Informationen finden Sie unter REST API-Schnittstellen.
  5. Wenn Sie Linkvorschauen über einen Drittanbieterdienst konfigurieren, implementieren Sie den Autorisierungsablauf für den Bereich https://www.googleapis.com/auth/workspace.linkpreview und die Funktion linkPreviewTriggers. Weitere Informationen finden Sie unter Link-Vorschau-Schnittstellen.
  6. Implementieren Sie die zugehörigen Callback-Funktionen, die erforderlich sind, um auf die UI-Interaktionen des Nutzers zu reagieren, z. B. auf Schaltflächenklicks.

Editor-Startseiten

Sie müssen in Ihrem Add-on-Skriptprojekt eine Homepage-Triggerfunktion bereitstellen, die ein einzelnes Card-Objekt oder ein Array von Card-Objekten erstellt und zurückgibt, aus denen die Homepage des Add-ons besteht.

An die Homepage-Triggerfunktion wird ein Ereignisobjekt als Parameter übergeben, das Informationen wie die Plattform des Clients enthält. Sie können die Daten des Ereignisobjekts verwenden, um die Erstellung der Startseite anzupassen.

Sie können eine gemeinsame Startseite oder eine Startseite präsentieren, die spezifisch für den Editor ist, in dem der Nutzer Ihr Add-on öffnet.

Gemeinsame Startseite anzeigen

Wenn Sie die allgemeine Startseite Ihres Add-ons in den Editoren anzeigen möchten, müssen Sie die entsprechenden Editorfelder wie addOns.docs, addOns.sheets oder addOns.slides in das Manifest des Add-ons aufnehmen.

Das folgende Beispiel zeigt den addons-Teil eines Google Workspace-Add-on-Manifests. Das Add-on erweitert Docs, Sheets und 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 für einen bestimmten Editor präsentieren 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 Sheets und Google Präsentationen aktiviert. In Docs und Präsentationen wird die gemeinsame Startseite angezeigt, in Sheets eine eigene Startseite. Die Callback-Funktion onSheetsHomepage erstellt die Sheets-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 Benutzeroberfläche anzeigen, die speziell für die Datei ist, die in der Editor-Hostanwendung geöffnet ist.

Sie müssen den Autorisierungsablauf für den drive.file-Bereich einbinden, 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, wird die kontextbezogene Triggerfunktion ausgeführt, die im Add-on-Manifest durch das Feld EDITOR_NAME.onFileScopeGrantedTrigger.runFunction angegeben wird.

So erstellen Sie eine REST API-Schnittstelle für einen der Editoren: Ersetzen Sie EDITOR_NAME durch die Editor-Host-App, die Sie verwenden möchten, z. B. sheets.onFileScopeGrantedTrigger.

  1. Fügen Sie EDITOR_NAME.onFileScopeGrantedTrigger im entsprechenden Editorabschnitt Ihres Manifests ein. Wenn Sie diese Schnittstelle beispielsweise in Google Sheets erstellen möchten, fügen Sie den Trigger dem Abschnitt "sheets" hinzu.
  2. Implementieren Sie die Funktion, die im Abschnitt EDITOR_NAME.onFileScopeGrantedTrigger genannt wird. Diese Funktion akzeptiert ein Ereignisobjekt als Argument und muss entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurückgeben.
  3. Wie bei jeder Karte müssen Sie die Callback-Funktionen implementieren, die verwendet werden, um die Widget-Interaktivität für die Benutzeroberfläche bereitzustellen. 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.

Das folgende Beispiel zeigt den addons-Teil eines Google Workspace-Add‑on-Manifests. Das Add-on verwendet REST APIs, daher ist onFileScopeGrantedTrigger für Google Tabellen enthalten. Wenn ein Nutzer den Bereich drive.file gewährt, erstellt die Callback-Funktion onFileScopeGrantedSheets eine dateispezifische Benutzeroberfläche.

"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"      }    }

Wenn Sie die Linkvorschau für einen Drittanbieterdienst aktivieren möchten, müssen Sie die Linkvorschau im Manifest Ihres Add-ons konfigurieren und eine Funktion erstellen, die eine Vorschaukarte zurückgibt. Bei Diensten, die eine Nutzerautorisierung erfordern, muss Ihre Funktion auch den Autorisierungsablauf aufrufen.

Eine Anleitung zum Aktivieren der Linkvorschau finden Sie unter Vorschaulinks mit Smartchips.

Ereignisobjekte

Ein Ereignisobjekt wird erstellt und an Triggerfunktionen wie EDITOR_NAME.homepageTrigger oder EDITOR_NAME.onFileScopeGrantedTrigger übergeben. Die Triggerfunktion verwendet die Informationen im 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 ein Editor die aktive Hostanwendung des Add-ons ist, enthalten die Ereignisobjekte die Felder des Ereignisobjekts Docs, Sheets oder Slides, die Clientinformationen enthalten.

Wenn das Add-on für den aktuellen Nutzer oder das aktuelle Dokument keine Autorisierung für den Bereich drive.file hat, enthält das Ereignisobjekt nur das Feld docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission oder slides.addonHasFileScopePermission. Wenn das Add-on autorisiert ist, enthält das Ereignisobjekt alle Felder des Editor-Ereignisobjekts.

Das folgende Beispiel zeigt ein Editor-Ereignisobjekt, das an eine sheets.onFileScopeGrantedTrigger-Funktion übergeben wird. Hier hat das Add-on die drive.file-Bereichsautorisierung für das aktuelle Dokument:

`        {           "commonEventObject": { ... },           "sheets": {             "addonHasFileScopePermission": true,             "id":"A_24Q3CDA23112312ED52",             "title":"How to get started with Sheets"           },           ...         }