Frontendové komponenty

Frontendové komponenty jsou React komponenty, které se vykreslují přímo v uživatelském rozhraní Twenty. Běží v izolovaném Web Workeru s využitím Remote DOM — váš kód se spouští uvnitř sandboxovaného iframe s nejasným původem (opaque-origin), ale jeho UI se stále vykresluje nativně na stránce, místo aby bylo omezené na tento iframe.

Komponenty Front jsou stále aktivně vyvíjeny. Váš kód běží nad částečným DOMem, nikoli nad skutečnou stránkou prohlížeče, takže pokročilé způsoby použití mohou selhávat, často bez zjevných chyb. Viz Aktuální omezení.

Kde lze použít frontendové komponenty

Frontendové komponenty se mohou vykreslovat na třech 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.
Nastavení aplikace — Definovaná pomocí defineSettingsFrontComponent(), frontendová komponenta se vykreslí jako sekce na kartě Settings (Nastavení) aplikace, místo výchozího uživatelského rozhraní pro konfiguraci proměnných.

Samotná frontendová komponenta není z uživatelského rozhraní dostupná — je potřeba ji zpřístupnit. Tři způsoby, jak to udělat, jsou:

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.
Definujte ji pomocí defineSettingsFrontComponent() — vykreslí ji jako sekci na kartě Settings (Nastavení) aplikace, místo výchozího uživatelského rozhraní pro konfiguraci proměnných.

Základní příklad

Nejrychlejší způsob, jak vidět front komponentu v akci, je spárovat ji s defineCommandMenuItem, aby se objevila jako tlačítko rychlé akce v pravém horním rohu stránky:

src/front-components/hello-world.tsx

import { defineFrontComponent } from 'twenty-sdk/define';

const HelloWorld = () => {
  return (
    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
      <h1>Hello from my app!</h1>
      <p>This component renders inside Twenty.</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
  name: 'hello-world',
  description: 'A simple front component',
  component: HelloWorld,
});

src/command-menu-items/hello-world.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-456789012345',
  shortLabel: 'Hello',
  label: 'Hello World',
  isPinned: true,
  availabilityType: 'GLOBAL',
  frontComponentUniversalIdentifier: '74c526eb-cb68-4cf7-b05c-0dd8c288d948',
});

Po synchronizaci pomocí yarn twenty dev (nebo po jednorázovém spuštění yarn twenty apply) se rychlá akce zobrazí v pravém horním rohu stránky:

Tlačítko rychlé akce v pravém horním rohu

Kliknutím na něj vykreslíte komponentu přímo ve stránce.

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.

Vlastní komponenta nastavení

Chcete-li nahradit automaticky generované uživatelské rozhraní pro konfiguraci proměnných na kartě Settings (Nastavení) vaší aplikace vlastní komponentou, definujte ji pomocí defineSettingsFrontComponent místo defineFrontComponent. Používá stejná konfigurační pole (kromě isHeadless, který není podporován, protože komponenta nastavení vždy vykresluje viditelné uživatelské rozhraní) a zároveň označuje komponentu jako uživatelské rozhraní nastavení aplikace. Komponenta se vykreslí jako sekce uvnitř karty Settings, nikoli jako náhrada celé karty. Systémem spravované sekce Twenty — automatická aktualizace, App URL a připojení — se vždy zobrazují nad ní a aplikace je nemůže přebít.

src/front-components/app-settings.tsx

import { defineSettingsFrontComponent } from 'twenty-sdk/define';

const AppSettings = () => {
  return (
    <div style={{ padding: '20px' }}>
      <h2>My app settings</h2>
      {/* render your own configuration UI here */}
    </div>
  );
};

export default defineSettingsFrontComponent({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'app-settings',
  description: "Custom UI for the app's Settings tab",
  component: AppSettings,
});

Na jednu aplikaci je povolena pouze jedna frontová komponenta nastavení; deklarace více než jedné způsobí selhání sestavení. Je-li přítomna, karta Settings aplikace vykreslí tuto komponentu místo výchozího uživatelského rozhraní pro konfiguraci proměnných.

Headless vs. ne-headless

Front-endové komponenty existují ve dvou režimech vykreslování řízených volbou isHeadless: 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

import { defineFrontComponent } from 'twenty-sdk/define';
import { useSelectedRecordIds, enqueueSnackbar } from 'twenty-sdk/front-component';
import { useEffect } from 'react';

