# 画板数据结构

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

## IBoardData

`IBoardData` 是 Univer 画板使用的快照格式。它用于描述一个画板单元，包括页面顺序、页面数据、资源、主题、当前页面、缩放比例和画板级设置。

### 属性

| 属性              | 类型                                  | 说明                     |           |
| --------------- | ----------------------------------- | ---------------------- | --------- |
| 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，不要直接修改快照对象。