# 보드 데이터 구조

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [boards/model/board-data.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/boards/model/board-data.ko-KR.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를 우선 사용하세요.