# 설치 및 기본 사용법

- Human documentation: [https://docs.univer.ai/ko-KR/guides/boards/getting-started/installation](https://docs.univer.ai/ko-KR/guides/boards/getting-started/installation)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/boards/getting-started/installation.md](https://docs.univer.ai/ko-KR/guides/boards/getting-started/installation.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [boards/getting-started/installation/index.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/boards/getting-started/installation/index.ko-KR.mdx)

---

이 장에서는 Univer Boards의 설치 방법과 기본 사용법을 소개합니다. Boards는 Univer Office SDK 제품으로 배포되며 현재 플러그인 모드를 사용합니다.

Univer의 핵심 개념이 익숙하지 않다면 먼저 [빠른 시작](https://docs.univer.ai/ko-KR/guides/boards/getting-started/quickstart.md)을 읽어보세요.

Univer는 *프리셋 모드*와 *플러그인 모드*의 두 가지 통합 방식을 제공합니다. 프리셋 모드는 미리 구성된 플러그인 묶음으로 설정을 간소화하여 쉽게 시작할 수 있습니다. **심층적인 커스터마이징이나 확장**이 필요하다면 플러그인을 개별적으로 조합하고 설정할 수 있는 플러그인 모드를 권장합니다.

## 플러그인 모드로 설정하기

Univer는 Boards를 여러 플러그인으로 제공합니다. 브라우저 편집기에서는 일반적으로 공유 Univer 런타임, 라이선스 플러그인, 문서 및 드로잉 종속성을 등록한 다음 Board 모델 및 UI 플러그인을 등록합니다.

### 패키지 관리자 사용

ES Modules와 `package.json`의 `exports` 필드를 지원하는 빌드 도구를 사용하세요.

#### 설치

Univer는 UI에 React를, 데이터 스트림에 RxJS를 사용하며 Vue나 Angular 앱에도 통합할 수 있습니다. peer dependencies[^peer-dependency]인 `react`, `react-dom`, `rxjs`가 설치되어 있는지 확인하세요. 아래 Yarn 명령에는 이 패키지들이 명시적으로 포함되어 있습니다.

모든 `@univerjs/*` 및 `@univerjs-pro/*` 패키지의 버전을 동일하게 유지하세요.

#### pnpm

```shell
pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui
```

#### npm

```shell
npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui
```

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui react react-dom rxjs
```

#### bun

```shell
bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui
```

#### 사용법

Univer를 초기화하기 전에 컨테이너를 만들고 높이를 명시하세요:

```html
<div id="app" style="height: 600px"></div>
```

`FUniver.newAPI(univer)`를 호출하기 전에 아래 예제에서 사용하는 facade 진입점을 가져오세요. CSS는 `@univerjs/design`, `@univerjs/ui`, 제품 CSS 순서로 가져오세요.

> [!WARNING: 주의]
> * Board 플러그인보다 먼저 `UniverLicensePlugin`을 등록하세요.
> * 제품 UI CSS보다 먼저 공유 UI CSS를 가져오세요.
> * 선택적 요소 유형이 포함된 스냅샷을 열기 전에 해당 요소 플러그인을 등록하세요.
> * `UniverBoardsUIPlugin`은 도형 기능에 필요한 `UniverProFormulaEnginePlugin`을 자동으로 로드합니다. 같은 `Univer` 인스턴스에 `UniverFormulaEnginePlugin`도 등록하는 경우 `@univerjs-pro/engine-formula`를 설치하고 초기화 코드에서 일반 엔진의 가져오기와 등록을 `UniverProFormulaEnginePlugin`으로 바꾸세요. 두 수식 엔진을 동시에 등록하지 마세요.

1.
   스타일, 로케일 팩 및 필수 플러그인을 가져옵니다.
   
   ```ts
   import { UniverBoardsPlugin } from '@univerjs-pro/boards'
   import { UniverBoardsUIPlugin } from '@univerjs-pro/boards-ui'
   import BoardsUIEnUS from '@univerjs-pro/boards-ui/locale/en-US'
   import { UniverInkUIPlugin } from '@univerjs-pro/ink-ui'
   import InkUIEnUS from '@univerjs-pro/ink-ui/locale/en-US'
   import { UniverLicensePlugin } from '@univerjs-pro/license'
   import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'
   import DesignEnUS from '@univerjs/design/locale/en-US'
   import { UniverDocsPlugin } from '@univerjs/docs'
   import { UniverDocsUIPlugin } from '@univerjs/docs-ui'
   import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'
   import { UniverDrawingPlugin } from '@univerjs/drawing'
   import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'
   import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US'
   import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
   import { UniverUIPlugin } from '@univerjs/ui'
   import UIEnUS from '@univerjs/ui/locale/en-US'
   
   import '@univerjs/design/lib/index.css'
   import '@univerjs/ui/lib/index.css'
   import '@univerjs/docs-ui/lib/index.css'
   import '@univerjs/drawing-ui/lib/index.css'
   import '@univerjs-pro/ink-ui/lib/index.css'
   import '@univerjs-pro/boards-ui/lib/index.css'
   ```

1.
   Facade API[^facade-entry]를 사용하려면 Facade 진입점을 가져옵니다.
   
   ```ts
   import { FUniver } from '@univerjs/core/facade'
   import '@univerjs-pro/boards/facade'
   ```

1.
   Univer 인스턴스를 만들고 플러그인을 등록한 다음 Board 유닛을 만듭니다.
   
   ```ts
   const univer = new Univer({
     locale: LocaleType.EN_US,
     locales: {
       [LocaleType.EN_US]: mergeLocales(
         DesignEnUS,
         UIEnUS,
         DocsUIEnUS,
         DrawingUIEnUS,
         InkUIEnUS,
         BoardsUIEnUS,
       ),
     },
   })
   
   univer.registerPlugin(UniverRenderEnginePlugin)
   univer.registerPlugin(UniverUIPlugin, { container: 'app' })
   univer.registerPlugin(UniverDocsPlugin)
   univer.registerPlugin(UniverDocsUIPlugin)
   univer.registerPlugin(UniverDrawingPlugin)
   univer.registerPlugin(UniverDrawingUIPlugin)
   univer.registerPlugin(UniverInkUIPlugin)
   univer.registerPlugin(UniverLicensePlugin, {
     license: process.env.CLIENT_LICENSE_TEXT,
   })
   univer.registerPlugin(UniverBoardsPlugin)
   univer.registerPlugin(UniverBoardsUIPlugin)
   
   univer.createUnit(UniverInstanceType.UNIVER_BOARD, {})
   
   const univerAPI = FUniver.newAPI(univer)
   ```

#### `univer.registerPlugin` 및 `univer.registerPlugins` 메서드

`univer.registerPlugin` 메서드는 Univer 인스턴스에 플러그인을 등록하는 데 사용합니다. Univer 인스턴스를 만든 뒤 이 메서드를 호출하여 플러그인을 등록할 수 있습니다.

`univer.registerPlugin(Plugin, options)` 메서드로 플러그인을 등록할 수 있습니다. 여기서 `Plugin`은 등록할 플러그인이고, `options`는 선택적 구성 항목입니다. 플러그인마다 구성 항목은 다를 수 있습니다.

`univer.registerPlugins`에 배열을 전달하여 여러 플러그인을 한 번에 등록할 수도 있습니다. 플러그인을 중앙에서 관리해야 할 때 유용합니다.

```typescript
univer.registerPlugins([
  UniverRenderEnginePlugin,
  [UniverUIPlugin, { container: 'app' }],
  UniverDocsPlugin,
  UniverDocsUIPlugin,
  UniverDrawingPlugin,
  UniverDrawingUIPlugin,
  UniverInkUIPlugin,
  [UniverLicensePlugin, {
    license: process.env.CLIENT_LICENSE_TEXT,
  }],
  UniverBoardsPlugin,
  UniverBoardsUIPlugin,
])
```

`FUniver.newAPI(univer)`가 반환하는 `univerAPI` 객체는 Univer의 Facade API입니다. 이 객체를 사용해 Board를 만들고 Board 요소를 조작할 수 있습니다.

## 모바일 지원

> [!WARNING]
> 아래 모바일 플러그인을 내보내는 SDK 패키지가 필요합니다. 모든 `@univerjs/*` 및 `@univerjs-pro/*` 의존성을 **같은 버전**으로 맞추세요.
> 
> `1.0.0-rc.0`은 `UniverBoardsMobileUIPlugin`을 내보내지 않습니다. 아래 예제는 해당 모바일 진입점을 포함하는 빌드에서 사용하세요.

Univer Boards에서 터치 조작을 제공하려면 **모바일 UI 플러그인**을 사용합니다.[^mobile-ui-mode] 에디터를 만들기 전에 UI 모드를 선택하세요.

위 플러그인 모드 예제에서 다음 UI 가져오기와 등록을 `createUnit()` 전에 **교체**하세요. 이미 초기화한 데스크톱 에디터에 추가하지 마세요. 모델 플러그인, 엔진, 언어 파일, CSS 및 Facade 가져오기는 유지합니다. 두 클래스는 **동일한 패키지 진입점**의 서로 다른 이름으로 내보내집니다.

```typescript
import { UniverBoardsMobileUIPlugin } from '@univerjs-pro/boards-ui'
import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'
import { UniverDrawingMobileUIPlugin } from '@univerjs/drawing-ui'
import { UniverMobileUIPlugin } from '@univerjs/ui'

univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })
univer.registerPlugin(UniverDocsMobileUIPlugin)
univer.registerPlugin(UniverDrawingMobileUIPlugin)
univer.registerPlugin(UniverBoardsMobileUIPlugin)
```

### 플러그인 대응표

사용할 기능만 등록하고 모델 플러그인과 필수 의존성을 유지하세요. 모바일 UI가 있다고 해서 양쪽 화면의 조작 기능이 모두 같은 것은 아닙니다. Pro 기능에는 해당 라이선스가 필요합니다. 백엔드가 필요한 기능은 앱에 [Univer Server SDK](https://docs.univer.ai/ko-KR/server.md)로 해당 기능을 통합하세요.

| 패키지                                      | 데스크톱 등록                             | 모바일 등록                                    |
| ---------------------------------------- | ----------------------------------- | ----------------------------------------- |
| `@univerjs/ui`                           | `UniverUIPlugin`                    | `UniverMobileUIPlugin`                    |
| `@univerjs/docs-ui`                      | `UniverDocsUIPlugin`                | `UniverDocsMobileUIPlugin`                |
| `@univerjs/drawing-ui`                   | `UniverDrawingUIPlugin`             | `UniverDrawingMobileUIPlugin`             |
| `@univerjs-pro/boards-ui`                | `UniverBoardsUIPlugin`              | `UniverBoardsMobileUIPlugin`              |
| `@univerjs/thread-comment-ui`            | `UniverThreadCommentUIPlugin`       | `UniverThreadCommentMobileUIPlugin`       |
| `@univerjs-pro/shape-editor-ui`          | `UniverShapeEditorUIPlugin`         | `UniverShapeEditorMobileUIPlugin`         |
| `@univerjs-pro/chart-ui`                 | `UniverChartUIPlugin`               | `UniverChartMobileUIPlugin`               |
| `@univerjs-pro/exchange-client`          | `UniverExchangeClientPlugin`        | `UniverExchangeClientMobileUIPlugin`      |
| `@univerjs-pro/boards-chart-ui`          | `UniverBoardsChartUIPlugin`         | `UniverBoardsChartMobileUIPlugin`         |
| `@univerjs-pro/boards-mind-ui`           | `UniverBoardsMindUIPlugin`          | `UniverBoardsMindMobileUIPlugin`          |
| `@univerjs-pro/boards-resources-ui`      | `UniverBoardsResourcesUIPlugin`     | `UniverBoardsResourcesMobileUIPlugin`     |
| `@univerjs-pro/boards-table-ui`          | `UniverBoardsTableUIPlugin`         | `UniverBoardsTableMobileUIPlugin`         |
| `@univerjs-pro/boards-thread-comment-ui` | `UniverBoardsThreadCommentUIPlugin` | `UniverBoardsThreadCommentMobileUIPlugin` |

### 컨테이너와 터치 조작

컨테이너 높이를 명시하고 페이지 viewport를 설정하세요. `100dvh`는 동적 뷰포트 높이를 따릅니다. 대상 모바일 브라우저에서 스크롤, 핀치 확대/축소, 텍스트 선택, 클립보드 및 화면 키보드 표시 후 배치를 확인하세요. 데스크톱 에디터의 폭만 줄여서는 모바일 플러그인으로 전환되지 않습니다.

`UniverMobileUIPlugin`은 기본적으로 `disableAutoFocus: true`를 사용하여 초기화 시 에디터가 자동으로 포커스를 가져오지 않도록 합니다.

```html
<meta name="viewport" content="width=device-width, initial-scale=1" />
<div id="app" style="height: 100dvh"></div>
```

## 선택적 기능 패키지

Board 편집기에 해당 요소 유형이 필요할 때 기능 패키지를 추가하세요.

```shell
pnpm add @univerjs-pro/boards-table @univerjs-pro/boards-table-ui
pnpm add @univerjs-pro/boards-mind @univerjs-pro/boards-mind-ui
```

기능 등록 예시는 [표](https://docs.univer.ai/ko-KR/guides/boards/features/tables.md), [마인드맵](https://docs.univer.ai/ko-KR/guides/boards/features/mind-maps.md), [가져오기 및 내보내기](https://docs.univer.ai/ko-KR/guides/boards/features/import-export.md)를 참고하세요.

## 기타 릴리스

Univer는 안정 릴리스 외에도 alpha / beta 및 nightly 채널을 제공합니다. 이러한 버전에서는 아직 정식 출시되지 않은 최신 기능을 미리 사용할 수 있습니다. 하지만 기능이 많아지는 만큼 위험도 커진다는 점에 유의하세요. 버그, 미완성 기능 또는 불안정한 기능이 포함될 수 있으므로 가능한 한 프로덕션 환경에서는 사용하지 마세요.

### Alpha / Beta 릴리스

Univer 개발팀이 새 기능이나 중요한 변경을 완료하면 alpha 또는 beta 채널에 사전 출시할 수 있습니다. 다음 명령으로 Univer 패키지의 alpha / beta 버전을 설치할 수 있습니다.

#### npm

```bash
npm install @univerjs-pro/boards@alpha # Alpha version
npm install @univerjs-pro/boards@beta # Beta version
```

#### pnpm

```bash
pnpm add @univerjs-pro/boards@alpha # Alpha version
pnpm add @univerjs-pro/boards@beta # Beta version
```

#### yarn

```bash
yarn add @univerjs-pro/boards@alpha # Alpha version
yarn add @univerjs-pro/boards@beta # Beta version
```

#### bun

```bash
bun add @univerjs-pro/boards@alpha # Alpha version
bun add @univerjs-pro/boards@beta # Beta version
```

alpha / beta 버전을 사용하면서 문제가 발생하거나 의견이 있다면 [GitHub Issues](https://github.com/dream-num/univer/issues)를 통해 Univer 개발팀에 알려 주세요.

이러한 초기 릴리스에 대한 의견을 환영합니다.

## 다음 단계

* [빠른 시작](https://docs.univer.ai/ko-KR/guides/boards/getting-started/quickstart.md)
* [Facade API](https://docs.univer.ai/ko-KR/guides/boards/getting-started/facade.md)
* [라이선스 설정](https://docs.univer.ai/ko-KR/server/license.md)
* [Server SDK 통합](https://docs.univer.ai/ko-KR/server.md)

[^peer-dependency]: `peerDependencies`는 호스트 프로젝트가 호환되는 버전으로 제공해야 하는 의존성입니다. 이를 통해 Univer와 애플리케이션이 React 같은 라이브러리를 공유합니다.

[^facade-entry]: Facade는 등록된 플러그인의 기능을 애플리케이션에서 사용하는 API입니다. Facade 진입점을 가져오면 API 메서드가 추가되지만 기능 플러그인 자체가 등록되지는 않습니다.

[^mobile-ui-mode]: 모바일 UI 플러그인은 초기화할 때 터치 컨트롤과 모바일 서비스를 선택합니다. 기기를 자동 감지하거나 창 크기 변경 시 기존 인스턴스의 모드를 바꾸지 않습니다. 모드를 변경하려면 문서 상태를 보존하고 기존 인스턴스를 폐기한 뒤 선택한 플러그인 조합으로 초기화하세요.