Google Editor-Oberflächen erstellen

Mit Add-ons für Google Workspace können Sie in den Editoren benutzerdefinierte Schnittstellen bereitstellen, einschließlich Google Docs, Google Tabellen und Google Präsentationen. So können Sie dem Nutzer relevante Informationen zur Verfügung stellen, Aufgaben automatisieren und Drittanbietersysteme mit den Editoren verbinden.

Add-on-UI aufrufen

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

Ein Add-on kann folgende Oberflächen enthalten:

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

  • REST API-Oberflächen: Wenn das Add-on REST APIs verwendet, können Sie im Bereich drive.file Trigger verwenden, die pro Datei den Zugriff auf ein Dokument anfordern. Nach der Gewährung wird ein weiterer Trigger namens EDITOR_NAME.onFileScopeGrantedTrigger ausgeführt und zeigt eine für die Datei spezifische Schnittstelle an.

  • Vorschauschnittstellen verknüpfen (Entwicklervorschau): Wenn dein Add-on in einen Drittanbieterdienst eingebunden ist, kannst du Karten erstellen, um eine Vorschau von Inhalten aus den URLs deines Dienstes anzuzeigen.

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

Führen Sie die folgenden Schritte aus, um Add-on-Oberflächen für die Editoren zu erstellen:

  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 Skriptprojektmanifest alle erforderlichen Bearbeiterbereiche hinzu.
  3. Wenn Sie eine Editor-spezifische Startseite angeben, implementieren Sie die Funktion EDITOR_NAME.homepageTrigger, um die Schnittstelle zu erstellen. Ist dies nicht der Fall, verwenden Sie die Schnittstelle common.homepageTrigger, um eine gemeinsame Startseite für Ihre Host-Apps zu erstellen.
  4. Wenn Sie REST APIs verwenden, implementieren Sie den drive.file-Vorgang für den Autorisierungsbereich und die Triggerfunktion EDITOR_NAME.onFileScopeGrantedTrigger, um eine für die geöffnete Datei spezifische Schnittstelle anzuzeigen. Weitere Informationen finden Sie unter REST API-Oberflächen.
  5. Wenn Sie eine Linkvorschau von einem Drittanbieterdienst konfigurieren, implementieren Sie den https://www.googleapis.com/auth/workspace.linkpreview-Vorgang für die Autorisierung des Bereichs und die Funktion linkPreviewTriggers. Weitere Informationen finden Sie unter Vorschauoberflächen verknüpfen.
  6. Implementiere die zugehörigen Callback-Funktionen, die erforderlich sind, um auf UI-Interaktionen des Nutzers zu reagieren, z. B. auf Klicks auf Schaltflächen.

Editor-Startseiten

Sie müssen eine Startseiten-Triggerfunktion im Skriptprojekt des Add-ons bereitstellen, die ein einzelnes Card-Objekt oder ein Array von Card-Objekten für die Startseite des Add-ons erstellt und zurückgibt.

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

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

Allgemeine Startseite anzeigen

Wenn du die allgemeine Startseite des Add-ons in den Editoren anzeigen möchtest, nimm die entsprechenden Editor-Felder wie addOns.docs, addOns.sheets oder addOns.slides in das Manifest des Add-ons auf.

Das folgende Beispiel zeigt den addons-Teil eines Google Workspace-Add-on-Manifests. Das Add-on erweitert Docs, Tabellen 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": {}
  }
}

Editorspezifische Startseite anzeigen

Wenn du eine Startseite speziell für einen Editor präsentieren möchtest, füge dem Add-on-Manifest den 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. Es zeigt die gemeinsame Startseite in Google Docs und Google Präsentationen sowie eine eigene Startseite in Google Tabellen. 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 verwendet, z. B. die Google Sheets API, können Sie mit der Funktion onFileScopeGrantedTrigger eine neue Schnittstelle für die Datei aufrufen, die in der Editor-Host-App geöffnet ist.

Sie müssen den Autorisierungsablauf des Bereichs drive.file angeben, um die Funktion onFileScopeGrantedTrigger verwenden zu können. Informationen zum Anfordern des Bereichs drive.file finden Sie unter Dateizugriff für das aktuelle 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 Kontexttrigger-Funktion aus, die im Feld EDITOR_NAME.onFileScopeGrantedTrigger.runFunction des Add-on-Manifests angegeben ist.

So erstellen Sie eine REST API-Oberfläche 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üge im Abschnitt des entsprechenden Editors in deinem Manifest den Abschnitt EDITOR_NAME.onFileScopeGrantedTrigger ein. Wenn Sie diese Schnittstelle beispielsweise in Google Tabellen erstellen möchten, fügen Sie den Trigger dem Abschnitt "sheets" hinzu.
  2. 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.
  3. Wie bei jeder Karte müssen Sie die Callback-Funktionen implementieren, die zur Bereitstellung von Widget-Interaktivität für die Schnittstelle verwendet werden. Wenn Sie beispielsweise eine Schaltfläche in die Benutzeroberfläche einfügen, sollte diese eine Aktion enthalten 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. Da das Add-on REST APIs verwendet, ist onFileScopeGrantedTrigger für 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"
     }
   }

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 die Funktion auch den Autorisierungsablauf aufrufen.

Eine Anleitung zum Aktivieren der Linkvorschau finden Sie unter Vorschaulinks in Google Docs (Entwicklervorschau).

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 festzulegen, wie Add-on-Karten erstellt werden oder anderweitig das Add-on-Verhalten zu steuern.

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

Wenn ein Bearbeiter die agierende Host-App des Add-ons ist, enthalten die Ereignisobjekte die Ereignisfelder von Google Docs, Google Tabellen oder Google Präsentationen, die Clientinformationen enthalten.

Wenn das Add-on für den aktuellen Nutzer oder das Dokument keine Autorisierung des Typs drive.file hat, enthält das Ereignisobjekt nur das Feld docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission oder slides.addonHasFileScopePermission. Wenn das Add-on dazu berechtigt 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 Autorisierung des Bereichs drive.file für das aktuelle Dokument:

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