Enregistrements, liens et hiérarchie

Un enregistrement représente une tâche, un client, une commande ou un autre objet métier. Utilisez l’API Facade pour écrire par lots, lire par pages, relier des tables et organiser les relations parent-enfant.

Créer et lire des enregistrements

const base = univerAPI.getActiveBase()if (!base) throw new Error('Open a Base first')const table = base.insertTable('Tasks', { primaryFieldName: 'Title' })const titleId = table.getPrimaryFieldId()const records = table.addRecords([  { values: { [titleId]: 'Write documentation' } },  { values: { [titleId]: 'Review examples' } },])records[0].setValue(titleId, 'Publish documentation')const page = table.queryRecords({ offset: 0, limit: 20 })console.log(page.total, page.records)

Par défaut, les valeurs utilisent les ID de champs comme clés. Passez univerAPI.Enum.BaseFieldKeyEnum.Name pour des données indexées par nom de champ. queryRecords() interroge les données locales chargées, sans récupérer de pages du backend. Utilisez viewId pour lire le périmètre d’une vue ou sort pour définir l’ordre.

Supprimez un lot avec table.deleteRecords(recordIds) ou dupliquez un enregistrement avec record.duplicate(). Ces opérations utilisent le système de commandes et prennent en charge l’annulation et le rétablissement.

Rechercher des enregistrements

Recherchez du texte dans les champs sélectionnés :

const matches = table.search({ query: 'documentation', fieldIds: [titleId], limit: 20 })console.log(matches)

Relier une autre table

Par exemple, reliez chaque tâche à un projet :

const projects = base.insertTable('Projects', { primaryFieldName: 'Name' })const project = projects.addRecord({ [projects.getPrimaryFieldId()]: 'Website' })const projectField = table.addField('Project', univerAPI.Enum.BaseFieldType.RecordLink, {  field: { config: { targetTableId: projects.getId(), multiple: false } },})records[0].setLinkedRecordIds(projectField.getId(), [project.getId()])console.log(records[0].getLinkedRecordIds(projectField.getId()))

Les cibles doivent appartenir à la même Base. Définissez multiple: true pour plusieurs enregistrements liés, displayFieldId pour le libellé affiché et pickerFieldIds pour fournir des informations supplémentaires dans le sélecteur. Utilisez les API de liens pour lire et écrire les ID au lieu de construire les chaînes de stockage internes.

Enregistrements parent-enfant

Faites d’une revue d’API un enfant de la tâche de documentation :

const parent = records[0]const parentFieldId = table.getHierarchyFieldId()const child = parent.addChild(parentFieldId, { [titleId]: 'Check API examples' })console.log(child.getParent(parentFieldId)?.getId())child.setParent(parentFieldId, null)

La première insertion d’un enfant crée automatiquement le champ de lien parent requis. Utilisez getChildren(), getAncestors() et getDescendants() pour lire les relations. Les hiérarchies acceptent jusqu’à cinq niveaux ; se définir comme son propre parent et créer des cycles sont des opérations refusées. Traitez les erreurs d’opération invalide dans votre interface.

La hiérarchie appartient aux données de la table et ne change pas lors d’un changement ou d’un filtrage de vue. Consultez Bases Facade pour les autres méthodes.