#Коллекции

При разработке плагинов NocoBase коллекция (таблица данных) является одной из ключевых концепций. Вы можете добавлять или изменять структуры таблиц данных в плагинах, определяя или расширяя коллекции. В отличие от таблиц данных, созданных через интерфейс управления источниками данных, коллекции, определенные в коде, обычно представляют собой таблицы метаданных системного уровня и не отображаются в списке управления источниками данных.

#Определение таблиц данных

Следуя стандартной структуре каталогов, файлы коллекций следует размещать в каталоге ./src/server/collections. Используйте defineCollection() для создания новых таблиц и extendCollection() для расширения существующих таблиц.

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

export default defineCollection({
  name: 'articles',
  title: 'Sample Articles',
  fields: [
    { type: 'string', name: 'title', interface: 'input', uiSchema: { title: 'Title', required: true } },
    { type: 'text', name: 'content', interface: 'textarea', uiSchema: { title: 'Content' } },
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
      interface: 'recordPicker',
      uiSchema: { title: 'Author' },
    },
  ],
});

В примере выше:

• name: Имя таблицы (в базе данных автоматически будет создана таблица с таким же именем).
• title: отображаемое название таблицы в интерфейсе.
• fields: набор полей; каждое поле содержит type, name и другие атрибуты.

Когда вам нужно добавить поля или изменить конфигурацию коллекций других плагинов, вы можете использовать extendCollection():

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

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

После активации плагина система автоматически добавит поле isPublished в существующую таблицу articles.

#Краткий справочник по типам полей

В fields метода defineCollection параметр type определяет тип колонки поля в базе данных. Ниже перечислены все встроенные типы полей:

#Текст

#Числа

#Логический тип

#Дата и время

#Структурированные данные

#Генерация идентификаторов

#Специальные типы

#Типы связей

Поля связей не создают колонок в базе данных, а устанавливают связи между таблицами на уровне ORM:

Пример использования полей связей:

export default defineCollection({
  name: 'articles',
  fields: [
    { type: 'string', name: 'title' },
    // Многие к одному: статья принадлежит одному автору
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
    },
    // Один ко многим: у статьи несколько комментариев
    {
      type: 'hasMany',
      name: 'comments',
      target: 'comments',
      foreignKey: 'articleId',
    },
    // Многие ко многим: у статьи несколько тегов
    {
      type: 'belongsToMany',
      name: 'tags',
      target: 'tags',
      through: 'articlesTags',  // имя промежуточной таблицы
    },
  ],
});

#Общие параметры

Все поля-колонки поддерживают следующие параметры:

#Синхронизация структуры базы данных

При первой активации плагина система автоматически синхронизирует конфигурацию коллекции со структурой базы данных. Если плагин уже установлен и запущен, после добавления или изменения коллекций необходимо вручную выполнить команду обновления:

yarn nocobase upgrade

#Отображение коллекции в списке таблиц данных интерфейса

Таблицы, определённые через defineCollection, являются внутренними серверными таблицами и по умолчанию не отображаются в списке управления источниками данных, а также в списке выбора таблиц данных при добавлении блока.

Рекомендуемый подход: добавьте соответствующую таблицу данных в разделе «Управление источниками данных» интерфейса NocoBase. После настройки полей и типов интерфейса таблица автоматически появится в списке выбора таблиц данных блока.

Если регистрацию действительно необходимо выполнить в коде плагина (например, для демонстрационных сценариев в плагинах-примерах), можно зарегистрировать коллекцию вручную через addCollection в клиентском плагине. Обратите внимание, что регистрация должна выполняться по шаблону eventBus и не может вызываться напрямую в load() — метод ensureLoaded() после load() очищает и заново устанавливает все коллекции. Полный пример см. в разделе Создание плагина управления данными с интеграцией фронтенда и бэкенда.

#Автогенерация ресурсов

После определения коллекции система автоматически сгенерирует соответствующий ресурс, в котором вы сможете напрямую выполнять CRUD-операции через API. См. Менеджер ресурсов.

#Связанные ссылки

• База данных — CRUD, Repository, транзакции и события базы данных
• Менеджер источников данных — управление несколькими источниками данных и их коллекциями
• Миграция — скрипты миграции данных при обновлении плагинов
• Плагин — жизненный цикл класса Plugin, методы класса и объект app
• Менеджер ресурсов — пользовательские REST API и обработчики операций
• Создание плагина управления данными с интеграцией фронтенда и бэкенда — полный пример с defineCollection + addCollection
• Структура проекта — описание соглашения о каталоге src/server/collections