# Board Data Structure

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

## IBoardData

`IBoardData` is the snapshot format used by Univer Boards. It describes one Board unit, including page order, page data, resources, themes, active page, zoom ratio, and board-level settings.

### Properties

| Property        | Type                                | Description                                                               |                               |
| --------------- | ----------------------------------- | ------------------------------------------------------------------------- | ----------------------------- |
| id              | `string`                            | Unique id of the Board unit.                                              |                               |
| rev?            | `number`                            | Optional revision value used by persistence or collaboration layers.      |                               |
| name            | `string`                            | Board name.                                                               |                               |
| appVersion      | `string`                            | Version of the package that created the snapshot.                         |                               |
| locale?         | `string`                            | Locale of the board.                                                      |                               |
| defaultPageSize | `IBoardPageSize`                    | Default page size for board pages.                                        |                               |
| pageOrder       | `string[]`                          | Ordered list of board page ids.                                           |                               |
| pages           | `Record\<string, IBoardPage\>`      | Page snapshots keyed by page id.                                          |                               |
| activePageId?   | `string`                            | Active page id.                                                           |                               |
| theme?          | `IBoardThemeData`                   | Current board theme.                                                      |                               |
| themes?         | `Record\<string, IBoardThemeData\>` | Additional named themes.                                                  |                               |
| zoomRatio?      | `number`                            | Current zoom ratio.                                                       |                               |
| resources?      | `IResources`                        | External resources used by images, rich text, tables, and other elements. |                               |
| custom?         | \`Record\<string, unknown>          | null\`                                                                    | Application-defined metadata. |
| boardSettings?  | `IBoardSettings`                    | Board-level UI and interaction settings.                                  |                               |

### Page data

`IBoardPage` stores elements by id and uses `elementOrder` to define rendering order. Keep both structures in sync when constructing a snapshot yourself.

```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',
}
```

## Usage

`IBoardData` is mainly used to:

1. Create a `UniverInstanceType.UNIVER_BOARD` unit.
2. Persist and restore Board documents.
3. Prepare data for import, export, or server-side processing.
4. Seed a Board with pages, elements, and settings before rendering.

> [!WARNING]
> Snapshot objects are persistence data. After a Board is running, prefer Facade APIs instead of mutating the snapshot object directly.