Skip to content

The open alternative to Salesforce, designed for AI.

14.5 KB
Raw Blame
---
title: Objetos
description: Declara nuevos tipos de registro (tablas personalizadas con sus propios campos) usando defineObject.
---

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

## Resumen

Los **objetos** personalizados son nuevos tipos de registro que tu aplicación añade a un espacio de trabajo — Tarjeta postal, Factura, Suscripción, cualquier cosa específica de tu dominio. Cada objeto declara su esquema (campos, relaciones, valores predeterminados) y un identificador universal estable que se mantiene a través de sincronizaciones e implementaciones.

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

## Puntos clave

* El `universalIdentifier` debe ser único y estable entre implementaciones.
* Cada campo requiere `name`, `type`, `label` y su propio `universalIdentifier` estable.
* La matriz `fields` es opcional: puedes definir objetos sin campos personalizados.
* `openRecordIn` establece dónde se abren los registros de este objeto al hacer clic: `ObjectOpenRecordIn.USER_CHOICE` (el valor predeterminado, que sigue la preferencia de cada miembro del espacio de trabajo en Settings → Experience), `ObjectOpenRecordIn.SIDE_PANEL` o `ObjectOpenRecordIn.RECORD_PAGE`. Fíjalo en `RECORD_PAGE` para los registros que necesitan una página completa para ser utilizables, como ocurre con los flujos de trabajo y los paneles, o en `SIDE_PANEL` para los registros que solo tienen sentido como un panel rápido, como los eventos del calendario.
* `disabledObjectPermissionActions` enumera los permisos de objeto que no se pueden conceder sobre el objeto: cualquiera de `'canReadObjectRecords'`, `'canUpdateObjectRecords'`, `'canSoftDeleteObjectRecords'` y `'canDestroyObjectRecords'`, las mismas marcas que un rol establece por objeto. Los usuarios, las claves de API y los agentes nunca obtienen estas acciones sobre el objeto, independientemente de lo que conceda su rol, y falla al guardar un permiso de objeto que concede una de ellas. Las funciones de lógica propias de tu aplicación las conservan. Por ejemplo, `['canUpdateObjectRecords', 'canSoftDeleteObjectRecords', 'canDestroyObjectRecords']` hace que un objeto solo pueda ser escrito por tu aplicación, para registros similares a configuraciones que conceden comportamiento.
* `color` establece el color de acento del objeto en la IU. Omítelo y Twenty elegirá uno para el objeto.
* `imageIdentifierFieldMetadataUniversalIdentifier` nombra el campo cuyo valor se muestra como el avatar del registro. Omítelo para que Twenty elija el predeterminado.
* `isLabelSyncedWithName`, en un objeto o en un campo, mantiene el nombre de la API sincronizado con la etiqueta cuando esta se edita en Configuración. De forma predeterminada es `false`, por lo que una etiqueta renombrada deja el nombre sin cambios.
* `isSearchable: true`, en un campo, incluye sus valores en la búsqueda de texto completo del objeto (búsqueda global y el menú de comandos). Requiere que el propio objeto permita búsquedas y que el tipo de campo sea compatible con texto. Un valor omitido significa que no permite búsquedas, excepto en el campo identificador de etiqueta del objeto, que siempre permite búsquedas y no se puede excluir. Cada sincronización aplica el estado declarado, por lo que un campo cuya opción de búsqueda se active desde Configuración se revertirá en la siguiente sincronización de tu aplicación, a menos que el manifiesto lo declare.
* `isAuditLogged: false` en un campo evita que sus cambios aparezcan en la cronología del registro. De forma predeterminada es `true`, excepto en un campo `POSITION`, cuyos cambios aparecen en blanco en la cronología y nunca se registran. Establécelo en los campos que tu aplicación reescribe de forma programada, como una marca de tiempo del último contacto o una relación de acumulación, para que cada sincronización no agregue una fila de actividad a cada registro que modifique. Una actualización cuyo diferencial completo está compuesto por campos sin registro de auditoría no produce ninguna actividad en la cronología. Al igual que `isSearchable`, cada sincronización aplica el estado declarado.
* `disabledFieldPermissionActions`, en un campo, enumera los permisos de campo que no se pueden conceder en él: `'canReadFieldValue'`, `'canUpdateFieldValue'` o ambos, los mismos indicadores que un rol establece por campo. Los usuarios, las claves de API, los agentes y otras aplicaciones nunca obtienen estas acciones en el campo, independientemente de lo que conceda su rol, y guardar un permiso de campo que conceda una de ellas falla. Las funciones de lógica de tu propia aplicación las conservan. Por ejemplo, `['canUpdateFieldValue']` mantiene un valor que tu aplicación calcula o sincroniza, como un estado o una puntuación, en modo de solo lectura para todos los demás. También funciona en los campos que agregas a objetos que no te pertenecen con `defineField()`.
* Los campos en línea definidos aquí **no** necesitan un `objectUniversalIdentifier`, ya que se hereda del objeto padre. Usa [`defineField()`](/es/developers/extend/apps/data/extending-objects) para añadir campos a objetos que no te pertenecen.
* Puedes generar nuevos objetos con `twenty app add object`, que te guía en la asignación de nombres, los campos y las relaciones. Consulta [Arquitectura → Generación de entidades](/es/developers/extend/apps/getting-started/scaffolding).

