Dove possono essere utilizzati i componenti front-end
I componenti front-end possono essere renderizzati in due posizioni all’interno di Twenty:- Pannello laterale — I componenti front-end non headless si aprono nel pannello laterale destro. Questo è il comportamento predefinito quando un componente front-end viene avviato dal menu comandi.
- Widget (dashboard e pagine dei record) — I componenti front possono essere incorporati come widget all’interno dei layout di pagina. Quando si configura una dashboard o il layout di una pagina record, gli utenti possono aggiungere un widget del componente front-end.
- Associarlo a un elemento di menu dei comandi — lo registra nel menu dei comandi (Cmd+K) e, facoltativamente, come azione rapida fissata.
- Incorporarlo come widget in un layout di pagina — lo posiziona nella pagina dei dettagli di un record o in una dashboard.
Esempio di base
Il modo più rapido per vedere un componente front in azione è associarlo adefineCommandMenuItem, così appare come pulsante di azione rapida nell’angolo in alto a destra della pagina:
src/front-components/hello-world.tsx
src/command-menu-items/hello-world.command-menu-item.ts
yarn twenty dev (o eseguendo una volta sola yarn twenty apply), l’azione rapida appare nell’angolo in alto a destra della pagina:

Campi di configurazione
| Campo | Obbligatorio | Descrizione |
|---|---|---|
universalIdentifier | Sì | ID univoco stabile per questo componente |
component | Sì | Una funzione di componente React |
name | No | Nome visualizzato |
description | No | Descrizione di ciò che fa il componente |
isHeadless | No | Imposta su true se il componente non ha una UI visibile (vedi sotto) |
Posizionare un componente front-end su una pagina
Oltre ai comandi, puoi incorporare un componente front-end direttamente in una pagina record aggiungendolo come widget in un layout di pagina. Vedi Layout di pagina per i dettagli.Headless vs non headless
I componenti front-end prevedono due modalità di rendering controllate dall’opzioneisHeadless:
Non headless (predefinito) — Il componente renderizza un’interfaccia utente visibile. Quando viene avviato dal menu comandi, si apre nel pannello laterale. Questo è il comportamento predefinito quando isHeadless è false o omesso.
Headless (isHeadless: true) — Il componente viene montato in modo invisibile in background. Non apre il pannello laterale. I componenti headless sono pensati per azioni che eseguono una logica e poi si smontano — ad esempio, eseguire un’attività asincrona, navigare a una pagina o mostrare una finestra modale di conferma. Si abbinano naturalmente ai componenti Command dell’SDK descritti di seguito.
src/front-components/sync-tracker.tsx
null, Twenty evita di renderizzare un contenitore per esso — non appare alcuno spazio vuoto nel layout. Il componente ha comunque accesso a tutti gli hook e all’API di comunicazione con l’host.
Componenti Command dell’SDK
Il pacchettotwenty-sdk fornisce quattro componenti di supporto Command progettati per i componenti front-end headless. Ogni componente esegue un’azione al montaggio, gestisce gli errori mostrando una notifica snackbar e smonta automaticamente il componente front-end al termine.
Importali da twenty-sdk/front-component:
Command— Esegue una callback asincrona tramite la propexecute.CommandLink— Naviga verso un percorso dell’app. Props:to,params,queryParams,options.CommandModal— Apre una finestra modale di conferma. Se l’utente conferma, esegue la callbackexecute. Props:title,subtitle,execute,confirmButtonText,confirmButtonAccent.CommandOpenSidePanelPage— Apre una pagina del pannello laterale. Le props dipendono dapage— ad esempioViewRecordaccettarecordId+objectNameSingular, altre pagine accettanopageTitle+pageIcon.
Command per eseguire un’azione dal menu comandi:
src/front-components/run-action.tsx
src/command-menu-items/run-action.command-menu-item.ts
CommandModal per chiedere conferma prima di eseguire:
src/front-components/delete-draft.tsx
Chiamare una funzione logica
I componenti front vengono eseguiti lato browser in un Web Worker in sandbox all’interno di un iframe con origine opaca, mentre le funzioni logiche vengono eseguite lato server. Non esiste una chiamata diretta in-process tra i due; invece, un front component chiama una funzione logica tramite HTTP. Una funzione logica dichiarata conhttpRouteTriggerSettings è raggiungibile tramite HTTP al relativo percorso della route. Twenty inietta nel worker l’URL di base da cui vengono servite le tue funzioni come TWENTY_FUNCTIONS_URL, insieme al TWENTY_APP_ACCESS_TOKEN che autentica la chiamata. Non esiste ancora un client SDK dedicato per invocare le proprie funzioni, quindi chiamale con un semplice fetch:
Su Twenty Cloud, le funzioni logiche attivate tramite HTTP sono servite su un dominio dedicato per ogni workspace inUn front component headless può eseguire la chiamata al mount tramite il componentehttps://\<your-workspace-subdomain>.withtwenty.com\<path>— questo è esattamente ciò in cui viene risoltoTWENTY_FUNCTIONS_URL. Per i chiamanti esterni, copia l’URL esatto dalle impostazioni del trigger HTTP della funzione o dalla scheda Settings dell’applicazione.
Command, quindi smontarsi automaticamente:
src/front-components/sync-prs.tsx
TWENTY_FUNCTIONS_URL è il httpRouteTriggerSettings.path della funzione logica. Mantieni isAuthRequired: true; il TWENTY_APP_ACCESS_TOKEN che Twenty genera per il tuo componente autentica la richiesta:
src/logic-functions/fetch-prs.logic-function.ts
TWENTY_FUNCTIONS_URL e TWENTY_APP_ACCESS_TOKEN vengono inseriti automaticamente — vedi Variabili dell’applicazione. Poiché le variabili di applicazione segrete non vengono mai esposte ai front component, mantieni le chiavi API e altra logica sensibile all’interno della funzione logica, non nel front component.Chiamare le Twenty REST API
Per leggere o scrivere record di Twenty da un front component, usaRestApiClient da twenty-client-sdk/rest. Appartiene alla stessa famiglia di client di CoreApiClient e MetadataApiClient, ma si rivolge alle Twenty REST API (/rest/...) invece della GraphQL API, leggendo il suo URL di base da TWENTY_API_URL.
| Metodo | Descrizione |
|---|---|
get(path, options?) | Invia una richiesta GET |
post(path, body?, options?) | Invia una richiesta POST |
put(path, body?, options?) | Invia una richiesta PUT |
patch(path, body?, options?) | Invia una richiesta PATCH |
delete(path, options?) | Invia una richiesta DELETE |
request(method, path, options?) | Richiesta generica con qualsiasi metodo HTTP |
options accetta headers, query (un record di parametri della query string; i valori nullish vengono ignorati) e un AbortSignal tramite signal. Un oggetto body non-FormData viene serializzato automaticamente in JSON. In caso di 401, il client aggiorna il token di accesso una volta tramite l’host e ritenta la richiesta.
L’URL di base e il token vengono risolti dall’ambiente per impostazione predefinita. Passa gli override al costruttore quando necessario — per esempio nei test:
RestApiClientError che espone status, statusText, url e il body analizzato:
Accesso al contesto di runtime
All’interno del tuo componente, usa gli hook dell’SDK per accedere all’utente corrente, al record e all’istanza del componente:src/front-components/record-info.tsx
| Hook | Restituisce | Descrizione |
|---|---|---|
useUserId() | string o null | L’ID dell’utente corrente |
useSelectedRecordIds() | string[] | Tutti gli ID dei record selezionati (array vuoto se nessuno è selezionato) |
useRecordId() | string o null | Deprecato. Usa useSelectedRecordIds() al suo posto |
useFrontComponentId() | string | L’ID di questa istanza di componente |
useColorScheme() | 'light' o 'dark' | Lo schema di colori attivo dell’interfaccia utente dell’host (System è già stato risolto) |
useFrontComponentExecutionContext(selector) | varia | Accedi all’intero contesto di esecuzione con una funzione selettore |
Variabili dell’applicazione
Le variabili dell’applicazione definite indefineApplication() con isSecret: false sono disponibili all’interno dei componenti front-end tramite l’utility getApplicationVariable:
src/front-components/greeting.tsx
getApplicationVariable restituisce sempre una stringa (o undefined), indipendentemente dal type dichiarato della variabile. La stringa viene serializzata in modo coerente in base al tipo (booleani come "true" / "false", numeri come stringhe decimali, array / oggetti come JSON), lo stesso formato usato per la logic-function process.env — esegui il parsing manualmente (Number(...), JSON.parse(...), === 'true'). Vedi Tipi di variabili.
Le seguenti variabili di sistema sono sempre disponibili tramite process.env:
| Variabile | Descrizione |
|---|---|
TWENTY_FUNCTIONS_URL | URL di base da cui vengono servite le funzioni di logica HTTP della tua app |
TWENTY_API_URL | URL di base dell’API Core di Twenty |
TWENTY_APP_ACCESS_TOKEN | Token di breve durata con ambito limitato al ruolo della tua app |
API di comunicazione con l’host
I componenti front-end possono attivare navigazione, modali e notifiche utilizzando funzioni datwenty-sdk:
| Funzione | Descrizione |
|---|---|
navigate(to, params?, queryParams?, options?) | Naviga a una pagina dell’app |
openSidePanelPage(params) | Apri un pannello laterale |
closeSidePanel() | Chiudi il pannello laterale |
openCommandConfirmationModal(params) | Mostra una finestra di conferma |
enqueueSnackbar(params) | Mostra una notifica toast |
unmountFrontComponent() | Smonta il componente |
updateProgress(progress) | Aggiorna un indicatore di avanzamento |
src/front-components/archive-record.tsx
Lavorare con più record
UsauseSelectedRecordIds() per gestire più record selezionati. Questo è utile per operazioni in blocco:
src/front-components/bulk-export.tsx
src/command-menu-items/bulk-export.command-menu-item.ts
Asset pubblici
I componenti front-end possono accedere ai file dalla directorypublic/ dell’app utilizzando getPublicAssetUrl:
Stile
I componenti front-end supportano diversi approcci di styling. Puoi usare:- Stili inline —
style={{ color: 'red' }} - Componenti di Twenty UI — la libreria di componenti di Twenty; vedi Uso dei componenti di Twenty UI di seguito
- Emotion — CSS-in-JS con
@emotion/react - Styled-components — pattern
styled.div - Tailwind CSS — classi di utilità
- Qualsiasi libreria CSS-in-JS compatibile con React
Uso dei componenti di Twenty UI
Twenty distribuisce la sua libreria di componenti come pacchettotwenty-ui. I componenti front-end possono usarlo per pulsanti, tag, pillole di stato, chip, avatar, icone, tipografia e token del tema che si adattano automaticamente al tema chiaro e scuro dell’area di lavoro.
Installazione
Aggiungi il pacchetto alla tua app, bloccato alla versione con cui la tua istanza di Twenty viene distribuita:twenty-ui è incluso nel tuo componente front-end in fase di build, quindi deve essere solo una dipendenza della tua app: non c’è nulla da configurare a runtime.
Importare i componenti
Importa dal sottopercorso corrispondente invece che dalla root del pacchetto, in modo che solo i componenti che usi finiscano nel tuo bundle:| Sottopercorso | Cosa esporta |
|---|---|
twenty-ui/input | Button e campi di input del form |
twenty-ui/data-display | Tag, Status, Chip, Avatar e altro |
twenty-ui/feedback | Callout, Banner, Info e altro |
twenty-ui/typography | H1Title, H2Title, H3Title, Label e altro |
twenty-ui/icon | Componenti Icon* (ad es. IconCheck) |
twenty-ui/theme-constants | ThemeProvider, themeCssVariables |
Icone
Importa le singole icone datwenty-ui/icon:
IconsProvider, useIcons e iconsState: includono l’intero set di icone Tabler (diversi MB).
Temi e token del tema
I componenti Twenty UI si adattano automaticamente al tema chiaro e scuro dell’area di lavoro: il renderer applica lo schema di colori attivo sull’host e i componenti risolvono i loro colori rispetto ad esso. Per usare gli stessi design token nei tuoi stili inline, chiama l’hookuseTheme(). Restituisce i token del tema di Twenty (spaziatura, colori, raggi, font) collegati al tema attivo, senza bisogno di configurare ThemeProvider nel tuo componente:
useTheme() è un hook, leggi i token all’interno del corpo del componente, così i valori riflettono sempre il tema attivo in tempo reale. La stessa mappa di token è anche esportata come costante themeCssVariables, ma nei componenti front-end è preferibile usare useTheme(): una costante a livello di modulo che dereferenzia themeCssVariables può essere undefined mentre il manifest dell’app viene estratto.
Per diramare esplicitamente in base allo schema attivo, leggilo con useColorScheme() da twenty-sdk/front-component, che restituisce 'light' o 'dark'.