Diese Seite wurde von der Cloud Translation API übersetzt.

Google Editor-Oberflächen erstellen

Mit Google Workspace-Add-ons können Sie benutzerdefinierte Oberflächen in den Editoren bereitstellen, einschließlich Google Docs, Google Tabellen und Google Präsentationen. So können Sie Nutzern relevante Informationen zur Verfügung stellen, Aufgaben automatisieren und Systeme von Drittanbietern mit den Editoren verbinden.

Auf die Add-on-Benutzeroberfläche zugreifen

Sie können ein Google Workspace-Add-on in den Editoren öffnen, wenn das Symbol in der Seitenleiste für den Schnellzugriff von Google Workspace rechts in 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:

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 die EDITOR_NAME.homepageTrigger für den Editor nicht 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 einfügen, die mit dem Bereich drive.file den Zugriff auf ein Dokument pro Datei anfordern. Nach der Genehmigung wird ein weiterer Trigger namens EDITOR_NAME.onFileScopeGrantedTrigger ausgeführt und eine dateispezifische Benutzeroberfläche angezeigt.
Oberflächen für Linkvorschauen: Wenn Ihr Add-on in einen Drittanbieterdienst eingebunden ist, können Sie Karten erstellen, die eine Vorschau der Inhalte aus den URLs Ihres Dienstes enthalten.

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

So erstellst du Editor-Add-on-Benutzeroberflächen für die Editoren:

Fügen Sie dem Manifest des Add-on-Scripts die entsprechenden Felder addOns.common, addOns.docs, addOns.sheets und addOns.slides hinzu.
Fügen Sie dem Manifest Ihres Scriptprojekts alle erforderlichen Bearbeiterbereiche hinzu.
Wenn du eine Bearbeiterspezifische Startseite bereitstellst, implementiere die Funktion EDITOR_NAME.homepageTrigger, um die Benutzeroberfläche zu erstellen. Falls nicht, verwenden Sie die Benutzeroberfläche von common.homepageTrigger, um eine gemeinsame Startseite für Ihre Host-Apps zu erstellen.
Wenn Sie REST APIs verwenden, implementieren Sie den Autorisierungsablauf für den Bereich drive.file und die Triggerfunktion EDITOR_NAME.onFileScopeGrantedTrigger, um eine für die geöffnete Datei spezifische Benutzeroberfläche anzuzeigen. Weitere Informationen finden Sie unter REST API-Schnittstellen.
Wenn Sie Linkvorschauen über einen Drittanbieterdienst konfigurieren, implementieren Sie den Autorisierungsablauf https://www.googleapis.com/auth/workspace.linkpreview und die Funktion linkPreviewTriggers. Weitere Informationen finden Sie unter Oberflächen für Linkvorschauen.
Implementieren Sie die zugehörigen Callback-Funktionen, die erforderlich sind, um auf die UI-Interaktionen des Nutzers zu reagieren, z. B. auf Klicks auf Schaltflächen.

Editor-Startseiten

Sie müssen im Scriptprojekt Ihres Add-ons eine Startseiten-Triggerfunktion angeben, die ein einzelnes Card oder ein Array von Card-Objekten erstellt und zurückgibt, die die Startseite des Add-ons bilden.

Der Triggerfunktion für die Startseite wird als Parameter ein Ereignisobjekt übergeben, das Informationen wie die Plattform des Clients enthält. Sie können die Daten des Ereignisobjekts verwenden, um die Gestaltung der Startseite anzupassen.

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

Gemeinsame Startseite anzeigen

Wenn Sie die Startseite Ihres Add-ons in den Editoren anzeigen lassen möchten, fügen Sie die entsprechenden Editor-Felder wie addOns.docs, addOns.sheets oder addOns.slides in das Manifest des Add-ons ein.

Das folgende Beispiel zeigt den addons-Teil eines Google Workspace-Add-on-Manifests. Das Add-on erweitert Docs, Sheets und Präsentationen und zeigt in jeder Host-App die gemeinsame Startseite 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": {}
  }
}

Eine benutzerspezifische Startseite anzeigen

Wenn Sie eine für einen Editor spezifische Startseite anzeigen möchten, fügen Sie dem Add-on-Manifest EDITOR_NAME.homepageTrigger hinzu.

Das folgende Beispiel zeigt den addons-Abschnitt eines Google Workspace-Add-on-Manifests. Das Add-on ist für Google Docs, Google Tabellen und Google Präsentationen aktiviert. In Docs und Präsentationen wird die gemeinsame Startseite angezeigt, in Google Tabellen eine eigene. Die Rückruffunktion onSheetsHomepage erstellt die spezifische Google Tabellen-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 verwendet, z. B. die Google Tabellen API, können Sie mit der Funktion onFileScopeGrantedTrigger eine neue Benutzeroberfläche für die Datei anzeigen, die in der Editor-Host-App geöffnet ist.

Sie müssen den Autorisierungsablauf für den Bereich drive.file einbinden, um die Funktion onFileScopeGrantedTrigger verwenden zu können. Weitere Informationen zum Anfordern des drive.file-Zugriffs finden Sie unter Dateizugriff für das aktuelle Dokument anfordern.

Wenn ein Nutzer den Umfang drive.file gewährt, wird EDITOR_NAME.onFileScopeGrantedTrigger.runFunction ausgelöst. Wenn der Trigger ausgelöst wird, wird die Kontexttriggerfunktion ausgeführt, die im Add-on-Manifest im Feld EDITOR_NAME.onFileScopeGrantedTrigger.runFunction angegeben ist.

So erstellst du 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.

Fügen Sie EDITOR_NAME.onFileScopeGrantedTrigger in den entsprechenden Abschnitt des Editors in Ihrem Manifest ein. Wenn Sie diese Benutzeroberfläche beispielsweise in Google Tabellen erstellen möchten, fügen Sie den Trigger dem Abschnitt "sheets" hinzu.
Implementieren Sie die im Abschnitt EDITOR_NAME.onFileScopeGrantedTrigger angegebene Funktion. Diese Funktion akzeptiert ein Ereignisobjekt als Argument und muss entweder ein einzelnes Card-Objekt oder ein Array von Card-Objekten zurückgeben.
Wie bei jeder Karte müssen Sie die Callback-Funktionen implementieren, die für die Interaktivität des Widgets auf der Benutzeroberfläche verwendet werden. Wenn Sie beispielsweise eine Schaltfläche in die Benutzeroberfläche einfügen, sollte sie eine verknüpfte Aktion und eine implementierte Callback-Funktion haben, die ausgeführt wird, wenn auf die Schaltfläche geklickt wird.

Das folgende Beispiel zeigt den addons-Abschnitt eines Google Workspace-Add-on-Manifests. Das Add-on verwendet REST APIs. Daher ist onFileScopeGrantedTrigger für Google Tabellen enthalten. Wenn ein Nutzer den Umfang 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"
     }
   }

Benutzeroberflächen für Linkvorschauen von Drittanbieterdiensten

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

Eine Anleitung zum Aktivieren von Linkvorschauen finden Sie unter Vorschaulinks mit Smartchips erstellen.

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 anderweitig gesteuert werden soll.

Die vollständige Struktur von Ereignisobjekten wird unter Ereignisobjekte beschrieben.

Wenn eine Editor-App die aktive Host-App des Add-ons ist, enthalten die Ereignisobjekte Felder für Ereignisobjekte von Google Docs, Google Tabellen oder Google Präsentationen, die Kundeninformationen enthalten.

Wenn das Add-on keine Autorisierung für den Bereich 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 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"
          },
          ...
        }