# 資料表、欄位與記錄

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [bases/model/tables-fields-records.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/bases/model/tables-fields-records.zh-TW.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',
})
```