Skip to content

The open alternative to Salesforce, designed for AI.

15.5 KB
Raw Blame
---
title: Viste
description: Distribuisci viste preconfigurate salvate — ordine delle colonne, filtri, gruppi — per gli oggetti nella tua app.
---

import { PageBanner } from "/snippets/page-banner.mdx"

## Panoramica

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 fornire viste preconfigurate con la tua app.

Ogni oggetto ottiene automaticamente la sua vista elenco principale (la tabella "All ..." che un elemento di navigazione `OBJECT` apre) fornita dal server — inclusi gli oggetti che la tua app crea, con una colonna per ogni campo dichiarato dalla tua app. Le viste che definisci con `defineView()` sono sempre viste **aggiuntive** rispetto a quella predefinita.

```ts 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: 'IconTable',
  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.
* La vista principale dell'elenco dell'oggetto è di proprietà del server: `key` è deprecato e ignorato, quindi una vista del manifest non potrà mai rivendicarla. Distribuisci un elemento di navigazione `VIEW` se vuoi avere la tua vista a un clic di distanza nella barra laterale.
* `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 Metadata](/it/developers/extend/apps/data/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.LIST`, `ViewType.KANBAN`, `ViewType.CALENDAR` | Come sono disposti i record. (`FIELDS_WIDGET`, `TABLE_WIDGET`, `KANBAN_WIDGET`, `LIST_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`                                                                                              | deprecato                                                                               | Non più letto: il luogo in cui vengono aperti i record è ora una proprietà dell'[oggetto](/it/developers/extend/apps/data/objects) (`openRecordIn` in `defineObject()`); in assenza, si applica la preferenza di ciascun membro. |
| `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.                                                                                                                                                                      |
| `groupLoadLimit`                                                                                            | `8` (predefinito), `25`, `50`, `100`                                                    | Record caricati per gruppo prima di "Carica altro", nelle viste tabella ed elenco raggruppate. Le bacheche Kanban eseguono la paginazione in base alle proprie dimensioni e lo ignorano.                                      |
| `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.

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

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

Tre proprietà facoltative perfezionano un filtro:

| Proprietà                                                          | Descrizione                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subFieldName`                                                     | Individua una parte di un campo composito, ad esempio `amountMicros` in un campo `CURRENCY` o `primaryLinkUrl` in un campo `LINKS`.                                                                                                                            |
| `relationTargetFieldMetadataUniversalIdentifier`                   | In un filtro su un campo `RELATION`, il campo dell'oggetto correlato rispetto al quale viene confrontato il valore, come viene impostato dal filtro avanzato quando selezioni un campo del record correlato. Omettilo per filtrare il record correlato stesso. |
| `viewFilterGroupUniversalIdentifier` + `positionInViewFilterGroup` | Inserisci il filtro in uno dei `filterGroups` della vista (ciascuno con un `logicalOperator` di `AND`, `OR` o `NOT` e un `parentViewFilterGroupUniversalIdentifier` facoltativo) e ordinalo all'interno di quel gruppo.                                        |

`twenty app pull` riscrive tutti e tre esattamente come l'area di lavoro li ha archiviati.

### Operatori supportati per tipo di campo

| Tipo di campo                                                                              | Operandi supportati                                                                                                |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `TEXT`                                                                                     | `CONTAINS`, `DOES_NOT_CONTAIN`, `IS`, `IS_NOT`, `IS_EMPTY`, `IS_NOT_EMPTY`                                         |
| `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 `TEXT`                              | stringa (esatta, sensibile alle maiuscole e minuscole) | `'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](/it/developers/extend/apps/layout/navigation-menu-items) di tipo `VIEW` che punti all'`universalIdentifier` della vista. Questo è il modello canonico: ogni oggetto personalizzato riceve una vista indice predefinita generata automaticamente al momento della creazione, quindi devi solo distribuire la voce della barra laterale che la apre.

<PageBanner illustration="card-page-views" />