const SyncTracker = () => {
  const [recordId] = useSelectedRecordIds();

  useEffect(() => {
    enqueueSnackbar({ message: `Tracking record ${recordId}`, variant: 'info' });
  }, [recordId]);

  return null;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-tracker',
  description: 'Tracks record views silently',
  isHeadless: true,
  component: SyncTracker,
});

Protože komponenta vrací 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íček twenty-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/front-component:

Command — Spustí asynchronní callback přes prop execute.
CommandLink — Naviguje na cestu v aplikaci. Props: to, params, queryParams, options.
CommandModal — Otevře potvrzovací modální okno. Pokud uživatel potvrdí, provede callback execute. Props: title, subtitle, execute, confirmButtonText, confirmButtonAccent.
CommandOpenSidePanelPage — Otevře stránku postranního panelu. Props závisí na page — např. ViewRecord bere recordId + objectNameSingular (plus volitelné id tab pro otevření záznamu na konkrétní záložce), ostatní stránky berou pageTitle + pageIcon.

Zde je kompletní příklad headless front-endové komponenty, která pomocí Command spouští akci z menu příkazů:

src/front-components/run-action.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const RunAction = () => {
  const execute = async () => {
    const client = new CoreApiClient();

    await client.mutation({
      createTask: {
        __args: { data: { title: 'Created by my app' } },
        id: true,
      },
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
  name: 'run-action',
  description: 'Creates a task from the command menu',
  component: RunAction,
  isHeadless: true,
});

src/command-menu-items/run-action.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
  label: 'Run my action',
  frontComponentUniversalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
});

A příklad s použitím CommandModal k vyžádání potvrzení před provedením:

src/front-components/delete-draft.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { CommandModal } from 'twenty-sdk/front-component';

const DeleteDraft = () => {
  const execute = async () => {
    // perform the deletion
  };

  return (
    <CommandModal
      title="Delete draft?"
      subtitle="This action cannot be undone."
      execute={execute}
      confirmButtonText="Delete"
      confirmButtonAccent="danger"
    />
  );
};

export default defineFrontComponent({
  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
  name: 'delete-draft',
  description: 'Deletes a draft with confirmation',
  component: DeleteDraft,
  isHeadless: true,
});

A zde je příklad použití CommandOpenSidePanelPage k otevření aktuálního záznamu v postranním panelu na konkrétní záložce. tab je ID záložky rozvržení stránky (výchozí rozvržení používají ID jako company-tab-emails nebo company-tab-timeline; vlastní rozvržení používají vlastní ID záložky). Pokud ID v rozvržení záznamu neexistuje, místo toho se otevře výchozí záložka:

src/front-components/open-company-emails.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import {
  CommandOpenSidePanelPage,
  SidePanelPages,
  useSelectedRecordIds,
} from 'twenty-sdk/front-component';

const OpenCompanyEmails = () => {
  const selectedRecordIds = useSelectedRecordIds();
  const recordId = selectedRecordIds.length === 1 ? selectedRecordIds[0] : null;

  if (!recordId) {
    return null;
  }

  return (
    <CommandOpenSidePanelPage
      page={SidePanelPages.ViewRecord}
      recordId={recordId}
      objectNameSingular="company"
      tab="company-tab-emails"
      resetNavigationStack={false}
    />
  );
};

export default defineFrontComponent({
  universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
  name: 'open-company-emails',
  description: 'Opens the current company on its Emails tab',
  component: OpenCompanyEmails,
  isHeadless: true,
});

Volání logické funkce

Front komponenty běží v prohlížeči v sandboxovaném Web Workeru uvnitř iframe s nejasným původem (opaque-origin), 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 přes HTTP dostupná na své cestě (route path). RestApiClient považuje cesty začínající na /s/ za aplikační trasy, převede je na URL, ze které jsou vaše funkce poskytovány, a autentizuje je pomocí TWENTY_APP_ACCESS_TOKEN.

V Twenty Cloud jsou logické funkce spouštěné přes HTTP poskytovány na vyhrazené doméně pro každý workspace na adrese https://\<your-workspace-subdomain>.withtwenty.com\<path>. Pro externí volající zkopírujte přesnou URL z nastavení funkce HTTP trigger nebo z karty Settings aplikace.

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

import { RestApiClient } from 'twenty-client-sdk/rest';
import { defineFrontComponent } from 'twenty-sdk/define';
import { Command } from 'twenty-sdk/front-component';

