설치 및 기본 사용법

Univer는 플러그인 기반 설계 철학을 채택하여 개발자에게 유연하고 확장 가능한 전자 문서 애플리케이션 프레임워크를 제공합니다. 이러한 플러그인 기반 설계 덕분에 Univer는 다양한 기능 모듈을 손쉽게 통합하여 여러 사용자의 요구를 충족할 수 있습니다. 다만 플러그인 기반 설계는 애플리케이션의 복잡성을 높이며, 특히 Univer를 처음 접하는 개발자에게는 어렵게 느껴질 수 있습니다.

이를 위해 Univer는 빠르게 통합하고 사용할 수 있도록 플러그인 모드와 프리셋 모드라는 두 가지 방식을 제공합니다. 프리셋은 미리 구성된 플러그인의 조합이므로, 복잡한 확장이 필요하지 않다면 두 모드가 제공하는 기능은 같습니다.

프리셋 모드와 플러그인 모드의 차이점은 다음과 같습니다.

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

플러그인 모드로 설정하기

Univer는 다양한 기능을 플러그인 형태로 제공합니다. 제품에 꼭 필요한 일부 핵심 플러그인 외에는 필요에 따라 다른 플러그인을 선택해서 도입할 수 있습니다. 여기서는 가장 기본적인 Univer Docs 애플리케이션을 예로 들어 플러그인을 직접 조합하고 설치하는 방법을 설명합니다.

프리셋 모드와 달리 플러그인 모드에는 Facade API¹가 기본으로 포함되지 않습니다. 아래 예제에서는 Facade API를 사용하므로 API 인스턴스를 만들기 전에 해당 facade 패키지를 가져와야 합니다.

패키지 관리자 사용

설치

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

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

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

사용법

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

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

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

1. 프로젝트에서 Univer 스타일 파일, 언어 팩 및 몇 가지 필수 플러그인을 가져옵니다.

   TypeScript

   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'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 { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'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'

2. 예제에서 사용하는 facade 패키지를 가져옵니다.

   TypeScript

   import '@univerjs/engine-formula/facade'import '@univerjs/ui/facade'import '@univerjs/docs/facade'import '@univerjs/docs-ui/facade'

3. 그런 다음 Univer 인스턴스를 만들고 플러그인을 등록합니다.

   TypeScript

   const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})

   코드 펼치기

univer.registerPlugin 및 univer.registerPlugins 메서드

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

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

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

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,])

플러그인 지연 로딩

플러그인 모드의 대표적인 장점은 플러그인을 불러오는 시점을 더 유연하게 제어할 수 있다는 것입니다. 일반적으로 애플리케이션을 초기화할 때는 필수 플러그인만 불러오고, 일부 플러그인은 첫 렌더링이 끝난 뒤에 불러오도록 미룹니다.

// ...const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

CDN에서 가져오기

패키지 관리자를 사용하지 않거나 Univer의 기능을 빠르게 시험해 보고 싶다면 CDN을 통해 Univer 관련 리소스를 가져올 수 있습니다. 자세한 내용은 CDN으로 Univer 사용하기를 참고하세요.

모바일 지원

Univer Docs에서 터치 조작을 제공하려면 모바일 UI 플러그인을 사용합니다.³ 에디터를 만들기 전에 UI 모드를 선택하세요.

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

import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)

현재 UniverSheetsCorePreset과 UniverDocsCorePreset은 데스크톱 UI를 등록하며 mobile: true 옵션이 없습니다. 모바일에서는 플러그인을 직접 구성하세요. 데스크톱 프리셋 뒤에 모바일 플러그인을 추가해도 기존 UI가 교체되지 않습니다.

플러그인 대응표

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

컨테이너와 터치 조작

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

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

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

프리셋 모드로 설정하기

여기서는 20줄 미만의 코드로 Univer Docs 애플리케이션을 빠르게 만드는 방법을 간단히 소개합니다.

패키지 관리자 사용

프로젝트에서 이미 최신 프런트엔드 개발 도구를 사용하고 있다면 Univer를 매우 간단하게 통합할 수 있습니다. Univer 애플리케이션을 빌드할 때는 ES Modules를 잘 지원하는 Vite, esbuild, Webpack 5 같은 빌드 도구를 권장합니다. Webpack 4와 같은 다른 빌드 도구를 사용한다면 추가 설정이 필요할 수 있습니다.

설치

사용 중인 패키지 관리자로 @univerjs/presets를 설치합니다.

pnpm add @univerjs/presets @univerjs/preset-docs-core

npm install @univerjs/presets @univerjs/preset-docs-core

yarn add @univerjs/presets @univerjs/preset-docs-core

bun add @univerjs/presets @univerjs/preset-docs-core

사용법

다음 코드로 Univer Docs 애플리케이션을 시작할 수 있습니다.

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

import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-docs-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetDocsCoreEnUS,    ),  },  presets: [    UniverDocsCorePreset({      container: 'app',    }),  ],})univerAPI.createDocument({})

여기서 반환되는 univerAPI 객체를 Univer Facade API라고 하며, 이 객체를 통해 Univer가 제공하는 다양한 기능을 호출할 수 있습니다.

createUniver 메서드

createUniver 메서드는 언어, 테마, 플러그인 등 Univer의 설정 정보가 담긴 설정 객체를 받습니다. 이 메서드는 Univer 인스턴스와 Univer Facade API 인스턴스가 포함된 객체를 반환합니다.

설정 객체의 주요 속성은 다음과 같습니다.

• locale: 언어 환경이며 LocaleType 열거형 값을 사용할 수 있습니다.
• locales: 로케일 객체입니다. 키는 언어 환경이고 값은 언어 팩 객체입니다.
• theme: 선택 사항인 테마 객체입니다.
• presets: 등록할 프리셋이 담긴 배열입니다. 예를 들면 UniverDocsCorePreset이 있습니다.
• plugins: 추가로 등록해야 하는 플러그인이 담긴 배열입니다.

프리셋 패키지에 포함되지 않은 플러그인을 사용하거나 직접 플러그인을 구현한 경우 plugins 속성으로 등록할 수 있습니다. Univer 인스턴스를 얻은 뒤 univer.registerPlugin 메서드로 플러그인을 등록해도 됩니다.

CDN에서 가져오기

패키지 관리자를 사용하지 않거나 Univer의 기능을 빠르게 시험해 보고 싶다면 CDN을 통해 Univer 관련 리소스를 가져올 수 있습니다. 자세한 내용은 CDN으로 Univer 사용하기를 참고하세요.

기타 릴리스

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

Alpha / Beta 릴리스

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

pnpm add @univerjs/<package-name>@alpha # Alpha version
pnpm add @univerjs/<package-name>@beta # Beta version

npm install @univerjs/<package-name>@alpha # Alpha version
npm install @univerjs/<package-name>@beta # Beta version

yarn add @univerjs/<package-name>@alpha # Alpha version
yarn add @univerjs/<package-name>@beta # Beta version

bun add @univerjs/<package-name>@alpha # Alpha version
bun add @univerjs/<package-name>@beta # Beta version

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

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

다음 단계

• 기본 개념 - Univer의 기본 개념을 알아봅니다.
• 기능 - Univer의 기능과 데이터를 조작하는 방법을 알아봅니다.