Zum Hauptinhalt springen
Letzte Änderung: 7. Oktober 2025
Sie haben die Möglichkeit, eine React-basierte Einstellungsseite für Ihre App auf der neuesten Version (2025.2) der Entwicklerplattform zu erstellen, zu der Benutzer, die Ihre App installieren, navigieren und diese für ihren Account anpassen können. In dieser Anleitung erfahren Sie, wie Sie mit React eine Einstellungskomponente erstellen, die die vorherigen Einstellungen ersetzt. Wenn Sie Ihre neue Einstellungskomponente einsetzen, wird Benutzern, die Ihre App später installieren, sofort Ihre neue Einstellungserweiterung statt einer zuvor erstellten Einstellungsseite angezeigt. Bevor Sie beginnen, berücksichtigen Sie bitte die Schnellanleitung, um Ihre erste App auf der neuesten Version der Entwicklerplattform zu erstellen.
Hinweis:Wenn Sie bereits eine Einstellungsseite für Ihre App erstellt haben, müssen Sie Ihre Einstellungen mithilfe der in diesem Leitfaden beschriebenen neuen Konfigurationsoptionen verändern. Es wird empfohlen, dass Sie sich alle Oberflächenelemente in der aktuellen Produktionsversion Ihrer App notieren, bevor Sie mit der Konfiguration der neuen Einstellungskomponente auf der neuesten Version der Entwicklerplattform beginnen. Sobald Sie zur neuen Einstellungskomponente für Ihre App wechseln, verlieren Sie nämlich den Zugriff auf die vorherige WYSIWYG-Konfigurationsbenutzeroberfläche, die Sie bislang verwendet haben.

​
Dateien der Einstellungskomponenten erstellen und einrichten

Erstellen Sie zunächst in Ihrem /app-Verzeichnis ein /settings/-Verzeichnis und fügen Sie dann die folgenden drei Dateien hinzu: 
├──src
│   ├── app/
│   │   └── settings/
│   │     └── Settings.tsx
│   │     └── settings-hsmeta.json
│   │     └── package.json
└──
Bearbeiten Sie diese drei Dateien, um den Boilerplate-Code in die folgenden Snippets aufzunehmen.

​
Settings.tsx

import React from 'react';
import { EmptyState, Text } from '@hubspot/ui-extensions';
import { hubspot } from '@hubspot/ui-extensions';

hubspot.extend <
  'settings' >
  (({ context }) => {
    return <Settings context={context} />;
  });

const Settings = ({ context }) => {
  // TODO: Update this JSX code to include the components that fit your settings page.
  return (
    <EmptyState title="Nothing here yet!" layout="vertical">
      <Text>
        Contact '{context.extension.appName}' for upcoming development plans.
      </Text>
    </EmptyState>
  );
};

​
settings-hsmeta.json

{
  "uid": "settings_extension",
  "type": "settings",
  "config": {
    "entrypoint": "/app/settings/Settings.tsx"
  }
}

​
package.json

{
  "name": "hubspot-settings-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}

​
Einstellungskomponente hochladen und installieren

So laden Sie Ihre Einstellungen-Komponente in Ihr Projekt hoch:
  • Führen Sie in Ihrem app/-Verzeichnis hs project install-deps aus, um eine package-lock.json-Datei zu erstellen, die die Erstellung der hochgeladenen Einstellungserweiterung beschleunigt und sicherstellt, dass alle Abhängigkeiten in Ihrer lokalen Entwicklungsumgebung und der Produktion übereinstimmen.
  • Führen Sie dann hs project upload aus. Rufen Sie anschließend die Detailseite Ihres Entwicklerprojekts auf, indem Sie dazu zu Entwicklung > Projekte gehen und dann auf den Namen Ihres Projekts klicken.
  • Ihre Einstellungskomponente sollte jetzt auf der Detailseite aufgeführt sein.
Hochgeladene Einstellungskomponente auf der Projektdetailseite

​
Anzeigen der Einstellungsseite in Ihrem Entwickler-Test-Account

  • Um zu überprüfen, ob die Einstellungskomponente ordnungsgemäß funktioniert, gehen Sie bitte zu dem Entwickler-Test-Account, wo Sie Ihre App installiert haben, klicken dann auf das Marketplace-Symbol und danach auf Verknüpfte Apps.
Zu verknüpften Apps im Entwickler-Test-Account gelangen
  • Klicken Sie auf den Namen Ihrer App, woraufhin Sie auf die Einstellungsseite Ihrer App gelangen sollten.
Komponente „Grundeinstellungen“ ohne Statusangabe im Test-Account
Sie können nun Ihre Einstellungskomponente – genauso wie bei einer App-Karte – weiter erstellen. Alle bestehenden Erstellungseinschränkungen von UI-Erweiterungen gelten auch für das Erstellen einer Einstellungsseite.
  • Verwenden Sie hubspot.fetch, um Ihr Backend zum Speichern und Abrufen von Einstellungen zu nutzen. Erfahren Sie in der älteren Dokumentation mehr über die Anwendung dieses Ansatzes.
  • Informieren Sie sich in der Referenzdokumentation zu Standardkomponenten darüber, wie Sie React-Komponenten beim Erstellen Ihrer Erweiterung verwenden können, oder benutzen Sie die Komponente im Figma Design Kit.
  • Verwenden Sie den hs project dev-Befehl, um Ihre Einstellungsseite iterativ zu erstellen und eine lokale Vorschau Ihrer Änderungen anzuzeigen.

​
Best Practices für Komponente

In den folgenden Abschnitten werden einige bewährte Methoden beschrieben, die Sie beim Erstellen der Einstellungen für Ihre App beachten sollten.

​
Kontakte verwalten

Wenn Sie über so viel Content in Ihrer Einstellungserweiterung verfügen, dass es notwendig ist, alle Einstellungsdaten des Benutzers zu trennen und zu organisieren, sollten Sie die jeweilige Verwendung der Komponenten Panel, Modal, Accordion und Tabs in Betracht ziehen. Überlegen Sie, wie Sie Ihre Einstellungen darstellen und anordnen möchten und welche Daten für jede Komponente abgerufen werden sollen.

​
Registerkarten

Wenn Sie Tabs einsetzen, verwenden Sie bitte die default-Tab-Variante. Die Einstellungserweiterung ist bereits in einem geschlossenen Varianten-Tab enthalten und eine zweite Ebene geschlossener Tabs kollidiert optisch mit dem Design.
Beispiel für verschachtelte Registerkarten auf der Einstellungsseite
Das folgende Snippet zeigt, wie Ihre Tabs strukturiert sein sollten. 
<Tabs>

<Tab title="First Tab">
<Text>Here is the content of the first tab.</Text>
</Tab>
<Tab title="Second Tab">
<Text>This is where the content of the second tab goes.</Text>
</Tab>

</Tabs>
⌘I