Kde lze použít frontendové komponenty
Frontendové komponenty se mohou vykreslovat na dvou místech v rámci Twenty:- Postranní panel — Frontendové komponenty, které nejsou headless, se otevírají v pravém postranním panelu. Toto je výchozí chování, když je frontendová komponenta vyvolána z příkazového menu.
- Widgety (nástěnky a stránky záznamů) — front komponenty lze vkládat jako widgety do rozložení stránky. Při konfiguraci nástěnky nebo rozložení stránky záznamu mohou uživatelé přidat widget frontendové komponenty.
- Spárujte ji s položkou příkazové nabídky — zaregistruje ji v příkazové nabídce (Cmd+K) a volitelně také jako připnutou rychlou akci.
- Vložte ji jako widget do rozložení stránky — umístí ji na detailní stránku záznamu nebo na nástěnku.
Základní příklad
Nejrychlejší způsob, jak vidět front komponentu v akci, je spárovat ji sdefineCommandMenuItem, aby se objevila jako tlačítko rychlé akce v pravém horním rohu stránky:
src/front-components/hello-world.tsx
src/command-menu-items/hello-world.command-menu-item.ts
yarn twenty dev (nebo po jednorázovém spuštění yarn twenty dev --once) se rychlá akce zobrazí v pravém horním rohu stránky:

