# 文件資料結構

- Human documentation: [https://docs.univer.ai/zh-TW/guides/docs/model/document-data](https://docs.univer.ai/zh-TW/guides/docs/model/document-data)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/docs/model/document-data.md](https://docs.univer.ai/zh-TW/guides/docs/model/document-data.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [docs/model/document-data.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/model/document-data.zh-TW.mdx)

---

## IDocumentData

[`IDocumentData`](https://docs.univer.ai/zh-TW/guides/docs/model/document-data.md) 是 Univer Docs 使用的快照格式。

它用於描述完整的文件單元，包括正文、文件級樣式、頁首頁尾、圖片、清單、表格以及插件資源。

### 屬性

| 屬性             | 類型                  | 描述                                             |
| -------------- | ------------------- | ---------------------------------------------- |
| id             | `string`            | 文件單元的唯一 ID。                                    |
| rev?           | `number`            | 文件版本號，用於協同編輯。                                  |
| locale?        | `LocaleType`        | 文件語言環境。                                        |
| title?         | `string`            | 文件標題。                                          |
| body?          | `IDocumentBody`     | 正文富文字內容。[詳情](https://docs.univer.ai/zh-TW/guides/docs/model/document-body.md) |
| documentStyle  | `IDocumentStyle`    | 文件級頁面、排版、頁首頁尾和預設文字樣式設定。                        |
| settings?      | `IDocumentSettings` | 執行時設定，例如 `zoomRatio`。                          |
| resources?     | `IResources`        | 插件資源。                                          |
| disabled?      | `boolean`           | 文件是否停用。                                        |
| headers?       | `IHeaders`          | 以頁首 ID 為 key 的頁首正文。                            |
| footers?       | `IFooters`          | 以頁尾 ID 為 key 的頁尾正文。                            |
| lists?         | `ILists`            | 段落項目符號使用的清單定義。                                 |
| drawings?      | `IDrawings`         | 圖片等繪圖物件。                                       |
| drawingsOrder? | `string[]`          | 繪圖物件渲染順序。                                      |
| tableSource?   | `ITables`           | 被正文引用的表格定義。                                    |

### 範例

```typescript
const documentData: IDocumentData = {
  id: 'doc-1',
  title: '範例文件',
  locale: LocaleType.ZH_TW,
  body: {
    dataStream: 'Hello Univer\r\n',
    textRuns: [
      {
        st: 0,
        ed: 12,
        ts: { fs: 14 },
      },
    ],
    paragraphs: [
      {
        startIndex: 12,
        paragraphId: 'paragraph-1',
      },
    ],
  },
  documentStyle: {
    pageSize: { width: 595, height: 842 },
    marginTop: 72,
    marginBottom: 72,
    marginLeft: 72,
    marginRight: 72,
  },
}
```

### 使用場景

`IDocumentData` 主要用於：

1. [建立 Univer Docs 文件](https://docs.univer.ai/zh-TW/guides/docs/features/core/docs-api.md#create-document)
2. [儲存 Univer Docs 快照](https://docs.univer.ai/zh-TW/guides/docs/features/core/docs-api.md#get-document-data)
3. [匯入或匯出 `.docx` 檔案](https://docs.univer.ai/zh-TW/guides/docs/features/import-export.md)
4. 透過 `ICellData.p` 在 Sheets 儲存格中儲存富文字

> [!WARNING]
> 快照是用於持久化的資料結構。文件執行後不要直接修改快照物件，請透過 Facade API 或命令修改文件內容。