Visualizações

Uma visualização é uma configuração salva de como os registros de um objeto são exibidos: quais campos aparecem, sua ordem, se estão visíveis e quaisquer filtros ou grupos aplicados. Use defineView() para enviar visualizações pré-configuradas com seu app. Cada objeto recebe automaticamente sua principal visualização de lista (a tabela “All …” que um item de navegação OBJECT abre), provisionada pelo servidor — incluindo os objetos que seu app cria, com uma coluna por campo que seu app declara. As visualizações que você define com defineView() são sempre visualizações adicionais em cima daquela padrão.

src/views/example-view.ts

import { defineView } from 'twenty-sdk/define';
import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from '../objects/example-object';
import { NAME_FIELD_UNIVERSAL_IDENTIFIER } from '../objects/example-object';

export default defineView({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'All example items',
  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
  icon: 'IconList',
  position: 0,
  fields: [
    {
      universalIdentifier: 'f926bdb7-6af7-4683-9a09-adbca56c29f0',
      fieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
      position: 0,
      isVisible: true,
      size: 200,
    },
  ],
});

Pontos-chave

objectUniversalIdentifier especifica a qual objeto esta visualização se aplica. Pode ser um objeto personalizado que você definiu ou um objeto padrão do Twenty.
A visualização principal de lista do objeto é de propriedade do servidor: key está obsoleto e é ignorado, portanto uma visualização definida no manifesto nunca poderá reivindicá-la. Envie um item de navegação VIEW se quiser que sua visualização fique a um clique de distância na barra lateral.
fields controla quais colunas aparecem e em que ordem. Cada campo referencia um fieldMetadataUniversalIdentifier. Para fazer referência a um campo de sistema criado automaticamente, como createdAt, consulte Direcionamento de metadados do sistema.
Você também pode declarar filters, filterGroups, sorts, groups e fieldGroups para configurações avançadas.
position controla a ordenação quando existem várias visualizações para o mesmo objeto.

Propriedades opcionais

Propriedade	Valores	Descrição
`type`	`ViewType.TABLE` (padrão), `ViewType.KANBAN`, `ViewType.CALENDAR`	Como os registros são dispostos. (`FIELDS_WIDGET`, `TABLE_WIDGET`, `KANBAN_WIDGET` e `CALENDAR_WIDGET` também existem, mas são usados internamente por widgets de layout de página.)
`visibility`	`ViewVisibility.WORKSPACE` (padrão), `ViewVisibility.UNLISTED`	Se a visualização é listada em todo o espaço de trabalho ou oculta nos seletores.
`openRecordIn`	`ViewOpenRecordIn.SIDE_PANEL` (padrão), `ViewOpenRecordIn.RECORD_PAGE`	Onde clicar em um registro o abre.
`ordenações`	`{ fieldMetadataUniversalIdentifier, direction: ViewSortDirection.ASC \| DESC }[]`	Ordem de classificação padrão.
`isCompact`	`boolean`	Exibição compacta de linhas.
`mainGroupByFieldMetadataUniversalIdentifier` + `shouldHideEmptyGroups`	—	Agrupar registros (por exemplo, colunas kanban) por um campo.
`kanbanAggregateOperation`, `kanbanAggregateOperationFieldMetadataUniversalIdentifier`, `kanbanColumnWidth`	`AggregateOperations.*`	Agregações e dimensionamento de colunas kanban.
`calendarLayout`, `calendarFieldMetadataUniversalIdentifier`, `calendarEndFieldMetadataUniversalIdentifier`	`ViewCalendarLayout.DAY` / `WEEK` / `MONTH`	Visualizações de calendário: layout, o campo de data que posiciona os registros e um campo de data final opcional.

Todos os enums acima são exportados de twenty-sdk/define.

Filtros

Uma visualização pode vir com filtros pré-aplicados. Cada filtro tem três coordenadas: o campo a ser filtrado, o operador (como comparar) e o valor (com o que comparar). As três precisam estar alinhadas — usar um operador que não se aplica a um tipo de campo será rejeitado no momento da sincronização.

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

