The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: Oggetti
description: Dichiara nuovi tipi di record — tabelle personalizzate con i propri campi — usando defineObject.
---
import { PageBanner } from "/snippets/page-banner.mdx"
## Panoramica
Gli **oggetti** personalizzati sono nuovi tipi di record che la tua app aggiunge a uno spazio di lavoro — Cartolina, Fattura, Abbonamento, qualsiasi cosa specifica per il tuo dominio. Ogni oggetto dichiara il proprio schema (campi, relazioni, valori predefiniti) e un identificatore universale stabile che persiste tra le sincronizzazioni e le distribuzioni.
```ts src/objects/post-card.object.ts
import { defineObject, FieldType } from 'twenty-sdk/define';
enum PostCardStatus {
DRAFT = 'DRAFT',
SENT = 'SENT',
DELIVERED = 'DELIVERED',
RETURNED = 'RETURNED',
}
export default defineObject({
universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
nameSingular: 'postCard',
namePlural: 'postCards',
labelSingular: 'Post Card',
labelPlural: 'Post Cards',
description: 'A post card object',
icon: 'IconMail',
fields: [
{
universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
name: 'content',
type: FieldType.TEXT,
label: 'Content',
description: "Postcard's content",
icon: 'IconAbc',
},
{
universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
name: 'recipientName',
type: FieldType.FULL_NAME,
label: 'Recipient name',
icon: 'IconUser',
},
{
universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
name: 'recipientAddress',
type: FieldType.ADDRESS,
label: 'Recipient address',
icon: 'IconHome',
},
{
universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
name: 'status',
type: FieldType.SELECT,
label: 'Status',
icon: 'IconSend',
defaultValue: `'${PostCardStatus.DRAFT}'`,
options: [
{
value: PostCardStatus.DRAFT,
label: 'Draft',
position: 0,
color: 'gray',
},
{
value: PostCardStatus.SENT,
label: 'Sent',
position: 1,
color: 'orange',
},
{
value: PostCardStatus.DELIVERED,
label: 'Delivered',
position: 2,
color: 'green',
},
{
value: PostCardStatus.RETURNED,
label: 'Returned',
position: 3,
color: 'orange',
},
],
},
{
universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
name: 'deliveredAt',
type: FieldType.DATE_TIME,
label: 'Delivered at',
icon: 'IconCheck',
isNullable: true,
defaultValue: null,
},
],
});
```
## Punti chiave
* Il `universalIdentifier` deve essere univoco e stabile tra i deployment.
* Ogni campo richiede un `name`, `type`, `label` e il proprio `universalIdentifier` stabile.
* L'array `fields` è facoltativo: puoi definire oggetti senza campi personalizzati.
* `openRecordIn` imposta dove si aprono i record di questo oggetto quando vengono cliccati: `ObjectOpenRecordIn.USER_CHOICE` (l'impostazione predefinita, che segue la preferenza di ciascun membro dell'area di lavoro da Settings → Experience), `ObjectOpenRecordIn.SIDE_PANEL` oppure `ObjectOpenRecordIn.RECORD_PAGE`. Fissalo su `RECORD_PAGE` per i record che devono occupare un'intera pagina per essere usabili, come avviene per i workflow e le dashboard, oppure su `SIDE_PANEL` per i record che hanno senso solo come pannello rapido, come avviene per gli eventi di calendario.
* `disabledObjectPermissionActions` elenca le autorizzazioni degli oggetti che non possono essere concesse sull'oggetto: una qualsiasi tra `'canReadObjectRecords'`, `'canUpdateObjectRecords'`, `'canSoftDeleteObjectRecords'` e `'canDestroyObjectRecords'`, gli stessi flag che un ruolo imposta per ciascun oggetto. Gli utenti, le chiavi API e gli agenti non ottengono mai queste azioni sull'oggetto, indipendentemente da ciò che concede il loro ruolo, e il salvataggio di un'autorizzazione per l'oggetto che ne concede una non riesce. Le funzioni della logica della tua app le mantengono. Ad esempio, `['canUpdateObjectRecords', 'canSoftDeleteObjectRecords', 'canDestroyObjectRecords']` rende un oggetto scrivibile solo dalla tua app, per record simili a configurazioni che concedono comportamenti.
* `color` imposta il colore di accento dell'oggetto nell'interfaccia utente. Omettilo e Twenty ne sceglierà uno per l'oggetto.
* `imageIdentifierFieldMetadataUniversalIdentifier` denomina il campo il cui valore viene mostrato come avatar del record. Omettilo per consentire a Twenty di scegliere quello predefinito.
* `isLabelSyncedWithName`, su un oggetto o su un campo, mantiene il nome API sincronizzato con l'etichetta quando quest'ultima viene modificata in Impostazioni. Per impostazione predefinita è `false`, quindi un'etichetta rinominata lascia invariato il nome.
* `isSearchable: true`, su un campo, include i relativi valori nella ricerca full-text dell'oggetto (ricerca globale e menu dei comandi). Richiede che l'oggetto stesso sia ricercabile e un tipo di campo compatibile con il testo. Un valore omesso indica che non è ricercabile, ad eccezione del campo identificatore dell'etichetta dell'oggetto, che è sempre ricercabile e non può essere escluso. Ogni sincronizzazione applica lo stato dichiarato, quindi un campo reso ricercabile da Impostazioni viene ripristinato alla successiva sincronizzazione dell'app, a meno che il manifest non lo dichiari.
* `isAuditLogged: false`, su un campo, mantiene le relative modifiche fuori dalla cronologia del record. Per impostazione predefinita è `true`, tranne che su un campo `POSITION`, le cui modifiche vengono visualizzate vuote nella cronologia e non vengono mai registrate. Impostalo sui campi che la tua app riscrive periodicamente, ad esempio un timestamp dell'ultimo contatto o una relazione di rollup, in modo che ogni sincronizzazione non aggiunga una riga di attività a ogni record che modifica. Un aggiornamento la cui intera differenza è costituita da campi non registrati nell'audit non produce alcuna attività nella cronologia. Come `isSearchable`, ogni sincronizzazione applica lo stato dichiarato.
* `disabledFieldPermissionActions`, in un campo, elenca le autorizzazioni del campo che non possono esservi concesse: `'canReadFieldValue'`, `'canUpdateFieldValue'` o entrambe, gli stessi flag impostati da un ruolo per ciascun campo. Gli utenti, le chiavi API, gli agenti e le altre app non ottengono mai queste azioni sul campo, indipendentemente da ciò che concede il loro ruolo, e il salvataggio di un'autorizzazione del campo che ne concede una non riesce. Le funzioni della logica della tua app le mantengono. Ad esempio, `['canUpdateFieldValue']` mantiene in sola lettura per tutti gli altri un valore che la tua app calcola o sincronizza, come uno stato o un punteggio. Funziona anche sui campi che aggiungi a oggetti che non possiedi con `defineField()`.
* I campi inline definiti qui **non** hanno bisogno di un `objectUniversalIdentifier` — viene ereditato dall'oggetto padre. Usa [`defineField()`](/it/developers/extend/apps/data/extending-objects) per aggiungere campi a oggetti che non possiedi.
* Puoi generare nuovi oggetti con `twenty app add object`, che ti guida nella denominazione, nei campi e nelle relazioni. Vedi [Architettura → Scaffolding delle entità](/it/developers/extend/apps/getting-started/scaffolding).
<Note>
**I campi base vengono aggiunti automaticamente.** Quando definisci un oggetto personalizzato,
Twenty crea per te campi standard come `id`, `name`, `createdAt`, `updatedAt`,
`createdBy`, `updatedBy` e `deletedAt`. Non è necessario dichiararli
nel tuo array `fields` — solo i tuoi campi personalizzati. Puoi sovrascrivere un
campo predefinito dichiarandone uno con lo stesso nome, ma è raramente una buona
idea.
</Note>
## Tipi di campo
L’insieme completo dei valori di `FieldType`, esportati da `twenty-sdk/define`:
| Categoria | Tipi |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Testo | `TEXT`, `RICH_TEXT`, `ARRAY` (di stringhe), `RAW_JSON` |
| Numerico | `NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`), `NUMERIC` (precisione arbitraria), `RATING`, `POSITION` |
| Date | `DATE`, `DATE_TIME` |
| Scelta | `BOOLEAN`, `SELECT`, `MULTI_SELECT` |
| Compositi | `FULL_NAME`, `ADDRESS`, `EMAILS`, `PHONES`, `LINKS` (`universalSettings.type`: `'url'` (predefinito) / `'domain'` — un campo di dominio memorizza l'host senza prefisso, pertanto `https://www.acme.com/careers` viene scritto come `acme.com` e un valore che non è un host viene rifiutato), `CURRENCY`, `ACTOR`, `FILES` |
| Identificatori e relazioni | `UUID`, `RELATION`, `MORPH_RELATION` (vedi [Relazioni](/it/developers/extend/apps/data/relations)) |
| Sistema | `TS_VECTOR` (vettore per la ricerca full-text, gestito dal server) |
I tipi compositi memorizzano più sotto-campi (ad es. `FULL_NAME` = nome + cognome; `CURRENCY` = `amountMicros` + `currencyCode`). `SELECT` e `MULTI_SELECT` richiedono un array `options` come nell’esempio sopra.
### Seleziona opzioni
Per `SELECT` e `MULTI_SELECT`, fornisci un array `options` non vuoto di oggetti. Ogni opzione ha un `value`, un `label` e una `position`. Il relativo `color` è facoltativo e, se omesso o null, il valore predefinito è `gray`.
Se fornito, `color` deve essere uno dei seguenti: `red`, `ruby`, `crimson`, `tomato`, `orange`, `amber`, `yellow`, `lime`, `grass`, `green`, `jade`, `mint`, `turquoise`, `cyan`, `sky`, `blue`, `iris`, `violet`, `purple`, `plum`, `pink`, `bronze`, `gold`, `brown`, `gray`.
Sia `defineObject()` sia `defineField()` restituiscono errori di convalida per colori non supportati o voci di opzione che sono null, primitive o array.
## Valori predefiniti
I valori predefiniti letterali devono essere racchiusi tra apici singoli **all'interno** della stringa — `defaultValue: "'Draft'"`, non `defaultValue: "Draft"`. Ecco perché il campo `status` sopra utilizza `` `'${PostCardStatus.DRAFT}'` ``.
Le stringhe senza virgolette sono riservate ai valori predefiniti calcolati, valutati quando viene creato un record:
* `'uuid'` — genera un UUID (per i campi `UUID`)
* `'now'` — il timestamp corrente (per i campi `DATE_TIME`)
La stessa convenzione si applica ai sotto-campi stringa dei valori compositi predefiniti (ad es. `{ source: "'MANUAL'" }` su un campo `ACTOR`) e ai valori `SELECT`/`MULTI_SELECT`. Una stringa letterale predefinita lasciata senza virgolette genera un avviso quando la tua app viene compilata.
## Nullabilità
`isNullable` controlla se un campo accetta `NULL`. Il valore predefinito è `true` — omettilo per i campi facoltativi. Imposta `isNullable: false` per rendere un campo obbligatorio a livello di database.
Le modifiche a `isNullable` vengono applicate a ogni sincronizzazione, incluse quelle che aggiornano un campo esistente — quindi puoi cambiare la nullabilità di un campo modificando il manifest e rieseguendo la sincronizzazione.
<Note>
**Rendere un campo esistente non nullable richiede un valore predefinito.** Quando
modifichi un campo impostando `isNullable: false`, devi anche fornire un
`defaultValue` non nullo. Il valore predefinito riempie tutte le righe `NULL` esistenti prima che venga applicato il vincolo `NOT
NULL`; senza di esso la sincronizzazione non riesce con `Default value
cannot be null for non-nullable fields`. I campi di relazione e i campi `TS_VECTOR`
ammettono sempre `NULL`, quindi `isNullable` non ha alcun effetto su di essi.
</Note>
```ts
{
universalIdentifier: 'b1a7c0de-1234-4f00-9abc-000000000000',
name: 'reference',
type: FieldType.TEXT,
label: 'Reference',
isNullable: false,
defaultValue: "'N/A'",
}
```
## Cosa c'è dopo
* **Collega questo oggetto ad altri** — vedi [Relazioni](/it/developers/extend/apps/data/relations) per il pattern di relazione bidirezionale.
* **Aggiungi campi a oggetti di altre app** — vedi [Estendere gli oggetti](/it/developers/extend/apps/data/extending-objects) per `defineField()`.
* **Visualizza questo oggetto nell'interfaccia utente (UI)** — vedi [Voci del menu di navigazione](/it/developers/extend/apps/layout/navigation-menu-items) per aggiungere una voce nella barra laterale; vedi [Viste](/it/developers/extend/apps/layout/views) per aggiungere configurazioni di elenco personalizzate.
<PageBanner illustration="card-page-objects" />