const SyncPrs = () => {
  const execute = async () => {
    await new RestApiClient().post('/s/github/fetch-prs', {
      owner: 'twentyhq',
      repo: 'twenty',
    });
  };

  return <Command execute={execute} />;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'sync-prs',
  description: 'Triggers the fetch-prs logic function',
  isHeadless: true,
  component: SyncPrs,
});

Cesta předaná RestApiClient je httpRouteTriggerSettings.path logické funkce s předponou /s. Ponechte isAuthRequired: true; TWENTY_APP_ACCESS_TOKEN, který Twenty vygeneruje pro vaši komponentu, požadavek autentizuje:

src/logic-functions/fetch-prs.logic-function.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import type { RoutePayload } from 'twenty-sdk/logic-function';

const handler = async (event: RoutePayload) => {
  const { owner, repo } = (event.body ?? {}) as { owner: string; repo: string };
  // ...fetch from GitHub and persist records...
  return { ok: true };
};

export default defineLogicFunction({
  universalIdentifier: '...',
  name: 'fetch-prs',
  handler,
  httpRouteTriggerSettings: {
    path: '/github/fetch-prs',
    httpMethod: 'POST',
    isAuthRequired: true,
  },
});

TWENTY_APP_ACCESS_TOKEN je vložen 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ě.

Volání Twenty REST API

Pro volání aplikačních HTTP tras nebo čtení a zápis záznamů Twenty z front komponenty použijte RestApiClient z twenty-client-sdk/rest. Odesílá cesty /s/... na základní URL funkcí vašeho workspace a všechny ostatní cesty, včetně /rest/..., na TWENTY_API_URL.

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
`resolveUrl(path, options?)`	Převede cestu na její úplnou URL bez odeslání požadavku (pro odkazy)

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:

const client = new RestApiClient({
  baseUrl: 'https://myworkspace.twenty.com',
  token: 'my-token',
});

Neúspěšné požadavky vyvolají RestApiClientError, který zpřístupňuje status, statusText, url a parsované body:

import { RestApiClient, RestApiClientError } from 'twenty-client-sdk/rest';

const client = new RestApiClient();

