# 畫板資料結構

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

## IBoardData

`IBoardData` 是 Univer Boards 使用的快照格式，用於描述一個畫板單元，包括頁面順序、頁面資料、資源、主題、作用中頁面、縮放比例，以及畫板層級設定。

### 屬性

| 屬性              | 類型                                  | 說明                     |              |
| --------------- | ----------------------------------- | ---------------------- | ------------ |
| id              | `string`                            | 畫板單元的唯一 ID。            |              |
| rev?            | `number`                            | 供持久化或協作層使用的選用修訂值。      |              |
| name            | `string`                            | 畫板名稱。                  |              |
| appVersion      | `string`                            | 建立此快照的套件版本。            |              |
| locale?         | `string`                            | 畫板的語系。                 |              |
| defaultPageSize | `IBoardPageSize`                    | 畫板頁面的預設頁面大小。           |              |
| pageOrder       | `string[]`                          | 依序排列的畫板頁面 ID 清單。       |              |
| pages           | `Record\<string, IBoardPage\>`      | 以頁面 ID 為鍵的頁面快照。        |              |
| activePageId?   | `string`                            | 作用中頁面的 ID。             |              |
| theme?          | `IBoardThemeData`                   | 目前的畫板主題。               |              |
| themes?         | `Record\<string, IBoardThemeData\>` | 其他具名主題。                |              |
| zoomRatio?      | `number`                            | 目前的縮放比例。               |              |
| resources?      | `IResources`                        | 圖片、富文字、表格及其他元素使用的外部資源。 |              |
| custom?         | \`Record\<string, unknown>          | null\`                 | 應用程式自訂的中繼資料。 |
| boardSettings?  | `IBoardSettings`                    | 畫板層級的 UI 與互動設定。        |              |

### 頁面資料

`IBoardPage` 會依 ID 儲存元素，並使用 `elementOrder` 定義算繪順序。自行建構快照時，請讓這兩種結構保持同步。

```ts
const boardData = {
  id: 'board-1',
  name: 'Planning board',
  appVersion: '1.0.0',
  defaultPageSize: { width: 1920, height: 1080 },
  pageOrder: ['page-1'],
  pages: {
    'page-1': {
      id: 'page-1',
      pageType: 'page',
      name: 'Page 1',
      elementOrder: ['text-1'],
      elements: {
        'text-1': {
          id: 'text-1',
          type: 'text',
          transform: { left: 120, top: 96, width: 240, height: 80 },
          text: 'Kickoff',
        },
      },
    },
  },
  activePageId: 'page-1',
}
```

## 用途

`IBoardData` 主要用於：

1. 建立 `UniverInstanceType.UNIVER_BOARD` 單元。
2. 持久化及還原畫板文件。
3. 準備匯入、匯出或伺服器端處理所需的資料。
4. 在算繪前，預先為畫板加入頁面、元素與設定。

> [!WARNING]
> 快照物件是持久化資料。畫板開始執行後，請優先使用 Facade API，不要直接修改快照物件。