Google Editor-Oberflächen erstellen

Mit Google Workspace-Add-ons können Sie benutzerdefinierte Benutzeroberflächen innerhalb der Editoren, einschließlich Google Docs, Tabellen und Präsentationen. So können Sie den Nutzenden relevante Informationen abrufen, Aufgaben automatisieren und Drittanbietersysteme Redakteure.

Auf die Add-on-UI zugreifen

Sie können ein Google Workspace-Add-on in den Editoren öffnen wenn das Symbol in der Google Workspace-Schnellinfo Auf die Seitenleiste rechts von Nutzern von Google Docs, Google Tabellen oder Google Präsentationen zugreifen Schnittstellen.

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

  • Startseiten: wenn das Manifest des Add-ons enthält den Trigger EDITOR_NAME.homepageTrigger für den Editor, in dem der Nutzer das Add-on öffnet, erstellt das Add-on und gibt Startseitenkarte speziell für Bearbeiter. Wenn das Manifest des Add-ons das Tag EDITOR_NAME.homepageTrigger für den Bearbeiter, der vom Nutzer geöffnet wird stattdessen eine allgemeine Infokarte auf der Startseite.

  • REST API-Schnittstellen: wenn das Add-on REST verwendet APIs können Sie Trigger einbinden, die Zugriff pro Datei auf ein Dokument anfordern mit dem Bereich drive.file. Nach der Erteilung wird ein anderer Trigger namens EDITOR_NAME.onFileScopeGrantedTrigger führt und zeigt eine für die Datei spezifische Oberfläche an.

  • Linkvorschau: Wenn Ihr Add-on in den Dienst eines Drittanbieters integriert ist, können Sie Karten erstellen, von den URLs Ihres Dienstes aus.

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

Build Editor-Add-on-Oberflächen für Bearbeiter. Gehen Sie dazu so vor:

  1. Fügen Sie die entsprechenden addOns.common, addOns.docs addOns.sheets und addOns.slides. Manifest für das Add-on-Skriptprojekt hinzu.
  2. Fügen Sie alle erforderlichen Editor-Bereiche hinzu: das Manifest Ihres Skriptprojekts.
  3. Wenn Sie eine Editor-spezifische Startseite bereitstellen, Implementieren der EDITOR_NAME.homepageTrigger um die Schnittstelle zu erstellen. Ist dies nicht der Fall, verwenden Sie common.homepageTrigger um eine gemeinsame Startseite für Ihre Host-Apps zu erstellen.
  4. Wenn Sie REST APIs verwenden, implementieren Sie den Autorisierungsvorgang für den Bereich drive.file. und EDITOR_NAME.onFileScopeGrantedTrigger Triggerfunktion, um eine für die geöffnete Datei spezifische Schnittstelle anzuzeigen. Weitere Informationen Weitere Informationen
  5. Wenn Sie die Linkvorschau eines Drittanbieterdienstes konfigurieren, implementieren Sie den Autorisierungsablauf für den https://www.googleapis.com/auth/workspace.linkpreview-Bereich und linkPreviewTriggers . Weitere Informationen finden Sie unter Vorschauoberflächen für Links:
  6. Implementieren Sie die zugehörigen Callback-Funktionen, die zum Antworten auf die Callback-Funktion des Nutzers erforderlich sind. Interaktionen auf der Benutzeroberfläche, z. B. Klicks auf Schaltflächen

Editor-Startseiten

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

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

Sie können eine gemeinsame Startseite oder eine für den Bearbeiter spezifische Startseite präsentieren. wenn die Nutzenden Ihr Add-on öffnen.

Allgemeine Startseite anzeigen

Damit die allgemeine Startseite Ihres Add-ons in den Editoren angezeigt wird, fügen Sie die entsprechenden Editor-Felder, z. B. addOns.docs, addOns.sheets oder addOns.slides, im Manifest des Add-ons.

Das folgende Beispiel zeigt den addons-Teil eines Google Workspace-Add-ons. Manifests. Das Add-on ist eine Erweiterung von Google Docs, Google Tabellen und Google Präsentationen und zeigt die gängigen Startseite in jeder Host-App.

 "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 spezielle Startseite für einen Bearbeiter präsentieren möchten, fügen Sie dem Add-on das EDITOR_NAME.homepageTrigger hinzu Manifests.

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 allgemeinen die Startseite in Google Docs und Google Präsentationen und eine eigene Startseite in Google Tabellen. Der Callback mit der Funktion onSheetsHomepage die Startseitenkarte für Google Tabellen erstellen.

 "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 das Add-on REST APIs wie die Google Sheets API verwendet, können Sie mit der onFileScopeGrantedTrigger-Funktion eine neue Oberfläche anzeigen. für die Datei, die in der Editor-Host-App geöffnet ist.

Sie müssen den Autorisierungsvorgang für den Bereich drive.file einschließen, um die onFileScopeGrantedTrigger. So beantragst du die drive.file Informationen hierzu finden Sie unter Dateizugriff für das aktuelle Dokument anfordern.

Wenn ein Nutzer den Bereich drive.file gewährt, wird der EDITOR_NAME.onFileScopeGrantedTrigger.runFunction Bränden. Wenn der Trigger ausgelöst wird, führt er die kontextbezogene Triggerfunktion aus die durch das Feld EDITOR_NAME.onFileScopeGrantedTrigger.runFunction im Add-on-Manifests.

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-Host-App, die Sie auswählen möchten. Verwenden Sie z. B. sheets.onFileScopeGrantedTrigger.

  1. Fügen Sie den EDITOR_NAME.onFileScopeGrantedTrigger ein. im entsprechenden Editor-Abschnitt deines Manifests. Wenn Sie beispielsweise wenn Sie diese Oberfläche in Google Tabellen erstellen möchten, Abschnitt "sheets"
  2. Funktion in EDITOR_NAME.onFileScopeGrantedTrigger implementieren . Diese Funktion akzeptiert ein Ereignisobjekt als Argument und muss entweder ein einzelnes Card -Objekt oder ein Array von Card-Objekten.
  3. Wie bei jeder Karte musst du die Callback-Funktionen implementieren, die verwendet werden, um Widget-Interaktivität für die Benutzeroberfläche. Wenn Sie beispielsweise eine Schaltfläche sollte sie über eine angehängte Action und eine implementierte Callback-Funktion verfügen, die ausgeführt wird, wenn die Schaltfläche angeklickt 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. Wenn ein Nutzer den Bereich drive.file gewährt, wird die Callback-Funktion onFileScopeGrantedSheets erstellt 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 Verknüpfung konfigurieren im Manifest Ihres Add-ons eine Vorschau ansehen und eine Funktion erstellen, die eine Vorschau zurückgibt . Für Dienste, die eine Nutzerautorisierung erfordern, muss Ihre Funktion außerdem Autorisierungsprozess durchlaufen.

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. Die Trigger-Funktion verwendet die Informationen aus der Ereignisobjekt, um zu bestimmen, wie Add-on-Karten konstruiert werden oder wie die Funktion wie das Add-on funktioniert.

Die vollständige Struktur der Ereignisobjekte wird unter Ereignisobjekte beschrieben.

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

Wenn das Add-on für den aktuellen Nutzer keine Bereichsautorisierung mit drive.file hat oder Dokument enthält, enthält das Ereignisobjekt nur das Objekt docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission oder slides.addonHasFileScopePermission. Wenn das Add-on -Autorisierung enthält das Ereignisobjekt alle Editor-Ereignisobjektfelder.

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

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