#Coleções

No desenvolvimento de plugins NocoBase, a coleção (tabela de dados) é um dos conceitos mais importantes. Você pode adicionar ou modificar estruturas de tabelas de dados em plugins definindo ou estendendo coleções. Diferente das tabelas de dados criadas pela interface de gerenciamento de fontes de dados, as coleções definidas via código são geralmente tabelas de metadados de nível de sistema e não aparecerão na lista de gerenciamento de fontes de dados.

#Definindo Coleções

Seguindo a estrutura de diretórios convencional, os arquivos de coleção devem ser colocados no diretório ./src/server/collections. Use defineCollection() para criar novas tabelas e extendCollection() para estender tabelas existentes.

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

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

No exemplo acima:

• name: Nome da tabela (uma tabela com o mesmo nome será gerada automaticamente no banco de dados).
• title: Nome de exibição da tabela na interface.
• fields: Coleção de campos, onde cada campo contém atributos como type, name, etc.

Quando você precisar adicionar campos ou modificar configurações para coleções de outros plugins, você pode usar extendCollection():

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

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

Após ativar o plugin, o sistema adicionará automaticamente o campo isPublished à tabela articles existente.

#Referência Rápida de Tipos de Campo

Em fields do defineCollection, o type determina o tipo da coluna do campo no banco de dados. A seguir estão todos os tipos de campo integrados:

#Texto

#Números

#Booleanos

#Data e Hora

#Dados Estruturados

#Geração de ID

#Tipos Especiais

#Tipos de Relação

Os campos de relação não criam colunas no banco de dados; em vez disso, estabelecem relações entre tabelas na camada ORM:

Exemplo de uso dos campos de relação:

export default defineCollection({
  name: 'articles',
  fields: [
    { type: 'string', name: 'title' },
    // Muitos para um: o artigo pertence a um autor
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
    },
    // Um para muitos: o artigo tem vários comentários
    {
      type: 'hasMany',
      name: 'comments',
      target: 'comments',
      foreignKey: 'articleId',
    },
    // Muitos para muitos: o artigo tem várias tags
    {
      type: 'belongsToMany',
      name: 'tags',
      target: 'tags',
      through: 'articlesTags',  // nome da tabela intermediária
    },
  ],
});

#Parâmetros Comuns

Todos os campos de coluna suportam os seguintes parâmetros:

#Sincronizando a Estrutura do Banco de Dados

Quando um plugin é ativado pela primeira vez, o sistema sincroniza automaticamente as configurações da coleção com a estrutura do banco de dados. Se o plugin já estiver instalado e em execução, após adicionar ou modificar coleções, você precisará executar manualmente o comando de atualização:

yarn nocobase upgrade

#Fazendo uma Coleção Aparecer na Lista de Tabelas de Dados da Interface

As tabelas definidas via defineCollection são tabelas internas do servidor e, por padrão, não aparecem na lista do gerenciamento de fontes de dados, nem na lista de seleção de tabelas de dados ao adicionar um bloco.

Abordagem recomendada: adicione a tabela de dados correspondente em "Gerenciamento de fontes de dados" na interface do NocoBase. Depois de configurar os campos e os tipos de interface, a tabela aparecerá automaticamente na lista de seleção de tabelas de dados do bloco.

Se você realmente precisar registrar pelo código do plugin (por exemplo, em cenários de demonstração de plugins de exemplo), pode registrar manualmente via addCollection no plugin do cliente. Observe que o registro precisa ser feito através do padrão eventBus e não pode ser chamado diretamente em load() — o ensureLoaded() limpa e redefine todas as coleções depois do load(). Veja o exemplo completo em Construir um plugin de gestão de dados com integração front-back.

#Geração Automática de Recursos (Resource)

Após definir uma coleção, o sistema gerará automaticamente um Recurso (Resource) correspondente, no qual você pode executar operações CRUD diretamente via API. Veja Gerenciador de Recursos.

#Links relacionados

• Database — CRUD, Repository, transações e eventos do banco de dados
• DataSourceManager — gerenciamento de várias fontes de dados e suas coleções
• Migration — scripts de migração de dados para upgrades de plugins
• Plugin — ciclo de vida da classe Plugin, métodos membros e o objeto app
• ResourceManager — APIs REST personalizadas e handlers de operações
• Construir um plugin de gestão de dados com integração front-back — exemplo completo com defineCollection + addCollection
• Estrutura do Projeto — explicação da convenção do diretório src/server/collections