#Colecciones

En el desarrollo de plugins de NocoBase, la colección (tabla de datos) es uno de los conceptos centrales. Usted puede añadir o modificar estructuras de tablas de datos en sus plugins definiendo o extendiendo colecciones. A diferencia de las tablas de datos creadas a través de la interfaz de gestión de fuentes de datos, las colecciones definidas en el código suelen ser tablas de metadatos a nivel de sistema y no aparecerán en la lista de gestión de fuentes de datos.

#Definición de Colecciones

Siguiendo la estructura de directorios convencional, los archivos de colección deben ubicarse en el directorio ./src/server/collections. Para crear nuevas tablas, utilice defineCollection(), y para extender tablas existentes, utilice extendCollection().

import { defineCollection } from '@nocobase/database';

export default defineCollection({
  name: 'articles',
  title: 'Artículos de ejemplo',
  fields: [
    { type: 'string', name: 'title', interface: 'input', uiSchema: { title: 'Título', required: true } },
    { type: 'text', name: 'content', interface: 'textarea', uiSchema: { title: 'Contenido' } },
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
      interface: 'recordPicker',
      uiSchema: { title: 'Autor' },
    },
  ],
});

En el ejemplo anterior:

• name: Nombre de la tabla (se generará automáticamente una tabla con el mismo nombre en la base de datos).
• title: Nombre de visualización de la tabla en la interfaz.
• fields: Colección de campos; cada campo incluye atributos como type, name, entre otros.

Cuando necesite añadir campos o modificar configuraciones para las colecciones de otros plugins, puede utilizar extendCollection():

import { extendCollection } from '@nocobase/database';

export default extendCollection({
  name: 'articles',
  fields: [
    {
      type: 'boolean',
      name: 'isPublished',
      defaultValue: false,
    },
  ],
});

Después de activar el plugin, el sistema añadirá automáticamente el campo isPublished a la tabla articles existente.

#Referencia Rápida de Tipos de Campo

En el apartado fields de defineCollection, type determina el tipo de columna que tendrá el campo en la base de datos. A continuación se listan todos los tipos de campo integrados:

#Texto

#Números

#Booleanos

#Fecha y Hora

#Datos Estructurados

#Generación de ID

#Tipos Especiales

#Tipos de Relación

Los campos de relación no crean columnas en la base de datos, sino que establecen relaciones entre tablas en la capa ORM:

Ejemplo de uso de los campos de relación:

export default defineCollection({
  name: 'articles',
  fields: [
    { type: 'string', name: 'title' },
    // Muchos a uno: el artículo pertenece a un autor
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
    },
    // Uno a muchos: el artículo tiene varios comentarios
    {
      type: 'hasMany',
      name: 'comments',
      target: 'comments',
      foreignKey: 'articleId',
    },
    // Muchos a muchos: el artículo tiene varias etiquetas
    {
      type: 'belongsToMany',
      name: 'tags',
      target: 'tags',
      through: 'articlesTags',  // nombre de la tabla intermedia
    },
  ],
});

#Parámetros Comunes

Todos los campos de columna admiten los siguientes parámetros:

#Sincronización de la Estructura de la Base de Datos

Cuando un plugin se activa por primera vez, el sistema sincronizará automáticamente las configuraciones de la colección con la estructura de la base de datos. Si el plugin ya está instalado y en ejecución, después de añadir o modificar colecciones, deberá ejecutar manualmente el comando de actualización:

yarn nocobase upgrade

#Cómo Hacer que una Colección Aparezca en la Lista de Tablas de Datos de la Interfaz

Las tablas definidas mediante defineCollection son tablas internas del servidor y, por defecto, no aparecen en la lista de la gestión de fuentes de datos ni en la lista de selección de tablas de datos al añadir un bloque.

Enfoque recomendado: añada la tabla de datos correspondiente en la «Gestión de fuentes de datos» de la interfaz de NocoBase. Una vez configurados los campos y los tipos de interfaz, la tabla aparecerá automáticamente en la lista de selección de tablas de datos del bloque.

Si realmente necesita registrarla desde el código del plugin (por ejemplo, en escenarios de demostración de plugins de ejemplo), puede hacerlo manualmente mediante addCollection en el plugin del cliente. Tenga en cuenta que el registro debe realizarse a través del patrón eventBus y no puede invocarse directamente en load(): ensureLoaded() vaciará y volverá a establecer todas las colecciones después de load(). Puede consultar un ejemplo completo en Crear un plugin de gestión de datos full-stack.

#Generación Automática de Recursos

Después de definir una colección, el sistema generará automáticamente un recurso correspondiente, sobre el cual podrá realizar directamente operaciones CRUD (crear, leer, actualizar, eliminar) a través de la API. Consulte Gestor de Recursos para más información.

#Enlaces relacionados

• Database — CRUD, Repository, transacciones y eventos de base de datos
• DataSourceManager — gestión de múltiples fuentes de datos y sus colecciones
• Migration — scripts de migración de datos para las actualizaciones de plugins
• Plugin — ciclo de vida de la clase Plugin, métodos miembros y objeto app
• ResourceManager — API REST personalizadas y manejadores de operaciones
• Crear un plugin de gestión de datos full-stack — ejemplo completo con defineCollection + addCollection
• Estructura del proyecto — explicación de la convención del directorio src/server/collections