Saltar para o conteúdo principal
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 distribuir visualizações pré-configuradas com seu app — normalmente uma visualização de índice padrão para cada objeto personalizado que você cria.
src/views/example-view.ts
import { defineView, ViewKey } 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',
  key: ViewKey.INDEX,
  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.
  • key determina o tipo de visualização — ViewKey.INDEX é a visualização de lista principal do objeto.
  • fields controla quais colunas aparecem e em que ordem. Cada campo referencia um fieldMetadataUniversalIdentifier.
  • Você também pode declarar filters, filterGroups, groups e fieldGroups para configurações avançadas.
  • position controla a ordenação quando existem várias visualizações para o mesmo objeto.

​
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-shared/types';

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

​
Operadores compatíveis por tipo de campo

Tipo de campoOperandos suportados
TEXT, EMAILS, FULL_NAME, ADDRESS, LINKS, PHONES, RAW_JSON, FILES, ACTOR, ARRAYCONTAINS, DOES_NOT_CONTAIN, IS_EMPTY, IS_NOT_EMPTY
ACTOR.source, ACTOR.workspaceMemberIdIS, IS_NOT, IS_EMPTY, IS_NOT_EMPTY
SELECTIS, IS_NOT, IS_EMPTY, IS_NOT_EMPTY
MULTI_SELECTCONTAINS, DOES_NOT_CONTAIN, IS_EMPTY, IS_NOT_EMPTY
RELATIONIS, IS_NOT, IS_EMPTY, IS_NOT_EMPTY
NUMBERIS, IS_NOT, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, IS_EMPTY, IS_NOT_EMPTY
RATINGIS, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, IS_EMPTY, IS_NOT_EMPTY
CURRENCY, CURRENCY.amountMicrosGREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, IS, IS_NOT, IS_EMPTY, IS_NOT_EMPTY
CURRENCY.currencyCodeIS, IS_NOT, IS_EMPTY, IS_NOT_EMPTY
DATE, DATE_TIMEIS, IS_RELATIVE, IS_IN_PAST, IS_IN_FUTURE, IS_TODAY, IS_BEFORE, IS_AFTER, IS_EMPTY, IS_NOT_EMPTY
BOOLEANIS
UUIDIS, IS_NOT, IS_EMPTY, IS_NOT_EMPTY
TS_VECTORVECTOR_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 operandoFormato do valorExemplo
IS, IS_NOT em SELECTarray de chaves de opções (strings)['ACTIVE', 'PENDING']
CONTAINS, DOES_NOT_CONTAIN em MULTI_SELECTarray de chaves de opções (strings)['TAG_A']
IS, IS_NOT em RELATIONarray de IDs de registros (uuids)['c5a1...']
CONTAINS, DOES_NOT_CONTAIN em campos de textostring'acme'
IS, IS_NOT em NUMBERstring (o valor)'5'
IS em RATING / UUIDstring (o valor)'5'
GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUALstring (o limite)'10'
IS, IS_BEFORE, IS_AFTER em DATE / DATE_TIMEstring ISO 8601'2025-01-01T00:00:00Z'
IS_EMPTY, IS_NOT_EMPTYstring 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.