Web SDK

설치 및 기본 사용법

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

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

플러그인 모드로 설정하기

패키지 관리자 사용

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

설치

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

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

Shell
pnpm 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 스타일보다 먼저 가져오고, 애플리케이션에서 활성화한 로캘 팩을 병합하세요.

    TypeScript
    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'

  2. PDF 퍼사드 진입점을 가져오세요. 이 부수 효과 가져오기는 FUniver에 PDF 메서드와 열거형을 추가합니다.

    TypeScript
    import '@univerjs-pro/pdfs/facade'

  3. 런타임을 만들고 명시적인 플러그인 스택을 등록한 다음 PDF를 만드세요.

    TypeScript
    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와 같은 워커 진입점을 만드세요.

TypeScript
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'startPdfPageThumbnailWorker()

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

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

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

협업 기반 편집

@univerjs-pro/pdfs-editor는 로컬 전용 플러그인 스택에 포함되지 않습니다. 단독으로 등록하지 마세요. 먼저 공동 편집 문서에 따라 @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 버전을 설치할 수 있습니다.

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

alpha / beta 버전을 사용하면서 문제가 발생하거나 의견이 있다면 GitHub Issues를 통해 Univer 개발팀에 알려 주세요.

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

다음 단계

Footnotes

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

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.