#Collections - tables de données

Dans le développement de plugins NocoBase, la Collection (table de données) est l'un des concepts les plus fondamentaux. Vous pouvez ajouter ou modifier la structure des tables d'un plugin en définissant ou en étendant des Collections. Contrairement aux tables créées via l'interface « Gestion des sources de données », les Collections définies par code sont en général des tables de métadonnées au niveau système et n'apparaissent pas dans la liste de gestion des sources de données.

#Définir une table

Selon la convention de répertoire, les fichiers de Collection doivent être placés dans ./src/server/collections. Pour créer une nouvelle table, utilisez defineCollection() ; pour étendre une table existante, utilisez extendCollection().

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

export default defineCollection({
  name: 'articles',
  title: 'Articles d\'exemple',
  fields: [
    { type: 'string', name: 'title', interface: 'input', uiSchema: { title: 'Titre', required: true } },
    { type: 'text', name: 'content', interface: 'textarea', uiSchema: { title: 'Contenu' } },
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
      interface: 'recordPicker',
      uiSchema: { title: 'Auteur' },
    },
  ],
});

Dans l'exemple ci-dessus :

• name : nom de la table (une table portant le même nom est générée automatiquement dans la base de données).
• title : nom d'affichage de la table dans l'interface.
• fields : ensemble des champs ; chaque champ contient des propriétés telles que type, name, etc.

Lorsque vous avez besoin d'ajouter des champs ou de modifier la configuration de la Collection d'un autre plugin, utilisez extendCollection() :

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

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

Une fois le plugin activé, le système ajoute automatiquement le champ isPublished à la table articles existante.

#Aide-mémoire des types de champs

Dans les fields de defineCollection, le type détermine le type de colonne dans la base de données. Voici tous les types de champs intégrés :

#Texte

#Numérique

#Booléen

#Date et heure

#Données structurées

#Génération d'ID

#Types spéciaux

#Types de relation

Les champs de relation ne créent pas de colonnes en base, mais établissent des relations entre tables au niveau ORM :

Exemples d'utilisation des champs de relation :

export default defineCollection({
  name: 'articles',
  fields: [
    { type: 'string', name: 'title' },
    // Plusieurs-à-un : un article appartient à un auteur
    {
      type: 'belongsTo',
      name: 'author',
      target: 'users',
      foreignKey: 'authorId',
    },
    // Un-à-plusieurs : un article a plusieurs commentaires
    {
      type: 'hasMany',
      name: 'comments',
      target: 'comments',
      foreignKey: 'articleId',
    },
    // Plusieurs-à-plusieurs : un article a plusieurs tags
    {
      type: 'belongsToMany',
      name: 'tags',
      target: 'tags',
      through: 'articlesTags',  // Nom de la table intermédiaire
    },
  ],
});

#Paramètres communs

Tous les champs de colonne prennent en charge les paramètres suivants :

#Synchroniser la structure de la base

Lors de la première activation du plugin, le système synchronise automatiquement la configuration des Collections avec la structure de la base de données. Si le plugin est déjà installé et en cours d'exécution, après l'ajout ou la modification de Collections, vous devez exécuter manuellement la commande de mise à niveau :

yarn nocobase upgrade

En cas d'anomalie ou de données corrompues lors de la synchronisation, vous pouvez reconstruire la structure des tables en réinstallant l'application :

yarn nocobase install -f

Si la mise à niveau du plugin nécessite une migration des données existantes — par exemple renommer un champ, scinder une table ou remplir des valeurs par défaut —, utilisez les scripts de migration plutôt que de modifier la base de données à la main.

#Faire apparaître une Collection dans la liste des tables de l'UI

Une table définie via defineCollection est une table interne au serveur ; par défaut elle n'apparaît pas dans la liste de « Gestion des sources de données » et n'apparaît pas non plus dans la liste de sélection de table lors de l'« Ajout d'un bloc ».

Approche recommandée : ajoutez la table correspondante via « Gestion des sources de données » dans l'interface NocoBase ; une fois les champs et les types d'interface configurés, la table apparaîtra automatiquement dans la liste de sélection de table des blocs.

S'il est vraiment nécessaire de l'enregistrer côté code (par exemple dans un scénario de démonstration de plugin), vous pouvez l'enregistrer manuellement dans le plugin client via addCollection. Attention : il faut impérativement passer par le mode eventBus ; vous ne pouvez pas l'appeler directement dans load() — ensureLoaded() videra et redéfinira l'ensemble des collections après load(). Voir l'exemple complet dans Construire un plugin de gestion de données front-end + back-end.

#Ressources (Resource) générées automatiquement

Une fois la Collection définie, NocoBase génère automatiquement des ressources REST API correspondantes : les opérations CRUD prêtes à l'emploi (list, get, create, update, destroy) ne nécessitent aucun code supplémentaire. Si les opérations CRUD intégrées ne suffisent pas — par exemple si vous avez besoin d'une API d' « import en lot » ou d' « agrégation statistique » —, vous pouvez enregistrer une action personnalisée via resourceManager. Voir ResourceManager - gestion des ressources pour plus de détails.

#Liens connexes

• Database — CRUD, Repository, transactions et événements de base de données
• DataSourceManager - gestion des sources de données — Gérer plusieurs sources de données et leurs collections
• Migration de données — Scripts de migration de données lors de la mise à niveau d'un plugin
• Plugin — Cycle de vie d'une classe de plugin, méthodes membres et objet app
• ResourceManager - gestion des ressources — API REST personnalisées et handlers d'action
• Construire un plugin de gestion de données front-end + back-end — Exemple complet defineCollection + addCollection
• Structure du projet — Détail de la convention du répertoire src/server/collections