Onde os componentes de front-end podem ser usados
Os componentes de front-end podem ser renderizados em dois locais dentro do Twenty:- Painel lateral — Componentes de front-end não headless abrem no painel lateral direito. Este é o comportamento padrão quando um componente de front-end é acionado pelo menu de comandos.
- Widgets (painéis e páginas de registro) — Componentes de front-end podem ser incorporados como widgets nos layouts de página. Ao configurar um painel ou o layout de uma página de registro, os usuários podem adicionar um widget de componente de front-end.
Exemplo básico
A maneira mais rápida de ver um componente de front-end em ação é registrá-lo como um comando. Adicionar um campocommand com isPinned: true faz com que ele apareça como um botão de ação rápida no canto superior direito da página — não é necessário layout de página:
src/front-components/hello-world.tsx
yarn twenty dev (ou executando uma única vez o yarn twenty dev --once), a ação rápida aparece no canto superior direito da página:

Campos de configuração
| Campo | Obrigatório | Descrição |
|---|---|---|
universalIdentifier | Sim | ID único e estável para este componente |
component | Sim | Uma função de componente React |
name | Não | Nome de Exibição |
description | Não | Descrição do que o componente faz |
isHeadless | Não | Defina como true se o componente não tiver interface visível (veja abaixo) |
command | Não | Registre o componente como um comando (veja opções de comando abaixo) |
Colocando um componente de front-end em uma página
Além de comandos, você pode incorporar um componente de front-end diretamente em uma página de registro adicionando-o como um widget em um layout de página. Veja a seção definePageLayout para obter detalhes.Headless vs não headless
Os componentes de front-end têm dois modos de renderização controlados pela opçãoisHeadless:
Não headless (padrão) — O componente renderiza uma interface visível. Quando acionado pelo menu de comandos, ele é aberto no painel lateral. Este é o comportamento padrão quando isHeadless é false ou omitido.
Headless (isHeadless: true) — The component mounts invisibly in the background. Ele não abre o painel lateral. Componentes headless são projetados para ações que executam lógica e, em seguida, se desmontam — por exemplo, executar uma tarefa assíncrona, navegar para uma página ou exibir um modal de confirmação. Eles se combinam naturalmente com os componentes Command do SDK descritos abaixo.
src/front-components/sync-tracker.tsx
null, o Twenty ignora renderizar um contêiner para ele — nenhum espaço vazio aparece no layout. O componente ainda tem acesso a todos os hooks e à API de comunicação do host.
Componentes Command do SDK
O pacotetwenty-sdk fornece quatro componentes auxiliares Command projetados para componentes de front-end headless. Cada componente executa uma ação ao montar, trata erros exibindo uma notificação de snackbar e desmonta automaticamente o componente de front-end ao concluir.
Importe-os de twenty-sdk/command:
Command— Executa um callback assíncrono via a propexecute.CommandLink— Navega para um caminho do app. Props:to,params,queryParams,options.CommandModal— Abre um modal de confirmação. Se o usuário confirmar, executa o callbackexecute. Props:title,subtitle,execute,confirmButtonText,confirmButtonAccent.CommandOpenSidePanelPage— Abre uma página específica do painel lateral. Props:page,pageTitle,pageIcon.
Command para executar uma ação a partir do menu de comandos:
src/front-components/run-action.tsx
CommandModal para solicitar confirmação antes de executar:
src/front-components/delete-draft.tsx
Acessando o contexto de execução
Dentro do seu componente, use hooks do SDK para acessar o usuário atual, o registro e a instância do componente:src/front-components/record-info.tsx
| Hook | Retorna | Descrição |
|---|---|---|
useUserId() | string ou null | O ID do usuário atual |
useRecordId() | string ou null | O ID do registro atual (quando colocado em uma página de registro) |
useFrontComponentId() | string | O ID desta instância do componente |
useFrontComponentExecutionContext(selector) | varia | Acesse o contexto de execução completo com uma função seletora |
API de comunicação do host
Componentes de front-end podem acionar navegação, modais e notificações usando funções detwenty-sdk:
| Função | Descrição |
|---|---|
navigate(to, params?, queryParams?, options?) | Navegar para uma página no app |
openSidePanelPage(params) | Abrir um painel lateral |
closeSidePanel() | Fecha o painel lateral |
openCommandConfirmationModal(params) | Mostrar um diálogo de confirmação |
enqueueSnackbar(params) | Mostrar uma notificação do tipo toast |
unmountFrontComponent() | Desmontar o componente |
updateProgress(progress) | Atualizar um indicador de progresso |
src/front-components/archive-record.tsx
Opções de comando
Adicionar um campocommand a defineFrontComponent registra o componente no menu de comandos (Cmd+K). Se isPinned for true, ele também aparece como um botão de ação rápida no canto superior direito da página.
| Campo | Obrigatório | Descrição |
|---|---|---|
universalIdentifier | Sim | ID exclusivo e estável para o comando |
label | Sim | Rótulo completo exibido no menu de comandos (Cmd+K) |
shortLabel | Não | Rótulo mais curto exibido no botão fixado de ação rápida |
icon | Não | Nome do ícone exibido ao lado do rótulo (por exemplo, 'IconBolt', 'IconSend') |
isPinned | Não | Quando true, mostra o comando como um botão de ação rápida no canto superior direito da página |
availabilityType | Não | Controla onde o comando aparece: 'GLOBAL' (sempre disponível), 'RECORD_SELECTION' (apenas quando registros estão selecionados) ou 'FALLBACK' (exibido quando nenhum outro comando corresponde) |
availabilityObjectUniversalIdentifier | Não | Restringe o comando a páginas de um tipo específico de objeto (por exemplo, somente em registros de Company) |
conditionalAvailabilityExpression | Não | Uma expressão booleana para controlar dinamicamente se o comando é visível (veja abaixo) |
Expressões de disponibilidade condicional
O campoconditionalAvailabilityExpression permite controlar quando um comando é visível com base no contexto da página atual. Importe variáveis tipadas e operadores de twenty-sdk para construir expressões:
| Variável | Tipo | Descrição |
|---|---|---|
pageType | string | Tipo de página atual (por exemplo, 'RecordIndexPage', 'RecordShowPage') |
isInSidePanel | boolean | Se o componente é renderizado em um painel lateral |
numberOfSelectedRecords | number | Número de registros atualmente selecionados |
isSelectAll | boolean | Se “selecionar tudo” está ativo |
selectedRecords | array | Os objetos de registro selecionados |
favoriteRecordIds | array | IDs dos registros marcados como favoritos |
objectPermissions | object | Permissões para o tipo de objeto atual |
targetObjectReadPermissions | object | Permissões de leitura para o objeto alvo |
targetObjectWritePermissions | object | Permissões de escrita para o objeto alvo |
featureFlags | object | Flags de recurso ativas |
objectMetadataItem | object | Metadados do tipo de objeto atual |
hasAnySoftDeleteFilterOnView | boolean | Se a visualização atual tem um filtro de soft-delete |
| Operador | Descrição |
|---|---|
isDefined(value) | true se o valor não for null/undefined |
isNonEmptyString(value) | true se o valor for uma string não vazia |
includes(array, value) | true se o array contiver o valor |
includesEvery(array, prop, value) | true se a propriedade de cada item incluir o valor |
every(array, prop) | true se a propriedade for truthy em cada item |
everyDefined(array, prop) | true se a propriedade estiver definida em cada item |
everyEquals(array, prop, value) | true se a propriedade for igual ao valor em cada item |
some(array, prop) | true se a propriedade for truthy em pelo menos um item |
someDefined(array, prop) | true se a propriedade estiver definida em pelo menos um item |
someEquals(array, prop, value) | true se a propriedade for igual ao valor em pelo menos um item |
someNonEmptyString(array, prop) | true se a propriedade for uma string não vazia em pelo menos um item |
none(array, prop) | true se a propriedade for falsy em cada item |
noneDefined(array, prop) | true se a propriedade for undefined em cada item |
noneEquals(array, prop, value) | true se a propriedade não for igual ao valor em nenhum item |
Recursos públicos
Componentes de front-end podem acessar arquivos do diretóriopublic/ do app usando getPublicAssetUrl:
Estilização
Componentes de front-end suportam várias abordagens de estilização. Você pode usar:- Estilos inline —
style={{ color: 'red' }} - Componentes de UI do Twenty — importe de
twenty-sdk/ui(Button, Tag, Status, Chip, Avatar e mais) - Emotion — CSS-in-JS com
@emotion/react - Styled-components — padrões
styled.div - Tailwind CSS — classes utilitárias
- Qualquer biblioteca CSS-in-JS compatível com React