Wo Front-Komponenten verwendet werden können
Front-Komponenten können an zwei Stellen innerhalb von Twenty gerendert werden:- Seitenpanel — Nicht-Headless-Front-Komponenten werden im rechten Seitenpanel geöffnet. Dies ist das Standardverhalten, wenn eine Front-Komponente über das Befehlsmenü ausgelöst wird.
- Widgets (Dashboards und Datensatzseiten) — Front-Komponenten können als Widgets in Seitenlayouts eingebettet werden. Beim Konfigurieren eines Dashboards oder eines Datensatzseiten-Layouts können Benutzer ein Front-Komponenten-Widget hinzufügen.
Einfaches Beispiel
Der schnellste Weg, eine Frontend-Komponente in Aktion zu sehen, ist, sie als Befehl zu registrieren. Das Hinzufügen einescommand-Felds mit isPinned: true lässt sie als Schnellaktionsschaltfläche oben rechts auf der Seite erscheinen — kein Seitenlayout erforderlich:
src/front-components/hello-world.tsx
yarn twenty dev (oder durch einmaliges Ausführen von yarn twenty dev --once) erscheint die Schnellaktion oben rechts auf der Seite:

Konfigurationsfelder
| Feld | Erforderlich | Beschreibung |
|---|---|---|
universalIdentifier | Ja | Stabile eindeutige ID für diese Komponente |
component | Ja | Eine React-Komponentenfunktion |
name | Nein | Anzeigename |
description | Nein | Beschreibung dessen, was die Komponente macht |
isHeadless | Nein | Auf true setzen, wenn die Komponente keine sichtbare UI hat (siehe unten) |
command | Nein | Die Komponente als Befehl registrieren (siehe unten Befehlsoptionen) |
Eine Frontend-Komponente auf einer Seite platzieren
Über Befehle hinaus können Sie eine Frontend-Komponente direkt in eine Datensatzseite einbetten, indem Sie sie als Widget in einem Seitenlayout hinzufügen. Details finden Sie im Abschnitt definePageLayout.Headless vs. Nicht-Headless
Front-Komponenten gibt es in zwei Rendering-Modi, die durch die OptionisHeadless gesteuert werden:
Nicht-Headless (Standard) — Die Komponente rendert eine sichtbare UI. Wird sie über das Befehlsmenü ausgelöst, öffnet sie sich im Seitenpanel. Dies ist das Standardverhalten, wenn isHeadless false ist oder weggelassen wird.
Headless (isHeadless: true) — Die Komponente wird unsichtbar im Hintergrund gemountet. Sie öffnet das Seitenpanel nicht. Headless-Komponenten sind für Aktionen konzipiert, die Logik ausführen und sich anschließend selbst unmounten — zum Beispiel das Ausführen einer asynchronen Aufgabe, das Navigieren zu einer Seite oder das Anzeigen eines Bestätigungsdialogs. Sie lassen sich gut mit den unten beschriebenen SDK-Command-Komponenten kombinieren.
src/front-components/sync-tracker.tsx
null zurückgibt, überspringt Twenty das Rendern eines Containers dafür — im Layout entsteht kein Leerraum. Die Komponente hat dennoch Zugriff auf alle Hooks und die Host-Kommunikations-API.
SDK-Command-Komponenten
Das Pakettwenty-sdk stellt vier Command-Hilfskomponenten bereit, die für Headless-Front-Komponenten ausgelegt sind. Jede Komponente führt beim Mounten eine Aktion aus, behandelt Fehler durch Anzeige einer Snackbar-Benachrichtigung und unmountet die Front-Komponente nach Abschluss automatisch.
Importieren Sie sie aus twenty-sdk/command:
Command— Führt einen asynchronen Callback über das Propexecuteaus.CommandLink— Navigiert zu einem App-Pfad. Props:to,params,queryParams,options.CommandModal— Öffnet einen Bestätigungsdialog. Bestätigt der Benutzer, wird der Callbackexecuteausgeführt. Props:title,subtitle,execute,confirmButtonText,confirmButtonAccent.CommandOpenSidePanelPage— Öffnet eine bestimmte Seite im Seitenpanel. Props:page,pageTitle,pageIcon.
Command verwendet, um eine Aktion aus dem Befehlsmenü auszuführen:
src/front-components/run-action.tsx
CommandModal verwendet, um vor der Ausführung um Bestätigung zu bitten:
src/front-components/delete-draft.tsx
Zugriff auf den Laufzeitkontext
Verwenden Sie innerhalb Ihrer Komponente SDK-Hooks, um auf den aktuellen Benutzer, den Datensatz und die Komponenteninstanz zuzugreifen:src/front-components/record-info.tsx
| Hook | Gibt zurück | Beschreibung |
|---|---|---|
useUserId() | string oder null | Die ID des aktuellen Benutzers |
useRecordId() | string oder null | Die ID des aktuellen Datensatzes (wenn auf einer Datensatzseite platziert) |
useFrontComponentId() | Zeichenkette | Die ID dieser Komponenteninstanz |
useFrontComponentExecutionContext(selector) | variiert | Zugriff auf den vollständigen Ausführungskontext mit einer Selektorfunktion |
Host-Kommunikations-API
Frontend-Komponenten können Navigation, Modals und Benachrichtigungen mittels Funktionen austwenty-sdk auslösen:
| Funktion | Beschreibung |
|---|---|
navigate(to, params?, queryParams?, options?) | Zu einer Seite in der App navigieren |
openSidePanelPage(params) | Ein Seitenpanel öffnen |
closeSidePanel() | Seitenpanel schließen |
openCommandConfirmationModal(params) | Einen Bestätigungsdialog anzeigen |
enqueueSnackbar(params) | Eine Toast-Benachrichtigung anzeigen |
unmountFrontComponent() | Die Komponente entfernen |
updateProgress(progress) | Einen Fortschrittsindikator aktualisieren |
src/front-components/archive-record.tsx
Befehlsoptionen
Das Hinzufügen einescommand-Felds zu defineFrontComponent registriert die Komponente im Befehlsmenü (Cmd+K). Wenn isPinned true ist, erscheint sie außerdem als Schnellaktionsschaltfläche oben rechts auf der Seite.
| Feld | Erforderlich | Beschreibung |
|---|---|---|
universalIdentifier | Ja | Stabile eindeutige ID für den Befehl |
label | Ja | Vollständiges Label, das im Befehlsmenü (Cmd+K) angezeigt wird |
shortLabel | Nein | Kürzeres Label, das auf der angehefteten Schnellaktionsschaltfläche angezeigt wird |
icon | Nein | Neben dem Label angezeigter Icon-Name (z. B. ‘IconBolt’, ‘IconSend’) |
isPinned | Nein | Bei true wird der Befehl als Schnellaktionsschaltfläche oben rechts auf der Seite angezeigt |
availabilityType | Nein | Steuert, wo der Befehl erscheint: ‘GLOBAL’ (immer verfügbar), ‘RECORD_SELECTION’ (nur wenn Datensätze ausgewählt sind) oder ‘FALLBACK’ (wird angezeigt, wenn keine anderen Befehle passen) |
availabilityObjectUniversalIdentifier | Nein | Beschränken Sie den Befehl auf Seiten eines bestimmten Objekttyps (z. B. nur bei Company-Datensätzen) |
conditionalAvailabilityExpression | Nein | Ein boolescher Ausdruck, um dynamisch zu steuern, ob der Befehl sichtbar ist (siehe unten) |
Bedingte Verfügbarkeitsausdrücke
Mit dem FeldconditionalAvailabilityExpression können Sie basierend auf dem aktuellen Seitenkontext steuern, wann ein Befehl sichtbar ist. Importieren Sie typisierte Variablen und Operatoren aus twenty-sdk, um Ausdrücke zu erstellen:
| Variable | Typ | Beschreibung |
|---|---|---|
pageType | Zeichenkette | Aktueller Seitentyp (z. B. ‘RecordIndexPage’, ‘RecordShowPage’) |
isInSidePanel | boolean | Ob die Komponente in einem Seitenpanel gerendert wird |
numberOfSelectedRecords | number | Anzahl der aktuell ausgewählten Datensätze |
isSelectAll | boolean | Ob „Alle auswählen“ aktiv ist |
selectedRecords | array | Die ausgewählten Datensatzobjekte |
favoriteRecordIds | array | IDs der favorisierten Datensätze |
objectPermissions | object | Berechtigungen für den aktuellen Objekttyp |
targetObjectReadPermissions | object | Leseberechtigungen für das Zielobjekt |
targetObjectWritePermissions | object | Schreibberechtigungen für das Zielobjekt |
featureFlags | object | Aktive Feature-Flags |
objectMetadataItem | object | Metadaten des aktuellen Objekttyps |
hasAnySoftDeleteFilterOnView | boolean | Ob die aktuelle Ansicht einen Soft-Delete-Filter hat |
| Operator | Beschreibung |
|---|---|
isDefined(value) | true, wenn der Wert nicht null/undefined ist |
isNonEmptyString(value) | true, wenn der Wert eine nicht leere Zeichenfolge ist |
includes(array, value) | true, wenn das Array den Wert enthält |
includesEvery(array, prop, value) | true, wenn die Eigenschaft jedes Elements den Wert enthält |
every(array, prop) | true, wenn die Eigenschaft bei jedem Element truthy ist |
everyDefined(array, prop) | true, wenn die Eigenschaft bei jedem Element definiert ist |
everyEquals(array, prop, value) | true, wenn die Eigenschaft bei jedem Element dem Wert entspricht |
some(array, prop) | true, wenn die Eigenschaft bei mindestens einem Element truthy ist |
someDefined(array, prop) | true, wenn die Eigenschaft bei mindestens einem Element definiert ist |
someEquals(array, prop, value) | true, wenn die Eigenschaft bei mindestens einem Element dem Wert entspricht |
someNonEmptyString(array, prop) | true, wenn die Eigenschaft bei mindestens einem Element eine nicht leere Zeichenfolge ist |
none(array, prop) | true, wenn die Eigenschaft bei jedem Element falsy ist |
noneDefined(array, prop) | true, wenn die Eigenschaft bei jedem Element undefined ist |
noneEquals(array, prop, value) | true, wenn die Eigenschaft bei keinem Element dem Wert entspricht |
Öffentliche Assets
Frontend-Komponenten können mitgetPublicAssetUrl auf Dateien aus dem public/-Verzeichnis der App zugreifen:
Styling
Frontend-Komponenten unterstützen mehrere Styling-Ansätze. Sie können verwenden:- Inline-Styles —
style={{ color: 'red' }} - Twenty-UI-Komponenten — Import aus
twenty-sdk/ui(Button, Tag, Status, Chip, Avatar und mehr) - Emotion — CSS-in-JS mit
@emotion/react - Styled-components —
styled.div-Muster - Tailwind CSS — Utility-Klassen
- Beliebige CSS-in-JS-Bibliothek, die mit React kompatibel ist