# 설치 및 기본 사용법

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

Univer PDFs는 Univer Office SDK 제품이며 현재 프리셋을 제공하지 않습니다. 플러그인 모드로 PDF 애플리케이션을 만드세요.

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

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

### 패키지 관리자 사용

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/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### npm

```shell
npm install @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui react react-dom rxjs
```

#### bun

```shell
bun add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

모든 `@univerjs/*` 및 `@univerjs-pro/*` 패키지를 동일한 버전으로 유지하세요.

#### 사용법

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

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

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

1.
   공통 UI 스타일을 PDF UI 스타일보다 먼저 가져오고, 애플리케이션에서 활성화한 로캘 팩을 병합하세요.
   
   ```ts
   import { UniverLicensePlugin } from '@univerjs-pro/license'
   import { UniverPdfsPlugin } from '@univerjs-pro/pdfs'
   import { UniverPdfsUIPlugin } from '@univerjs-pro/pdfs-ui'
   import PdfsUIEnUS from '@univerjs-pro/pdfs-ui/locale/en-US'
   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
   import { FUniver } from '@univerjs/core/facade'
   import DesignEnUS from '@univerjs/design/locale/en-US'
   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-pro/pdfs-ui/lib/index.css'
   ```

1.
   PDF 퍼사드 진입점을 가져오세요. 이 부수 효과 가져오기는 `FUniver`에 PDF 메서드와 열거형을 추가합니다.
   
   ```ts
   import '@univerjs-pro/pdfs/facade'
   ```

1.
   런타임을 만들고 명시적인 플러그인 스택을 등록한 다음 PDF를 만드세요.
   
   ```ts
   const univer = new Univer({
     locale: LocaleType.EN_US,
     locales: {
       [LocaleType.EN_US]: mergeLocales(
         DesignEnUS,
         UIEnUS,
         PdfsUIEnUS,
       ),
     },
   })
   
   univer.registerPlugin(UniverUIPlugin, { container: 'app' })
   univer.registerPlugin(UniverLicensePlugin, {
     license: process.env.CLIENT_LICENSE_TEXT,
   })
   univer.registerPlugin(UniverPdfsPlugin)
   univer.registerPlugin(UniverPdfsUIPlugin)
   
   const univerAPI = FUniver.newAPI(univer)
   univerAPI.createPdf({ name: 'Untitled PDF' })
   ```

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

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

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

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

```typescript
univer.registerPlugins([
  [UniverUIPlugin, { container: 'app' }],
  [UniverLicensePlugin, {
    license: process.env.CLIENT_LICENSE_TEXT,
  }],
  UniverPdfsPlugin,
  UniverPdfsUIPlugin,
])
```

## 모바일 지원

현재 `@univerjs-pro/pdfs-ui`는 별도의 모바일 UI 플러그인을 내보내지 않습니다. 존재하지 않는 `MobileUIPlugin` 가져오기나 `mobile: true` 옵션을 사용하지 마세요. 좁은 컨테이너가 완전한 터치 지원을 의미하지는 않습니다. 대상 기기에서 기존 UI를 검증하세요.

## 선택적 썸네일 워커

페이지 썸네일은 추가 설정 없이 메인 스레드에서 렌더링할 수 있습니다. 문서가 큰 경우 `thumbnailWorkerURL`을 통해 전용 모듈 워커를 제공하세요.

`pdf-thumbnail.worker.ts`와 같은 워커 진입점을 만드세요.

```ts
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'

startPdfPageThumbnailWorker()
```

그런 다음 PDF UI 플러그인을 등록할 때 해당 URL을 전달하세요.

```ts
univer.registerPlugin(UniverPdfsUIPlugin, {
  thumbnailWorkerURL: new Worker(new URL('./pdf-thumbnail.worker.ts', import.meta.url), { type: 'module' }),
})
```

이 옵션은 문자열 URL 또는 기존 `Worker`도 허용합니다. 워커나 `OffscreenCanvas`를 사용할 수 없으면 썸네일 렌더링은 메인 스레드로 대체됩니다.

## 협업 기반 편집

`@univerjs-pro/pdfs-editor`는 로컬 전용 플러그인 스택에 포함되지 않습니다. 단독으로 등록하지 마세요. 먼저 [공동 편집](https://docs.univer.ai/ko-KR/guides/pdfs/features/collaboration.md) 문서에 따라 `@univerjs-pro/collaboration`, `@univerjs-pro/collaboration-client`, `@univerjs-pro/collaboration-client-ui`의 전체 스택을 설치하고 등록한 다음 PDF 편집기 수명 주기 플러그인을 설치하고 등록하세요.

## Node.js 사용법

Node.js 서비스는 브라우저 UI 패키지 없이 `UniverPdfsPlugin`만 등록할 수 있습니다. 저장된 PDF 유닛을 불러오거나 동기화해야 하는 경우에만 위의 전체 협업 스택을 추가하세요.

## 기타 릴리스

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

### Alpha / Beta 릴리스

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

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

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

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

## 다음 단계

* [빠른 시작](https://docs.univer.ai/ko-KR/guides/pdfs/getting-started/quickstart.md)
* [Facade API](https://docs.univer.ai/ko-KR/guides/pdfs/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 같은 라이브러리를 공유합니다.