Konfigurační pole
| Pole | Povinné | Popis |
|---|---|---|
universalIdentifier | Ano | Stabilní jedinečné ID pro tuto komponentu |
component | Ano | Funkce komponenty React |
name | Ne | Zobrazovaný název |
description | Ne | Popis toho, co komponenta dělá |
isHeadless | Ne | Nastavte na true, pokud komponenta nemá viditelné UI (viz níže) |
Umístění frontendové komponenty na stránku
Mimo příkazy můžete frontendovou komponentu vložit přímo na stránku záznamu přidáním jako widget v rozvržení stránky. Podrobnosti viz Rozložení stránek.Headless vs. ne-headless
Front-endové komponenty existují ve dvou režimech vykreslování řízených volbouisHeadless:
Ne-headless (výchozí) — Komponenta vykreslí viditelné uživatelské rozhraní. Po vyvolání z menu příkazů se otevře v postranním panelu. Toto je výchozí chování, když je isHeadless false nebo když tato volba není uvedena.
Headless (isHeadless: true) — Komponenta se neviditelně inicializuje na pozadí. Neotevírá postranní panel. Headless komponenty jsou určené pro akce, které provedou logiku a poté se odpojí — například spuštění asynchronního úkolu, navigaci na stránku nebo zobrazení potvrzovacího modálního okna. Přirozeně se hodí ke komponentám SDK Command popsaným níže.
src/front-components/sync-tracker.tsx
null, Twenty přeskočí vykreslení kontejneru — v rozvržení se neobjeví žádné prázdné místo. Komponenta má však stále přístup ke všem hookům a API komunikace s hostitelem.
Komponenty SDK Command
Balíčektwenty-sdk poskytuje čtyři pomocné komponenty Command navržené pro headless front-endové komponenty. Každá komponenta při připojení provede akci, chyby zpracuje zobrazením oznámení ve snackbaru a po dokončení automaticky odpojí front-endovou komponentu.
Importujte je z twenty-sdk/command:
Command— Spustí asynchronní callback přes propexecute.CommandLink— Naviguje na cestu v aplikaci. Props:to,params,queryParams,options.CommandModal— Otevře potvrzovací modální okno. Pokud uživatel potvrdí, provede callbackexecute. Props:title,subtitle,execute,confirmButtonText,confirmButtonAccent.CommandOpenSidePanelPage— Otevře konkrétní stránku postranního panelu. Props:page,pageTitle,pageIcon.
Command spouští akci z menu příkazů:
src/front-components/run-action.tsx
src/command-menu-items/run-action.command-menu-item.ts
CommandModal k vyžádání potvrzení před provedením:
src/front-components/delete-draft.tsx
Volání logické funkce
Front komponenty běží v prohlížeči v izolovaném web workeru, zatímco logické funkce běží na serveru. Neexistuje mezi nimi žádné přímé volání v rámci jednoho procesu — místo toho se front komponenta k logické funkci připojuje přes HTTP. Logická funkce deklarovaná pomocíhttpRouteTriggerSettings je vystavena pod endpointem /s/ na ${TWENTY_API_URL}/s\<path>. Vaše front komponenta volá tuto trasu pomocí RestApiClient z twenty-client-sdk/rest, který se autentizuje pomocí TWENTY_APP_ACCESS_TOKEN, který Twenty do workeru vkládá.
RestApiClient je přesně pro tento účel. Z worker prostředí čte TWENTY_API_URL a TWENTY_APP_ACCESS_TOKEN, přidává hlavičku Authorization: Bearer, serializuje a parsuje JSON a vyhazuje RestApiClientError, pokud token nebo URL chybí nebo je odpověď mimo rozsah 2xx — takže nemusíte tento boilerplate znovu implementovat v každé komponentě.
Headless front komponenta může volání spustit při mountu přes komponentu Command a poté se automaticky odmountovat:
src/front-components/sync-prs.tsx
httpRouteTriggerSettings.path logické funkce s předponou /s. Ponechte isAuthRequired: true; klient poskytuje pro vaši komponentu přístupový token aplikace vydaný Twenty:
src/logic-functions/fetch-prs.logic-function.ts
TWENTY_API_URL a TWENTY_APP_ACCESS_TOKEN jsou vloženy automaticky — viz Proměnné aplikace. Protože tajné proměnné aplikace nejsou nikdy vystaveny front komponentám, ponechte API klíče a další citlivou logiku v logické funkci, ne ve front komponentě.Reference RestApiClient
Importujte RestApiClient z twenty-client-sdk/rest. Patří do stejné rodiny klientů jako CoreApiClient a MetadataApiClient, ale cílí na HTTP trasy vaší aplikace místo na GraphQL API.
| Metoda | Popis |
|---|---|
get(path, options?) | Odešle požadavek GET |
post(path, body?, options?) | Odešle požadavek POST |
put(path, body?, options?) | Odešle požadavek PUT |
patch(path, body?, options?) | Odešle požadavek PATCH |
delete(path, options?) | Odešle požadavek DELETE |
request(method, path, options?) | Obecný požadavek s libovolnou metodou HTTP |
options přijímá headers, query (záznam parametrů dotazovacího řetězce; hodnoty typu nullish jsou vynechány) a AbortSignal prostřednictvím signal. Objekt body, který není typu FormData, je automaticky serializován do JSON. Při 401 klient jednou obnoví přístupový token prostřednictvím hostitele a požadavek znovu odešle.
Základní URL a token jsou ve výchozím nastavení odvozeny z prostředí. Podle potřeby předávejte konstruktoru přepsané hodnoty — například v testech:
RestApiClientError, který zpřístupňuje status, statusText, url a parsované body:
Přístup k běhovému kontextu
Uvnitř komponenty použijte hooky SDK pro přístup k aktuálnímu uživateli, záznamu a instanci komponenty:src/front-components/record-info.tsx
| Hook | Vrací | Popis |
|---|---|---|
useUserId() | string nebo null | ID aktuálního uživatele |
useSelectedRecordIds() | string[] | Všechna vybraná ID záznamů (prázdné pole, pokud není nic vybráno) |
useRecordId() | string nebo null | Zastaralé. Použijte místo toho useSelectedRecordIds() |
useFrontComponentId() | string | ID této instance komponenty |
useColorScheme() | 'light' nebo 'dark' | Aktivní barevné schéma uživatelského rozhraní hostitele (System je již vyhodnocen) |
useFrontComponentExecutionContext(selector) | různé | Přístup k úplnému kontextu běhu pomocí selektorové funkce |
Aplikační proměnné
Aplikační proměnné definované vdefineApplication() s isSecret: false jsou k dispozici ve front-endových komponentách prostřednictvím pomocné funkce getApplicationVariable:
src/front-components/greeting.tsx
process.env:
| Proměnná | Popis |
|---|---|
TWENTY_API_URL | Základní URL Twenty API |
TWENTY_APP_ACCESS_TOKEN | Krátkodobý token s oprávněními omezenými na roli vaší aplikace |
API komunikace s hostitelem
Frontendové komponenty mohou pomocí funkcí ztwenty-sdk vyvolávat navigaci, modály a oznámení:
| Funkce | Popis |
|---|---|
navigate(to, params?, queryParams?, options?) | Přejít na stránku v aplikaci |
openSidePanelPage(params) | Otevřít postranní panel |
closeSidePanel() | Zavřít postranní panel |
openCommandConfirmationModal(params) | Zobrazit potvrzovací dialog |
enqueueSnackbar(params) | Zobrazit oznámení typu toast |
unmountFrontComponent() | Odpojit komponentu |
updateProgress(progress) | Aktualizovat indikátor průběhu |
src/front-components/archive-record.tsx
Práce s více záznamy
PoužijteuseSelectedRecordIds() pro zpracování více vybraných záznamů. To je užitečné pro hromadné operace:
src/front-components/bulk-export.tsx
Veřejné soubory
Frontendové komponenty mohou přistupovat k souborům ze složky aplikacepublic/ pomocí getPublicAssetUrl:
Stylování
Frontendové komponenty podporují více přístupů ke stylování. Můžete použít:- Inline styly —
style={{ color: 'red' }} - Komponenty Twenty UI — import z
twenty-sdk/ui(Button, Tag, Status, Chip, Avatar a další) - Emotion — CSS-in-JS s
@emotion/react - Styled-components — vzory
styled.div - Tailwind CSS — utilitní třídy
- Jakákoli CSS-in-JS knihovna kompatibilní s Reactem