try {
  const people = await client.get('/rest/people', {
    query: { limit: 10 },
  });
} catch (error) {
  if (error instanceof RestApiClientError) {
    console.error(error.status, error.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

import { defineFrontComponent } from 'twenty-sdk/define';
import {
  useUserId,
  useSelectedRecordIds,
  useFrontComponentId,
} from 'twenty-sdk/front-component';

const RecordInfo = () => {
  const userId = useUserId();
  const [recordId] = useSelectedRecordIds();
  const componentId = useFrontComponentId();

  return (
    <div>
      <p>User: {userId}</p>
      <p>Record: {recordId ?? 'No record context'}</p>
      <p>Component: {componentId}</p>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
  name: 'record-info',
  component: RecordInfo,
});

Dostupné hooky:

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é v defineApplication() s isSecret: false jsou k dispozici ve front-endových komponentách prostřednictvím pomocné funkce getApplicationVariable:

src/front-components/greeting.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { getApplicationVariable } from 'twenty-sdk/front-component';

const Greeting = () => {
  const recipientName = getApplicationVariable('DEFAULT_RECIPIENT_NAME') ?? 'World';

  return <p>Hello, {recipientName}!</p>;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'greeting',
  component: Greeting,
});

Tajné proměnné (isSecret: true) nejsou zpřístupněny front-endovým komponentám. Jsou k dispozici pouze v logických funkcích, které běží na straně serveru. Tím se zabrání odesílání citlivých hodnot, jako jsou API klíče, do prohlížeče.

getApplicationVariable vždy vrací string (nebo undefined), bez ohledu na deklarovaný type proměnné. Řetězec je serializován konzistentně podle typu (logické hodnoty jako "true" / "false", čísla jako desetinné řetězce, pole / objekty jako JSON), ve stejném formátu, jaký používá process.env v logických funkcích — zpracujte jej sami (Number(...), JSON.parse(...), === 'true'). Viz Typy proměnných. Následující systémové proměnné jsou vždy dostupné přes process.env:

Proměnná	Popis
`TWENTY_API_URL`	Základní URL Twenty core API
`TWENTY_APP_ACCESS_TOKEN`	Krátkodobý token s oprávněními omezenými na roli vaší aplikace

`TWENTY_FUNCTIONS_URL`

Twenty také vkládá TWENTY_FUNCTIONS_URL do front komponent a logických funkcí: základní URL, ze které jsou poskytovány vaše logické funkce spouštěné přes HTTP. Existuje proto, že tato URL není vždy samotný server Twenty. V Twenty Cloud jsou aplikační trasy poskytovány na vyhrazené doméně pro každý workspace (https://\<your-workspace-subdomain>.withtwenty.com, nebo hlavní veřejná doména aplikace, pokud je nakonfigurována), aby odpovědi vytvořené aplikací běžely na odděleném původu, a nikoli na původu aplikace Twenty. Self-hostované a lokální instance poskytují aplikační trasy pod předponou /s přímo na serveru a proměnnou nemusí vůbec nastavovat. Protože se základní URL liší podle workspace a instance, váš kód ji nemůže napevno zakódovat — server správnou hodnotu vloží za běhu. Jen zřídka ji potřebujete číst přímo. Volání svých tras provádějte přes RestApiClient s cestou s předponou /s/ a klient za vás URL vyřeší: odstraní předponu /s a zacílí na TWENTY_FUNCTIONS_URL, přičemž pokud proměnná není nastavena, použije jako zálohu \<TWENTY_API_URL>/s. Použijte resolveUrl('/s/\<path>') pro získání absolutní URL bez odeslání požadavku, např. pro odkaz. Proměnnou čtěte přímo pouze při ručním sestavování URL:

const routeUrl = `${process.env.TWENTY_FUNCTIONS_URL || `${process.env.TWENTY_API_URL}/s`}/documents/generate`;

API komunikace s hostitelem

Frontendové komponenty mohou pomocí funkcí z twenty-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

Zde je příklad, který používá hostitelské API k zobrazení snackbaru a zavření postranního panelu po dokončení akce:

src/front-components/archive-record.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { enqueueSnackbar, closeSidePanel, useSelectedRecordIds } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const ArchiveRecord = () => {
  const [recordId] = useSelectedRecordIds();

  const handleArchive = async () => {
    const client = new CoreApiClient();

    await client.mutation({
      updateTask: {
        __args: { id: recordId, data: { status: 'ARCHIVED' } },
        id: true,
      },
    });

    await enqueueSnackbar({
      message: 'Record archived',
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Archive this record?</p>
      <button onClick={handleArchive}>Archive</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
  name: 'archive-record',
  description: 'Archives the current record',
  component: ArchiveRecord,
});

Práce s více záznamy

Použijte useSelectedRecordIds() pro zpracování více vybraných záznamů. To je užitečné pro hromadné operace:

src/front-components/bulk-export.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { useSelectedRecordIds } from 'twenty-sdk/front-component';
import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk/front-component';
import { CoreApiClient } from 'twenty-client-sdk/core';

const BulkExport = () => {
  const selectedRecordIds = useSelectedRecordIds();

  const handleExport = async () => {
    const client = new CoreApiClient();

    for (const recordId of selectedRecordIds) {
      await client.mutation({
        updateTask: {
          __args: { id: recordId, data: { exported: true } },
          id: true,
        },
      });
    }

    await enqueueSnackbar({
      message: `Exported ${selectedRecordIds.length} records`,
      variant: 'success',
    });

    await closeSidePanel();
  };

  return (
    <div style={{ padding: '20px' }}>
      <p>Export {selectedRecordIds.length} selected record(s)?</p>
      <button onClick={handleExport}>Export</button>
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
  name: 'bulk-export',
  description: 'Export selected records',
  component: BulkExport,
});

Zobrazte ji pomocí položky příkazové nabídky omezené na výběry záznamů:

src/command-menu-items/bulk-export.command-menu-item.ts

import { defineCommandMenuItem } from 'twenty-sdk/define';

export default defineCommandMenuItem({
  universalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678902',
  label: 'Bulk Export',
  availabilityType: 'RECORD_SELECTION',
  frontComponentUniversalIdentifier: 'd0e1f2a3-b4c5-6789-defa-012345678901',
});

Veřejné soubory

Frontendové komponenty mohou přistupovat k souborům ze složky aplikace public/ pomocí getPublicAssetUrl:

import { defineFrontComponent } from 'twenty-sdk/define';
import { getPublicAssetUrl } from 'twenty-sdk/utils';

const Logo = () => <img src={getPublicAssetUrl('logo.png')} alt="Logo" />;

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'logo',
  component: Logo,
});

Podrobnosti viz sekci veřejných souborů.

Stylování

Frontendové komponenty podporují více přístupů ke stylování. Můžete použít:

Inline styly — style={{ color: 'red' }}
Komponenty Twenty UI — vlastní knihovna komponent Twenty; podívejte se níže na Používání komponent Twenty UI
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

Používání komponent Twenty UI

Twenty dodává svou knihovnu komponent jako balíček twenty-ui. Frontendové komponenty jej mohou používat pro tlačítka, tagy, stavové štítky, čipy, avatary, ikony, typografii a tokeny motivu, které se automaticky přizpůsobují světlému a tmavému motivu pracovního prostoru.

Instalace

Přidejte balíček do své aplikace, připnutý k verzi, se kterou je dodána vaše instance Twenty:

yarn add twenty-ui@1.0.0-alpha.1

twenty-ui je zabalen do vaší frontendové komponenty při sestavení, takže stačí, aby byl závislostí vaší aplikace — za běhu není třeba nic konfigurovat.

Import komponent

Importujte z odpovídající podcesty místo z kořene balíčku, aby se do vašeho bundlu dostaly jen komponenty, které používáte:

Podcesta	Co exportuje
`twenty-ui/input`	`Button` a formulářové vstupy
`twenty-ui/data-display`	`Tag`, `Status`, `Chip`, `Avatar` a další
`twenty-ui/feedback`	`Callout`, `Banner`, `Info` a další
`twenty-ui/typography`	`H1Title`, `H2Title`, `H3Title`, `Label` a další
`twenty-ui/icon`	Komponenty `Icon*` (např. `IconCheck`)
`twenty-ui/theme-constants`	`ThemeProvider`, `themeCssVariables`

import { defineFrontComponent } from 'twenty-sdk/define';
import { Status, Tag } from 'twenty-ui/data-display';
import { Button } from 'twenty-ui/input';

const StyledWidget = () => {
  return (
    <div style={{ padding: '16px', display: 'flex', gap: '8px' }}>
      <Button title="Click me" onClick={() => alert('Clicked!')} />
      <Tag text="Active" color="green" />
      <Status color="green" text="Online" />
    </div>
  );
};

export default defineFrontComponent({
  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-567890123456',
  name: 'styled-widget',
  component: StyledWidget,
});

Ikony

Importujte jednotlivé ikony z twenty-ui/icon:

import { IconBox, IconCheck } from 'twenty-ui/icon';

Každá pojmenovaná ikona je odstraňována tree-shakingem, takže import několika málo ikon přidá do vašeho bundlu jen minimum navíc. Vyhněte se IconsProvider, useIcons a iconsState — natáhnou celou sadu ikon Tabler (několik MB).

Témování a tokeny motivu

Komponenty Twenty UI se automaticky přizpůsobí světlému a tmavému motivu pracovního prostoru — renderer použije na hostiteli aktivní barevné schéma a komponenty podle něj odvodí své barvy. Chcete-li ve svých vlastních inline stylech používat stejné design tokeny, zavolejte hook useTheme(). Vrací tokeny motivu Twenty (odsazení, barvy, poloměry, písma) napojené na aktivní motiv, aniž by bylo potřeba v komponentě nastavovat ThemeProvider:

import { useTheme } from 'twenty-ui/theme-constants';

const Card = () => {
  const theme = useTheme();

  return (
    <div
      style={{
        padding: theme.spacing[4],
        background: theme.background.secondary,
        color: theme.font.color.primary,
      }}
    >
      Themed card
    </div>
  );
};

Protože useTheme() je hook, čtete tokeny uvnitř těla komponenty, takže hodnoty vždy odrážejí aktuální motiv. Stejná mapa tokenů je také exportována jako konstanta themeCssVariables, ale ve frontendových komponentách preferujte useTheme() — modulová konstanta, která dereferencuje themeCssVariables, může být během extrakce manifestu aplikace nedefinovaná. Chcete-li se explicitně větvit podle aktivního schématu, načtěte jej pomocí useColorScheme() z twenty-sdk/front-component, která vrací 'light' nebo 'dark'.

Aktuální omezení

Komponenty Front jsou aktivně vyvíjeny. Renderování, stylování a obsluha událostí fungují dobře. Cokoli, co sahá mimo samotné renderování (měření prvku, volání metody DOM na refu, vytváření portálu mimo váš strom, práce s úložištěm prohlížeče), dnes chybí nebo je nekompletní a většinou to selhává tiše: bez výjimky a bez chyby TypeScriptu, protože kostra je typovaná proti plnému DOMu prohlížeče. Pokud vás něco z toho blokuje, vytvořte issue, aby to bylo upřednostněno.

Rozvržení a měření

Zatím se nic nemůže samo změřit.

API	Co se stane
`getBoundingClientRect()`, `getClientRects()`	Vyvolá výjimku
`offsetWidth`, `clientWidth`, `scrollWidth`, `offsetTop`, …	Tiše `undefined`, takže `width ?? 0` vrátí `0` a `width > 600` je vždycky false
`ResizeObserver`, `IntersectionObserver`	`ReferenceError` (ochrany pomocí `typeof` fungují)
`window.matchMedia()`, `window.getComputedStyle()`	Vyvolá výjimku
`window.innerWidth`, `innerHeight`, `devicePixelRatio`	Tiše `undefined`
`new MutationObserver(fn)`	Zkonstruuje se, pak `.observe()` vyvolá výjimku

Takže recharts ResponsiveContainer, Floating UI / Popper, virtualizace seznamů a táhnutí pro změnu velikosti zatím nefungují. Místo toho dělejte rozvržení v CSS: váš stylesheet se dostane ke skutečné stránce, takže flexbox, grid, aspect-ratio, clamp() i @container se chovají normálně.

requestAnimationFrame, fetch, setTimeout a queueMicrotask fungují bez prefixu window.. Pouze window.requestAnimationFrame(...) a podobné volání vyvolají výjimku.

Přístup k DOMu

ref vám dává sandboxový prvek, ne HTMLElement.

Co napíšete	Co se stane	Co použít místo toho
`ref.current.focus()`, `.click()`, `.select()`, `.setSelectionRange()`, `.scrollIntoView()`, `video.play()`	Vyvolá výjimku	Řízené komponenty; čtěte hodnoty z `event.target`
`element.classList.add(...)`	Vyvolá výjimku (`classList` je `undefined`)	Sestavte si řetězec `className` sami
`document.getElementById()`, `getElementsByClassName()`, `createTreeWalker()`	Vyvolá výjimku	`querySelector()` / `querySelectorAll()`, které fungují
`document.activeElement`	Vždy `undefined`	Sledujte fokus pomocí `onFocus` / `onBlur`
`\<canvas>`	Nerenderuje nic, žádná chyba	SVG, nebo kreslete offscreen a zobrazte `<img src={dataUrl}>`
`createPortal(node, document.body)`	Nerenderuje nic, zatímco `isConnected` hlásí úspěch	Překryvné prvky inline pomocí `position: absolute`, nebo knihovně předávejte vlastní kontejnerový prvek

Kvůli této mezeře v portálu popovery Radix, Headless UI, MUI a react-select ve výchozím stavu nic nevyrenderují. Většina z nich přijímá prop pro kontejner; nasměrujte ho na prvek, který jste vyrenderovali.

Události

Události myši, ukazatele, dotyku, tažení, klávesnice, fokusu, input/change/submit, scroll/wheel/contextmenu a animationend/transitionend přecházejí do hostitele, plus několik specifických pro prvek: load/error na <img>, schránka a kompozice na <input>/\<textarea>, média na \<video>/\<audio>, toggle na \<details>/\<dialog>. Cokoli dalšího (onAuxClick, onSelect, onInvalid, onReset, onAnimationStart, zachycení ukazatele (pointer capture), onLoad na <img>) je bez varování zahazováno. document.addEventListener() a window.addEventListener() se zaregistrují bez chyby, ale nikdy se nespustí, což je důvod, proč se přetažení zastaví, jakmile ukazatel opustí prvek, na kterém začalo. Ani event.preventDefault() se nepřenáší; odeslání formuláře, dragover/drop a kliknutí na odkazy jsou už za vás ošetřené.

Atributy a stylování

Každý prvek předává své vlastní vlastnosti do hostitelského DOMu (href na \<a>, src/alt na <img>, value/placeholder/disabled na <input> atd.) plus společnou sadu na každém prvku: id, className, style, title, tabIndex, role, draggable a jakýkoli atribut aria-* / data-* (s pomlčkou, takže ariaLabel je zahozena). Cokoli mimo tento rozsah je tiše zahazováno, takže vlastní stav vyjádřete jako data-*. Komponentové CSS, ať už z import './styles.css', CSS-in-JS nebo z prvku \<style>, je do \<head> hostitelské stránky vkládáno bez ohraničení (unscoped). Třídy se tak střetávají s vlastními třídami Twenty (přidávejte jim předpony a nikdy nepište holé div { ... } selektory) a @media se vztahuje k oknu prohlížeče, nikoli k vašemu widgetu (použijte @container s vlastním container-type). Inline propy style nejsou ovlivněny.

Úložiště a síť

localStorage, sessionStorage, IndexedDB, cookies, Cache API a BroadcastChannel nejsou vůbec k dispozici, protože komponenta běží ve workeru na neprůhledném (opaque) původu. Pro uchování stavu zavolejte logickou funkci a použijte její úložiště klíč–hodnota. fetch funguje, s výhradami:

Volání na Twenty API a trasy (routes) vaší aplikace jsou proxyována hostitelem, proto upřednostněte RestApiClient. U proxyovaných volání jsou AbortSignal a ostatní volby RequestInit zahazovány a jsou podporována pouze těla typu string a URLSearchParams.
Jiné původy opouštějí sandbox s Origin: null, takže API třetí strany odpoví jen tehdy, pokud posílá Access-Control-Allow-Origin: *. Místo toho jej volejte z logické funkce.
fetch('/rest/people') se nikdy nespáruje s Twenty API, protože sandbox nemá URL stránky, podle které by vyhodnotil relativní cestu.

Další omezení

Obsah souborů. <input type="file"> poskytuje vašemu handleru pouze metadata souboru, nikoli samotné bajty, takže FileReader a nahrávání zatím nejsou možná.
Payloady drag-and-drop. Události tažení se spouštějí, ale event.dataTransfer je undefined.
Vestavěné moduly Node. fs, path a node:crypto způsobí chybu při sestavení, takže tuto práci přesuňte do logické funkce. Web Crypto, fetch, TextEncoder a URL jsou k dispozici.
\<iframe> je vždy znovu zasandboxováno bez allow-same-origin, takže vložený obsah spoléhající se na vlastní relaci se vykreslí jako odhlášený. Nemá ani onLoad.

Přehled

Aplikace

API

Vlastní hosting

Přispět

Kde lze použít frontendové komponenty

Základní příklad

Konfigurační pole

Umístění frontendové komponenty na stránku

Vlastní komponenta nastavení

Headless vs. ne-headless

Komponenty SDK Command

Volání logické funkce

Volání Twenty REST API

Přístup k běhovému kontextu

Aplikační proměnné

`TWENTY_FUNCTIONS_URL`

API komunikace s hostitelem

Práce s více záznamy

Veřejné soubory

Stylování

Používání komponent Twenty UI

Instalace

Import komponent

Ikony

Témování a tokeny motivu

Aktuální omezení

Rozvržení a měření

Přístup k DOMu

Události

Atributy a stylování

Úložiště a síť

Další omezení

​Kde lze použít frontendové komponenty

​Základní příklad

​Konfigurační pole

​Umístění frontendové komponenty na stránku

​Vlastní komponenta nastavení

​Headless vs. ne-headless

​Komponenty SDK Command

​Volání logické funkce

​Volání Twenty REST API

​Přístup k běhovému kontextu

​Aplikační proměnné

​TWENTY_FUNCTIONS_URL

​API komunikace s hostitelem

​Práce s více záznamy

​Veřejné soubory

​Stylování

​Používání komponent Twenty UI

​Instalace

​Import komponent

​Ikony

​Témování a tokeny motivu

​Aktuální omezení

​Rozvržení a měření

​Přístup k DOMu

​Události

​Atributy a stylování

​Úložiště a síť

​Další omezení

Kde lze použít frontendové komponenty

Základní příklad

Konfigurační pole

Umístění frontendové komponenty na stránku

Vlastní komponenta nastavení

Headless vs. ne-headless

Komponenty SDK Command

Volání logické funkce

Volání Twenty REST API

Přístup k běhovému kontextu

Aplikační proměnné

`TWENTY_FUNCTIONS_URL`

API komunikace s hostitelem

Práce s více záznamy

Veřejné soubory

Stylování

Používání komponent Twenty UI

Instalace

Import komponent

Ikony

Témování a tokeny motivu

Aktuální omezení

Rozvržení a měření

Přístup k DOMu

Události

Atributy a stylování

Úložiště a síť

Další omezení