# 记录、关联与层级

- Human documentation: [https://docs.univer.ai/zh-CN/guides/bases/features/core/records](https://docs.univer.ai/zh-CN/guides/bases/features/core/records)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/bases/features/core/records.md](https://docs.univer.ai/zh-CN/guides/bases/features/core/records.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [bases/features/core/records.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/bases/features/core/records.zh-CN.mdx)

---

一条记录对应一个业务对象，例如任务、客户或订单。通过 Facade API 可以批量写入、分页读取、关联其他表，以及组织父子记录。

## 新建和读取记录

```ts
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)
```

记录值默认以字段 ID 为键。已有按字段名称组织的数据时，传入 `univerAPI.Enum.BaseFieldKeyEnum.Name`。`queryRecords()` 在已加载的本地数据上查询，不会自动请求后端分页；可用 `viewId` 按视图范围读取，或用 `sort` 指定排序。

删除一批记录使用 `table.deleteRecords(recordIds)`，复制一条记录使用 `record.duplicate()`。这些修改经过命令系统，支持撤销和重做。

## 搜索记录

在指定字段中搜索文本，返回匹配结果：

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

## 关联另一张表

例如，让每个任务关联一个项目：

```ts
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()))
```

关联目标必须在同一个 Base 中。`multiple: true` 允许多个目标记录；`displayFieldId` 控制显示名称，`pickerFieldIds` 控制选择器中的补充字段。使用关联 API 读写记录 ID，不要自己拼接底层存储字符串。

## 父子记录

例如，将“检查 API 示例”设为文档任务的子任务：

```ts
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)
```

第一次添加子记录时，会自动创建所需的父级关联字段。还可使用 `getChildren()`、`getAncestors()` 和 `getDescendants()` 读取层级关系。当前最多五层；不能将记录设为自己的父级，也不能产生循环关系。无效操作会抛出错误，业务界面应提示用户。

父子关系属于表数据，筛选或切换视图不会改变它。更多方法见 [Bases Facade](https://docs.univer.ai/zh-CN/reference/facade/bases.md)。