# 핵심 기능

- Human documentation: [https://docs.univer.ai/ko-KR/guides/pdfs/features/core](https://docs.univer.ai/ko-KR/guides/pdfs/features/core)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/pdfs/features/core.md](https://docs.univer.ai/ko-KR/guides/pdfs/features/core.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

#### Package metadata

```json
{
  "preset": [],
  "plugins": [
    {
      "client": "@univerjs-pro/pdfs",
      "facade": "@univerjs-pro/pdfs/facade"
    },
    {
      "client": "@univerjs-pro/pdfs-ui",
      "locale": "@univerjs-pro/pdfs-ui/locale/ko-KR",
      "style": "@univerjs-pro/pdfs-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

Univer PDFs 핵심 기능은 정식 PDF Unit, 영구 편집 레이어 및 브라우저 워크벤치를 제공합니다. 가져온 PDF 콘텐츠는 원본 기준으로 유지되고, 승인된 변경 사항은 Unit 스냅샷에 저장되어 현재 문서로 렌더링됩니다.

## 기능

* **PDF Unit 모델**: 원본 문서, 페이지 구조, 리소스 및 영구 편집 의도를 `IPdfUnitData`에 저장합니다.
* **페이지 및 요소 작업**: 페이지 탐색과 삽입은 물론 편집 가능한 텍스트, 목록, 표, 이미지, 구분선 및 주석을 지원합니다.
* **브라우저 워크벤치**: PDF 페이지 렌더링, 미리 보기, 선택, 편집 컨트롤, 클립보드 동작 및 검사기 UI를 제공합니다.
* **명령 파이프라인**: 승인된 변경 사항을 영구 명령과 변형 배치로 적용하여 저장, 실행 취소 및 다시 실행이 하나의 모델을 공유합니다.
* **Facade API**: PDF, 페이지, 요소 및 네이티브 텍스트 객체를 통해 PDF Unit을 생성, 조회, 편집 및 저장합니다.

## 플러그인 모드

### 설치

#### npm

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

#### pnpm

```bash
pnpm add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### yarn

```bash
yarn add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### bun

```bash
bun add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-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-pro/pdfs/facade'

import '@univerjs/design/lib/index.css'
import '@univerjs/ui/lib/index.css'
import '@univerjs-pro/pdfs-ui/lib/index.css'

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)
const pdf = univerAPI.createPdf({ name: 'Untitled PDF' })
```

`UniverPdfsPlugin`은 PDF Unit과 영구 명령을 담당하고, `UniverPdfsUIPlugin`은 브라우저 뷰어와 편집 컨트롤을 담당합니다. 보기 전용 UI에는 `{ editor: { enabled: false } }`를 지정하세요. 협업 기반 애플리케이션은 필요한 협업 플러그인과 함께 `@univerjs-pro/pdfs-editor`를 추가할 수 있습니다.

## 프리셋 모드

Univer PDFs는 현재 프리셋 패키지를 제공하지 않습니다. PDF 애플리케이션은 플러그인 모드로 만드세요.

## 메뉴 순서와 그리드 레이아웃

기존 `UniverUIPlugin` 등록에서 `menu`와 `ribbonType`을 설정합니다. 공통 UI 옵션이므로 `UniverPdfsUIPlugin`에 전달하지 않습니다. 다음 예제는 PDFs의 실제 메뉴 항목 ID를 사용합니다.

### 초기 설정

```ts
import type { MenuConfig } from '@univerjs/ui'
import { UniverUIPlugin } from '@univerjs/ui'

const menu: MenuConfig = {
  'ribbon.view': { order: -1 },
  'ribbon.start.layout': { order: -1 },
  'pdf.menu.tool.highlight': {
    order: 1,
    gridLayout: { row: 2, column: 1 },
  },
  'pdf.menu.tool.ink': {
    order: 0,
    gridLayout: { row: 1, column: 1 },
  },
}

univer.registerPlugin(UniverUIPlugin, { container: 'app', ribbonType: 'grid', menu })
```

`order`는 같은 계층의 탭, 그룹 또는 메뉴 항목을 오름차순으로 정렬하며 항목을 다른 그룹으로 옮기지는 않습니다. 메뉴 항목 ID는 `data-u-command` 속성에서 확인할 수 있습니다. 명령 ID와 같다고 가정하지 마세요.

### 실행 중 업데이트

`@univerjs/ui/facade`를 가져온 후 `FUniver.newAPI(univer)`로 `univerAPI`를 생성합니다. [`updateMenuConfig()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#updatemenuconfig)는 변경 사항을 병합하고 지정하지 않은 필드를 유지하며 메뉴를 갱신합니다. 이후 등록되는 메뉴에도 설정이 적용됩니다.

```ts
import '@univerjs/ui/facade'

univerAPI.updateMenuConfig({
  'pdf.menu.tool.highlight': { gridLayout: { row: 2, column: 1, showLabel: true, width: 96 } },
})
```

`gridLayout`은 그리드 Ribbon에만 적용됩니다. 각 그룹은 두 행이며 `row`와 `column`은 1부터 시작합니다. 명시적 좌표가 위치를 결정하므로 사용 중인 셀을 교환할 때는 `order`만 바꾸지 말고 두 항목을 함께 업데이트하세요. 지정하지 않은 선택 필드는 기존 설정이나 Schema를 유지합니다. 행·열 확장, 레이블, 너비와 아이콘 크기는 [`IRibbonGridLayout`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/ui.md#iribbongridlayout)을 참고하세요.

`UniverPdfsUIPlugin`의 편집 기능을 활성화하세요. `editor.enabled: false`이면 해당 제품의 Ribbon을 등록하지 않습니다. 메뉴 재정의 설정은 등록되지 않은 버튼을 생성하지 않습니다.

사용자 정의 버튼과 하위 메뉴 진입점도 [`createMenu()`, `createSubmenu()`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/ui.md#ifacademenuitem)에 `order`와 `gridLayout`을 전달하고 `appendTo()`로 등록할 수 있습니다. 팝업 내부에는 Ribbon 그리드 레이아웃이 적용되지 않습니다.