# 表、字段与记录

- Human documentation: [https://docs.univer.ai/zh-CN/guides/bases/model/tables-fields-records](https://docs.univer.ai/zh-CN/guides/bases/model/tables-fields-records)

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

一个 Base 包含若干按顺序排列的表。每个表都包含字段定义、记录值、可选的单元格数据矩阵、资源、视图，以及供渲染和查询逻辑使用的索引。

新建表默认包含零条记录；请通过 Facade API 或导入的快照数据显式添加记录。

## 表快照

| 属性             | 类型                                  | 说明              |
| -------------- | ----------------------------------- | --------------- |
| id             | `string`                            | 表 ID。           |
| name           | `string`                            | 表名称。            |
| fields         | `Record\<string, IFieldSnapshot\>`  | 以字段 ID 为键的字段定义。 |
| fieldOrder     | `string[]`                          | 按顺序排列的字段 ID 列表。 |
| records        | `Record\<string, IRecordSnapshot\>` | 以记录 ID 为键的记录数据。 |
| recordOrder?   | `string[]`                          | 按顺序排列的记录 ID 列表。 |
| primaryFieldId | `string`                            | 主字段 ID。         |
| views          | `Record\<string, IViewSnapshot\>`   | 以视图 ID 为键的视图。   |
| viewOrder      | `string[]`                          | 按顺序排列的视图 ID 列表。 |
| resources?     | `IBaseResources`                    | 共享的选项、成员和附件资源。  |

## 字段快照

| 属性            | 类型                          | 说明          |
| ------------- | --------------------------- | ----------- |
| id            | `string`                    | 字段 ID。      |
| name          | `string`                    | 字段名称。       |
| description?  | `string`                    | 字段说明。       |
| type          | `BaseFieldType`             | 字段类型。       |
| config        | `Record\<string, unknown\>` | 该字段类型专用的配置。 |
| defaultValue? | `BaseCellValue`             | 新记录的默认值。    |
| system?       | `boolean`                   | 该字段是否由系统管理。 |
| readonly?     | `boolean`                   | 字段值是否只读。    |

## 字段类型

常见的字段类型包括 `text`、`number`、`currency`、`progress`、`rating`、`checkbox`、`singleSelect`、`multiSelect`、`person`、`group`、`date`、`attachment`、`formula`、`createdAt`、`updatedAt`、`createdBy` 和 `updatedBy`。

编写应用代码时，请使用 Facade 枚举：

```ts
const field = table.addField('Due date', univerAPI.Enum.BaseFieldType.Date)
```

## 记录快照

| 属性         | 类型                                | 说明           |
| ---------- | --------------------------------- | ------------ |
| id         | `string`                          | 记录 ID。       |
| values     | `Record\<string, BaseCellValue\>` | 以字段 ID 为键的值。 |
| orderKey   | `string`                          | 稳定的排序键。      |
| createdAt  | `number`                          | 创建时间戳。       |
| updatedAt  | `number`                          | 更新时间戳。       |
| createdBy? | `string`                          | 创建者 ID。      |
| updatedBy? | `string`                          | 最后更新者的 ID。   |

## Facade 示例

```ts
const table = base.insertTable('Tasks', { primaryFieldName: 'Title' })
const title = table.getPrimaryField()
const status = table.addField('Status', univerAPI.Enum.BaseFieldType.SingleSelect)

const record = table.addRecord({
  [title.getId()]: 'Write guide',
  [status.getId()]: 'In progress',
})
```