Viste

Una vista è una configurazione salvata per come vengono visualizzati i record di un oggetto: quali campi compaiono, il loro ordine, se sono visibili e gli eventuali filtri o gruppi applicati. Usa defineView() per distribuire viste preconfigurate con la tua app — in genere una vista indice predefinita per ogni oggetto personalizzato che crei.

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,
    },
  ],
});

Punti chiave

objectUniversalIdentifier specifica a quale oggetto si applica questa vista. Può essere un oggetto personalizzato che hai definito o un oggetto Twenty standard.
key: ViewKey.INDEX contrassegna la vista come vista elenco principale dell’oggetto (quella che un elemento di navigazione OBJECT apre).
fields controlla quali colonne compaiono e in quale ordine. Ogni campo fa riferimento a un fieldMetadataUniversalIdentifier. Per fare riferimento a un campo di sistema creato automaticamente come createdAt, vedi Targeting System Fields.
Puoi anche definire filters, filterGroups, sorts, groups e fieldGroups per configurazioni più avanzate.
position controlla l’ordinamento quando esistono più viste per lo stesso oggetto.

Proprietà opzionali

Proprietà	Valori	Descrizione
`type`	`ViewType.TABLE` (predefinito), `ViewType.KANBAN`, `ViewType.CALENDAR`	Come sono disposti i record. (`FIELDS_WIDGET`, `TABLE_WIDGET`, `KANBAN_WIDGET` e `CALENDAR_WIDGET` esistono anche ma sono usati internamente dai widget di layout di pagina.)
`visibility`	`ViewVisibility.WORKSPACE` (predefinito), `ViewVisibility.UNLISTED`	Se la vista è elencata per l’intero workspace o nascosta dai selettori.
`openRecordIn`	`ViewOpenRecordIn.SIDE_PANEL` (predefinito), `ViewOpenRecordIn.RECORD_PAGE`	Dove si apre un record quando lo si clicca.
`sorts`	`{ fieldMetadataUniversalIdentifier, direction: ViewSortDirection.ASC \| DESC }[]`	Ordinamento predefinito.
`isCompact`	`boolean`	Visualizzazione compatta delle righe.
`mainGroupByFieldMetadataUniversalIdentifier` + `shouldHideEmptyGroups`	—	Raggruppa i record (ad es. colonne kanban) per un campo.
`kanbanAggregateOperation`, `kanbanAggregateOperationFieldMetadataUniversalIdentifier`, `kanbanColumnWidth`	`AggregateOperations.*`	Aggregazioni e dimensionamento delle colonne kanban.
`calendarLayout`, `calendarFieldMetadataUniversalIdentifier`, `calendarEndFieldMetadataUniversalIdentifier`	`ViewCalendarLayout.DAY` / `WEEK` / `MONTH`	Viste calendario: layout, il campo data che posiziona i record e un campo data di fine opzionale.

Tutti gli enum sopra sono esportati da twenty-sdk/define.

Filtri

Una vista può essere fornita con filtri preapplicati. Ogni filtro ha tre coordinate: il campo che viene filtrato, l’operando (come confrontare) e il valore (con cosa confrontare). Tutti e tre devono allinearsi: l’uso di un operando che non si applica a un tipo di campo verrà rifiutato al momento della sincronizzazione.

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

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

Operatori supportati per tipo di campo

Tipo di campo	Operandi supportati
`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`

I tipi di campo con nomi simili possono usare operandi completamente diversi — SELECT e MULTI_SELECT sono un caso comune.

Forma del valore per operando

Il campo value è sempre un valore serializzabile in JSON, ma la forma prevista dipende dall’operando:

Famiglia di operandi	Forma del valore	Esempio
`IS`, `IS_NOT` su `SELECT`	array di chiavi di opzione (stringhe)	`['ACTIVE', 'PENDING']`
`CONTAINS`, `DOES_NOT_CONTAIN` su `MULTI_SELECT`	array di chiavi di opzione (stringhe)	`['TAG_A']`
`IS`, `IS_NOT` su `RELATION`	array di ID di record (uuid)	`['c5a1...']`
`CONTAINS`, `DOES_NOT_CONTAIN` su campi testuali	stringa	`'acme'`
`IS`, `IS_NOT` su `NUMBER`	stringa (il valore)	`'5'`
`IS` su `RATING` / `UUID`	stringa (il valore)	`'5'`
`GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`	stringa (il limite)	`'10'`
`IS`, `IS_BEFORE`, `IS_AFTER` su `DATE` / `DATE_TIME`	stringa ISO 8601	`'2025-01-01T00:00:00Z'`
`IS_EMPTY`, `IS_NOT_EMPTY`	stringa vuota	`''`
`IS` su `BOOLEAN`	`'true'` o `'false'`	`'true'`

Come le viste vengono visualizzate nell’interfaccia utente

Una vista da sola non è raggiungibile dalla barra laterale. Per farla apparire lì, collegala a una voce del menu di navigazione di tipo VIEW che punti all’universalIdentifier della vista. Questo è il pattern canonico: ogni oggetto personalizzato in genere distribuisce una vista predefinita + una voce nella barra laterale che la apre.

Panoramica

App

API

Auto-ospitazione

Contribuire

Punti chiave

Proprietà opzionali

Filtri

Operatori supportati per tipo di campo

Forma del valore per operando

Come le viste vengono visualizzate nell’interfaccia utente

​Punti chiave

​Proprietà opzionali

​Filtri

​Operatori supportati per tipo di campo

​Forma del valore per operando

​Come le viste vengono visualizzate nell’interfaccia utente

Punti chiave

Proprietà opzionali

Filtri

Operatori supportati per tipo di campo

Forma del valore per operando

Come le viste vengono visualizzate nell’interfaccia utente