<Note>
  **Los campos base se añaden automáticamente.** Cuando defines un objeto personalizado,
  Twenty crea campos estándar como `id`, `name`, `createdAt`, `updatedAt`,
  `createdBy`, `updatedBy` y `deletedAt` por ti. No necesitas declararlos
  en tu matriz `fields`; solo tus campos personalizados. Puedes sobrescribir un
  campo predeterminado declarando uno con el mismo nombre, pero esto rara vez es una buena
  idea.
</Note>

## Tipos de campo

El conjunto completo de valores de `FieldType`, exportados desde `twenty-sdk/define`:

| Categoría                    | Tipos                                                                                                                                                                                                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Texto                        | `TEXT`, `RICH_TEXT`, `ARRAY` (de cadenas), `RAW_JSON`                                                                                                                                                                                                                                                              |
| Numérico                     | `NUMBER` (`universalSettings.dataType`: `'float'` / `'int'` / `'bigint'`), `NUMERIC` (precisión arbitraria), `RATING`, `POSITION`                                                                                                                                                                                  |
| Fechas                       | `DATE`, `DATE_TIME`                                                                                                                                                                                                                                                                                                |
| Selección                    | `BOOLEAN`, `SELECT`, `MULTI_SELECT`                                                                                                                                                                                                                                                                                |
| Compuesto                    | `FULL_NAME`, `ADDRESS`, `EMAILS`, `PHONES`, `LINKS` (`universalSettings.type`: `'url'` (predeterminado) / `'domain'` — un campo de dominio almacena el host sin más, por lo que `https://www.acme.com/careers` se escribe como `acme.com`, y se rechaza un valor que no sea un host), `CURRENCY`, `ACTOR`, `FILES` |
| Identificadores y relaciones | `UUID`, `RELATION`, `MORPH_RELATION` (ver [Relations](/es/developers/extend/apps/data/relations))                                                                                                                                                                                                                     |
| Sistema                      | `TS_VECTOR` (vector de búsqueda de texto completo, gestionado por el servidor)                                                                                                                                                                                                                                     |

Los tipos compuestos almacenan múltiples subcampos (por ejemplo, `FULL_NAME` = nombre + apellido; `CURRENCY` = `amountMicros` + `currencyCode`). `SELECT` y `MULTI_SELECT` requieren un arreglo `options` como en el ejemplo anterior.

### Selecciona opciones

Para `SELECT` y `MULTI_SELECT`, proporcione una matriz no vacía de objetos `options`. Cada opción tiene un `value`, un `label` y una `position`. Su `color` es opcional y toma de forma predeterminada el valor `gray` cuando se omite o es nulo.

Cuando se proporciona, `color` debe ser uno de los siguientes: `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`.

Tanto `defineObject()` como `defineField()` devuelven errores de validación para colores no compatibles o entradas de opciones que son nulas, primitivas o matrices.

## Valores predeterminados

Los valores predeterminados de cadenas literales deben ir entre comillas simples **dentro** de la cadena — `defaultValue: "'Draft'"`, no `defaultValue: "Draft"`. Por eso el campo `status` anterior utiliza `` `'${PostCardStatus.DRAFT}'` ``.

Las cadenas sin comillas se reservan para valores predeterminados calculados, evaluados cuando se crea un registro:

* `'uuid'` — genera un UUID (para campos `UUID`)
* `'now'` — la marca de tiempo actual (para campos `DATE_TIME`)

La misma convención se aplica a los subcampos de tipo cadena de los valores predeterminados compuestos (por ejemplo, `{ source: "'MANUAL'" }` en un campo `ACTOR`) y a los valores de `SELECT`/`MULTI_SELECT`. Un valor predeterminado de tipo cadena literal dejado sin comillas genera una advertencia cuando se compila tu aplicación.

## Nulabilidad

`isNullable` controla si un campo acepta `NULL`. Su valor predeterminado es `true` — omítelo para campos opcionales. Configura `isNullable: false` para hacer que un campo sea obligatorio a nivel de base de datos.

Los cambios en `isNullable` se aplican en cada sincronización, incluidas las sincronizaciones que actualizan un campo existente; de este modo, puedes cambiar la nulabilidad de un campo editando el manifiesto y sincronizando de nuevo.

<Note>
  **Hacer que un campo existente no acepte valores nulos requiere un valor predeterminado.** Cuando
  cambies un campo a `isNullable: false`, también debes proporcionar un `defaultValue` no nulo. El valor predeterminado rellena cualquier fila `NULL` existente antes de que se aplique la restricción `NOT
    NULL`; sin él, la sincronización falla con `Default value
    cannot be null for non-nullable fields`. Los campos de relación y los campos `TS_VECTOR`
  siempre aceptan valores nulos, por lo que `isNullable` no tiene ningún efecto en ellos.
</Note>

```ts
{
  universalIdentifier: 'b1a7c0de-1234-4f00-9abc-000000000000',
  name: 'reference',
  type: FieldType.TEXT,
  label: 'Reference',
  isNullable: false,
  defaultValue: "'N/A'",
}
```

## ¿Qué sigue

* **Conecta este objeto con otros**: consulta [Relaciones](/es/developers/extend/apps/data/relations) para el patrón de relación bidireccional.
* **Añade campos a objetos de otras aplicaciones**: consulta [Extender objetos](/es/developers/extend/apps/data/extending-objects) para `defineField()`.
* **Mostrar este objeto en la IU** — consulta [Elementos del menú de navegación](/es/developers/extend/apps/layout/navigation-menu-items) para añadir una entrada en la barra lateral; consulta [Vistas](/es/developers/extend/apps/layout/views) para añadir configuraciones de lista personalizadas.

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