Vai al contenuto principale

​
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.
src/objects/post-card.object.ts

​
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() 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à.
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.

​
Tipi di campo

L’insieme completo dei valori di FieldType, esportati da twenty-sdk/define: 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.
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.

​
Cosa c’è dopo

  • Collega questo oggetto ad altri — vedi Relazioni per il pattern di relazione bidirezionale.
  • Aggiungi campi a oggetti di altre app — vedi Estendere gli oggetti per defineField().
  • Visualizza questo oggetto nell’interfaccia utente (UI) — vedi Voci del menu di navigazione per aggiungere una voce nella barra laterale; vedi Viste per aggiungere configurazioni di elenco personalizzate.