filters: [
  {
    universalIdentifier: '...',
    fieldMetadataUniversalIdentifier: STATUS_FIELD_UNIVERSAL_IDENTIFIER,
    operand: ViewFilterOperand.IS,
    value: ['ACTIVE'],
  },
],

Operadores compatíveis por tipo de campo

Tipo de campo	Operandos suportados
`TEXT`, `EMAILS`, `FULL_NAME`, `ADDRESS`, `LINKS`, `PHONES`, `RAW_JSON`, `FILES`, `ACTOR`, `ARRAY`	`CONTAINS`, `DOES_NOT_CONTAIN`, `IS_EMPTY`, `IS_NOT_EMPTY`
`ACTOR.source`, `ACTOR.workspaceMemberId`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`SELECT`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`MULTI_SELECT`	`CONTAINS`, `DOES_NOT_CONTAIN`, `IS_EMPTY`, `IS_NOT_EMPTY`
`RELATION`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`NUMBER`	`IS`, `IS_NOT`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_EMPTY`, `IS_NOT_EMPTY`
`RATING`	`IS`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_EMPTY`, `IS_NOT_EMPTY`
`CURRENCY`, `CURRENCY.amountMicros`	`GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`CURRENCY.currencyCode`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`DATE`, `DATE_TIME`	`IS`, `IS_RELATIVE`, `IS_IN_PAST`, `IS_IN_FUTURE`, `IS_TODAY`, `IS_BEFORE`, `IS_AFTER`, `IS_EMPTY`, `IS_NOT_EMPTY`
`BOOLEAN`	`IS`
`UUID`	`IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`
`TS_VECTOR`	`VECTOR_SEARCH`

Tipos de campos com nomes semelhantes podem usar operandos completamente diferentes — SELECT e MULTI_SELECT sendo um caso comum.

Formato do valor por operando

O campo value é sempre um valor serializável em JSON, mas o seu formato esperado depende do operando:

Família do operando	Formato do valor	Exemplo
`IS`, `IS_NOT` em `SELECT`	array de chaves de opções (strings)	`['ACTIVE', 'PENDING']`
`CONTAINS`, `DOES_NOT_CONTAIN` em `MULTI_SELECT`	array de chaves de opções (strings)	`['TAG_A']`
`IS`, `IS_NOT` em `RELATION`	array de IDs de registros (uuids)	`['c5a1...']`
`CONTAINS`, `DOES_NOT_CONTAIN` em campos de texto	string	`'acme'`
`IS`, `IS_NOT` em `NUMBER`	string (o valor)	`'5'`
`IS` em `RATING` / `UUID`	string (o valor)	`'5'`
`GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`	string (o limite)	`'10'`
`IS`, `IS_BEFORE`, `IS_AFTER` em `DATE` / `DATE_TIME`	string ISO 8601	`'2025-01-01T00:00:00Z'`
`IS_EMPTY`, `IS_NOT_EMPTY`	string vazia	`''`
`IS` em `BOOLEAN`	`'true'` ou `'false'`	`'true'`

Como as visualizações aparecem na UI

Uma visualização por si só não é acessível a partir da barra lateral. Para fazê-la aparecer lá, associe-a a um item de menu de navegação do tipo VIEW que aponte para o universalIdentifier da visualização. Esse é o padrão canônico: cada objeto personalizado normalmente inclui uma visualização padrão + uma entrada na barra lateral que a abre.

Visão Geral

Aplicativos

API

Auto-Anfitrião

Contribuir

Pontos-chave

Propriedades opcionais

Filtros

Operadores compatíveis por tipo de campo

Formato do valor por operando

Como as visualizações aparecem na UI

​Pontos-chave

​Propriedades opcionais

​Filtros

​Operadores compatíveis por tipo de campo

​Formato do valor por operando

​Como as visualizações aparecem na UI

Pontos-chave

Propriedades opcionais

Filtros

Operadores compatíveis por tipo de campo

Formato do valor por operando

Como as visualizações aparecem na UI