Google-Editor-Oberflächen erstellen

Mit Add-ons für Google Workspace können Sie benutzerdefinierte Oberflächen in den Editoren bereitstellen, darunter Google Docs, Google Sheets 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 das Add-on für Google Workspace in den Editoren öffnen, wenn das Symbol im Seitenbereich für den Schnellzugriff von Google Workspace in den Benutzeroberflächen von Google Docs, Google Sheets und Google Präsentationen angezeigt wird.

Ein Add-on für Google Workspace 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, erstellt und gibt das Add-on eine Startseitenkarte speziell für diesen Editor zurück. Wenn das Manifest des Add-ons nicht den EDITOR_NAME.homepageTrigger für den Editor enthält, in dem der Nutzer das Add-on öffnet, wird stattdessen eine allgemeine Startseitenkarte angezeigt.
**REST API-Oberflächen**: Wenn das Add-on REST APIs verwendet, können Sie Trigger einfügen, die mit dem Bereich drive.file den Zugriff auf eine Datei pro Datei anfordern. Nachdem der Zugriff gewährt wurde, wird ein weiterer Trigger namens EDITOR_NAME.onFileScopeGrantedTrigger ausgeführt und eine für die Datei spezifische Oberfläche angezeigt.
Oberflächen für die Linkvorschau: Wenn Ihr Add-on in einen Drittanbieterdienst eingebunden ist, können Sie Karten erstellen, die eine Vorschau von Inhalten aus den URLs Ihres Dienstes enthalten.

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

So erstellen Sie Oberflächen für Editor-Add-ons für die Editoren:

Fügen Sie dem Manifest des Add-on-Skriptprojekts die entsprechenden addOns.common, addOns.docs, addOns.sheets, und addOns.slides Felder hinzu. manifest.
Fügen Sie dem Manifest des Skriptprojekts alle erforderlichen Editor-Bereiche hinzu.
Wenn Sie eine editorspezifische Startseite bereitstellen, implementieren Sie die EDITOR_NAME.homepageTrigger Funktion, um die Oberfläche zu erstellen. Andernfalls verwenden Sie die common.homepageTrigger Oberfläche, um eine allgemeine Startseite für Ihre Host-Apps zu erstellen.
Wenn Sie REST APIs verwenden, implementieren Sie den drive.file Autorisierungsablauf für den Bereich und EDITOR_NAME.onFileScopeGrantedTrigger Triggerfunktion, um eine für die geöffnete Datei spezifische Oberfläche anzuzeigen. Weitere Informationen finden Sie unter REST API-Oberflächen.
Wenn Sie Linkvorschauen von einem Drittanbieterdienst konfigurieren, implementieren Sie den https://www.googleapis.com/auth/workspace.linkpreview Bereich Autorisierungsablauf und linkPreviewTriggers Funktion. Weitere Informationen finden Sie unter Oberflächen für die Linkvorschau.
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 im Skriptprojekt Ihres Add-ons eine Startseiten-Triggerfunktion bereitstellen, die eine einzelne Card oder ein Array von Card Objekten erstellt und zurückgibt, aus denen die Startseite des Add-ons besteht.

Der Startseiten-Triggerfunktion wird ein Ereignis objekt 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 allgemeine Startseite oder eine Startseite präsentieren, die spezifisch für den Editor ist, in dem der Nutzer Ihr Add-on öffnet.

Allgemeine Startseite anzeigen

Wenn Sie die allgemeine Startseite Ihres Add-ons in den Editoren anzeigen möchten, fügen Sie dem Manifest des Add-ons die entsprechenden Editor-Felder hinzu, z. B. addOns.docs, addOns.sheets oder addOns.slides.

Das folgende Beispiel zeigt den Abschnitt addons eines Add-on-Manifests für Google Workspace. Das Add-on erweitert Google Docs, Google Sheets und Google Präsentationen und zeigt die allgemeine 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 Sie eine editorspezifische Startseite präsentieren möchten, fügen Sie dem Add-on-Manifest EDITOR_NAME.homepageTrigger hinzu.

Das folgende Beispiel zeigt den Abschnitt addons eines Add-on-Manifests für Google Workspace. Das Add-on ist für Google Docs, Google Sheets und Google Präsentationen aktiviert. Es zeigt die allgemeine Startseite in Google Docs und Google Präsentationen und eine eindeutige Startseite in Google Sheets an. Die Callback-Funktion onSheetsHomepage erstellt die spezifische Startseitenkarte für Google Sheets.

 "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-Oberflächen

Wenn Ihr Add-on REST APIs wie die Google Sheets API verwendet, können Sie mit der onFileScopeGrantedTrigger Funktion eine neue Oberfläche anzeigen, die spezifisch für die Datei ist, die in der Editor-Host-App geöffnet ist.

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

Wenn ein Nutzer den drive.file Bereich gewährt, wird EDITOR_NAME.onFileScopeGrantedTrigger.runFunction ausgelöst. Wenn der Trigger ausgelöst wird, wird die kontextbezogene Triggerfunktion ausgeführt, die durch das EDITOR_NAME.onFileScopeGrantedTrigger.runFunction Feld in dem Add-on-Manifest angegeben wird.

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:

Fügen Sie EDITOR_NAME.onFileScopeGrantedTrigger dem entsprechenden Editor-Abschnitt Ihres Manifests hinzu. Wenn Sie diese Oberfläche beispielsweise in Google Sheets erstellen möchten, fügen Sie den Trigger dem "sheets" Abschnitt hinzu.
Implementieren Sie die Funktion, die im EDITOR_NAME.onFileScopeGrantedTrigger Abschnitt genannt ist. Diese Funktion akzeptiert ein Ereignis objekt 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 verwendet werden, um die Widget-Interaktivität für die Oberfläche bereitzustellen. Wenn Sie beispielsweise eine Schaltfläche in die Oberfläche einfügen, sollte sie eine angehängte Aktion und eine implementierte Callback-Funktion haben, die ausgeführt wird, wenn auf die Schaltfläche geklickt wird.

Das folgende Beispiel zeigt den Abschnitt addons eines Add-on-Manifests für Google Workspace. Das Add-on verwendet REST APIs, daher ist onFileScopeGrantedTrigger für Google Sheets enthalten. Wenn ein Nutzer den Bereich drive.file gewährt, erstellt die Callback-Funktion onFileScopeGrantedSheets eine dateispezifische Oberflä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"
      }
    }
  }
}

Oberflächen für die Linkvorschau für Drittanbieterdienste

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 Vorschau von Links 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 werden oder wie das Add-on-Verhalten anderweitig gesteuert wird.

Die vollständige Struktur von Ereignisobjekten wird unter Ereignis objekte beschrieben.

Wenn ein Editor die Host-App des Add-ons ist, enthalten die Ereignisobjekte Docs, Sheets oder Slides Ereignisobjektfelder, die Clientinformationen 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 für Ereignisobjekte des Editors.

Das folgende Beispiel zeigt ein Ereignisobjekt des Editors, das an eine Funktion sheets.onFileScopeGrantedTrigger übergeben wird. Hier hat das Add-on die Autorisierung für den Bereich drive.filefür das aktuelle Dokument:

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

Google-Editor-Oberflächen erstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.