Google Editor-Oberflächen erstellen

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 nicht EDITOR_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 namens EDITOR_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:

  1. Fügen Sie dem Manifest des Add-on-Skriptprojekts die entsprechenden Felder addOns.common, addOns.docs, addOns.sheets und addOns.slides hinzu.
  2. Fügen Sie dem Manifest des Skriptprojekts alle erforderlichen Editor-Bereiche hinzu.
  3. Wenn Sie eine editorspezifische Startseite bereitstellen, implementieren Sie die Funktion EDITOR_NAME.homepageTrigger, um die Schnittstelle zu erstellen. Falls nicht, erstellen Sie über die common.homepageTrigger-Oberfläche eine gemeinsame Startseite für Ihre Hostanwendungen.
  4. Wenn Sie REST APIs verwenden, implementieren Sie den Autorisierungsvorgang für den Bereich drive.file 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 die Linkvorschau über einen Drittanbieterdienst konfigurieren, implementieren Sie den Autorisierungsvorgang für den Bereich https://www.googleapis.com/auth/workspace.linkpreview und die Funktion linkPreviewTriggers. Weitere Informationen finden Sie unter Linkvorschau-Oberflächen.
  6. 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.

  1. 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.
  2. Implementieren Sie die im Abschnitt EDITOR_NAME.onFileScopeGrantedTrigger benannte 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 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"
     }
   }

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