Web SDK

설치 및 기본 사용법

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

Univer의 핵심 개념에 익숙하지 않다면 먼저 빠른 시작을 읽어보세요.

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

플러그인 모드로 설정하기

브라우저용 Bases 애플리케이션은 일반적으로 공유 Univer 런타임, 렌더링 엔진, UI 셸, 수식 엔진, 라이선스를 등록한 다음 Bases 모델 및 UI 플러그인을 등록합니다.

패키지 관리자 사용

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/engine-render @univerjs/ui @univerjs-pro/bases @univerjs-pro/bases-ui @univerjs-pro/engine-formula @univerjs-pro/license

사용법

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

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

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

주의

  • Bases 플러그인보다 먼저 UniverLicensePlugin을 등록하세요.
  • 제품 UI CSS보다 먼저 공유 UI CSS를 가져오세요.
  • 대시보드 도형을 포함한 Bases에는 @univerjs-pro/engine-formula의 UniverProFormulaEnginePlugin을 사용합니다. 같은 Univer 인스턴스에서 여러 제품을 함께 사용하는 경우 기존 UniverFormulaEnginePlugin의 가져오기와 등록을 바꾸고 두 수식 엔진을 동시에 등록하지 마세요.

  1. 스타일, 로캘 팩, 필수 플러그인을 가져옵니다.

    TypeScript
    import { UniverBasesPlugin } from '@univerjs-pro/bases'import { UniverBasesUIPlugin } from '@univerjs-pro/bases-ui'import BasesUIEnUS from '@univerjs-pro/bases-ui/locale/en-US'import BasesEnUS from '@univerjs-pro/bases/locale/en-US'import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'import { UniverLicensePlugin } from '@univerjs-pro/license'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import DesignEnUS from '@univerjs/design/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-pro/bases-ui/lib/index.css'

  2. Facade API2를 사용하려면 Facade 진입점을 가져옵니다.

    TypeScript
    import { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/bases/facade'import '@univerjs-pro/bases-ui/facade'

  3. Univer 인스턴스를 만들고 플러그인을 등록한 다음 Base 단위를 만듭니다.

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      BasesEnUS,      BasesUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverProFormulaEnginePlugin)univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverBasesPlugin)univer.registerPlugin(UniverBasesUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_BASE, {})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' }],  UniverProFormulaEnginePlugin,  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverBasesPlugin,  UniverBasesUIPlugin,])

모바일 지원

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

기타 릴리스

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

Alpha / Beta 릴리스

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

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

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

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

다음 단계

Footnotes

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

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

이 가이드는 어떠셨나요?

© 2026 DreamNum Co., Ltd.