ko-KR.md
May 7, 2026 · View on GitHub
스프레드시트, 문서, 프레젠테이션을 만들기 위한 풀스택 동형 오피스 SDK.
Univer는 플러그인 아키텍처, Canvas 기반 렌더링, 수식 엔진, 브라우저와 Node.js에서 함께 사용할 수 있는 Facade API로 임베드 가능한 생산성 경험을 만들 수 있게 해줍니다.
English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español
📖 문서 | ✨ 쇼케이스 | 📘 API Reference | 📝 블로그
✨ Univer란?
Univer는 제품 안에 오피스 애플리케이션을 만들기 위한 오픈소스 SDK입니다. 호스팅 앱이나 고정된 UI를 강제하지 않으면서 스프레드시트, 문서, 프레젠테이션 경험에 필요한 빌딩 블록을 제공합니다.
Univer는 다음과 같은 경우에 적합합니다.
- SaaS 제품, 내부 도구, BI 워크플로, AI 애플리케이션에 스프레드시트나 문서 편집 기능을 임베드할 때.
- 브라우저와 같은 아키텍처로 서버에서 워크북/문서 처리를 실행할 때.
- 필요한 기능만 플러그인으로 조합하거나 presets로 빠르게 시작할 때.
- 커스텀 플러그인, 명령, 서비스, UI 컴포넌트, Facade API로 동작을 확장할 때.
Univer는 단순한 스프레드시트 파일 뷰어가 아닙니다. 자체 생산성 화면을 구축하기 위한 프레임워크입니다.
🌟 Highlights
|
⚡ 대규모 화면에 맞춘 설계 Canvas 기반 렌더링과 전용 수식 엔진이 복잡한 워크북도 반응성 있게 유지합니다. |
🧩 플러그인 중심 확장 필요한 기능을 조합, 교체, 지연 로딩하거나 확장할 수 있습니다. |
🤖 Headless AI 인프라 Node.js에서 워크북과 문서 로직을 실행해 에이전트, 자동화, 서버 사이드 워크플로를 지원합니다. |
|
🛠️ 제품 통합을 위한 SDK 프레임워크 어댑터, Facade API, presets, headless runtime이 실제 통합 경로에 맞춰집니다. |
🌗 Dark mode 지원 UI 컴포넌트와 렌더링 엔진이 모두 라이트/다크 테마를 지원합니다. |
🔌 통합 Facade API 브라우저와 Node.js에서 워크북, 범위, 수식, 문서를 일관된 API로 다룰 수 있습니다. |
🚀 왜 Univer인가?
- 동형 설계: 브라우저 UI 앱과 Node.js headless 처리를 모두 실행할 수 있습니다.
- 플러그인 우선 아키텍처: 모든 기능은 조합 가능한 플러그인으로 제공되어 추가, 제거, 교체, 지연 로딩이 가능합니다.
- 빠른 통합을 위한 Preset Mode: 빠르게 동작하는 앱이 필요할 때
univer-presets의 curated plugin bundle을 사용할 수 있습니다. - 완전한 제어를 위한 Plugin Mode: 커스텀 로딩, 더 작은 번들, 깊은 통합이 필요할 때 패키지를 직접 조합할 수 있습니다.
- Facade API: 워크북, 워크시트, 범위, 문서, 수식, 명령, 이벤트를 고수준 API로 다룰 수 있습니다.
- Canvas 렌더링 엔진: 큰 편집 가능한 문서 표면을 지원하고 여러 문서 타입이 렌더링 레이어를 공유합니다.
- 확장 가능한 UI: React, Vue, Web Components 및 프레임워크별 애플리케이션 셸에 통합할 수 있습니다.
⚡ 빠른 시작
대부분의 애플리케이션은 Preset Mode로 시작하는 것을 권장합니다. 패키지를 직접 조합하고 플러그인 등록을 제어해야 한다면 Plugin Mode를 사용하세요.
Preset Mode (권장)
Presets는 필요한 Facade API 등록과 스타일을 포함하는 Univer 플러그인의 curated collection입니다.
pnpm add @univerjs/presets @univerjs/preset-sheets-core
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'
const { univerAPI } = createUniver({
locale: LocaleType.EN_US,
locales: {
[LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),
},
presets: [
UniverSheetsCorePreset({
container: 'app',
}),
],
})
univerAPI.createWorkbook({})
Plugin Mode
Plugin Mode는 패키지, 스타일 import, locale 병합, Facade API 등록, 플러그인 순서를 더 낮은 수준에서 제어할 수 있게 해줍니다.
pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui
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 { UniverSheetsPlugin } from '@univerjs/sheets'
import SheetsEnUS from '@univerjs/sheets/locale/en-US'
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'
import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US'
import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'
import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US'
import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'
import SheetsUIEnUS from '@univerjs/sheets-ui/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/docs-ui/lib/index.css'
import '@univerjs/sheets-ui/lib/index.css'
import '@univerjs/sheets-formula-ui/lib/index.css'
import '@univerjs/sheets-numfmt-ui/lib/index.css'
import '@univerjs/engine-formula/facade'
import '@univerjs/ui/facade'
import '@univerjs/docs-ui/facade'
import '@univerjs/sheets/facade'
import '@univerjs/sheets-ui/facade'
import '@univerjs/sheets-formula/facade'
import '@univerjs/sheets-numfmt/facade'
const univer = new Univer({
locale: LocaleType.EN_US,
locales: {
[LocaleType.EN_US]: mergeLocales(
DesignEnUS,
UIEnUS,
DocsUIEnUS,
SheetsEnUS,
SheetsUIEnUS,
SheetsFormulaUIEnUS,
SheetsNumfmtUIEnUS,
),
},
})
univer.registerPlugin(UniverRenderEnginePlugin)
univer.registerPlugin(UniverFormulaEnginePlugin)
univer.registerPlugin(UniverUIPlugin, { container: 'app' })
univer.registerPlugin(UniverDocsPlugin)
univer.registerPlugin(UniverDocsUIPlugin)
univer.registerPlugin(UniverSheetsPlugin)
univer.registerPlugin(UniverSheetsUIPlugin)
univer.registerPlugin(UniverSheetsFormulaPlugin)
univer.registerPlugin(UniverSheetsFormulaUIPlugin)
univer.registerPlugin(UniverSheetsNumfmtPlugin)
univer.registerPlugin(UniverSheetsNumfmtUIPlugin)
const univerAPI = FUniver.newAPI(univer)
univerAPI.createWorkbook({})
페이지에는 컨테이너가 필요합니다.
<div id="app" style="height: 100vh"></div>
자세한 내용은 Installation & Basic Usage guide, createUniver reference, Facade API reference를 참고하세요.
🧩 Preset Mode vs Plugin Mode
| 선택 | 사용 시점 | 시작하기 |
|---|---|---|
| Preset Mode | 최소 설정으로 동작하는 Sheets, Docs, Node 구성이 필요할 때. | univer-presets 및 getting started guide |
| Plugin Mode | 패키지, 플러그인 등록 순서, 지연 로딩, 런타임 구성을 엄격하게 제어해야 할 때. | 이 저장소의 examples/ 및 architecture guide |
| Headless Mode | UI 없이 서버 측 워크북/문서 처리, 수식 계산, 자동화가 필요할 때. | Headless Univer |
모든 @univerjs/* 패키지는 같은 버전으로 유지하세요. Univer Pro 패키지를 사용하는 경우 @univerjs-pro/* 버전도 맞춰야 합니다.
🧭 호환성
- 브라우저 런타임: Univer는 Chrome 70을 대상으로 컴파일되며 Edge
>=70, Firefox>=63, Chrome>=70, Safari>=12.0, Electron>=5에서 잘 동작하도록 노력합니다. - Polyfills: Univer는
Intl.Segmenter에 의존합니다. 대상 브라우저나 런타임이 이를 제공하지 않는다면@formatjs/intl-segmenter같은 polyfill을 추가하세요. - 빌드 도구: Vite, esbuild, Webpack 5를 권장합니다. 빌드 도구가
package.json의exports필드를 지원하지 않는 경우(Webpack 4에서 흔함) 추가 path mapping이 필요할 수 있습니다. - React: Univer의 view layer는 React 18 기반이며 React 18과 19를 지원합니다. React 16.9+ 및 17에는 최소한의 호환성 지원을 제공합니다.
- Node.js runtime: Headless Univer는 Node.js
>=18.17.0을 지원합니다. 이 monorepo를 개발하려면 Node.js>=22.18이 필요합니다.
🛠️ 만들 수 있는 것
| 영역 | 오픈소스 기능 |
|---|---|
| Sheets | 워크북, 워크시트, 범위, 선택, 수식, 숫자 서식, 필터링, 정렬, 데이터 유효성 검사, 조건부 서식, 하이퍼링크, 댓글, 찾기/바꾸기, 노트, 테이블, drawing integration, 확장 가능한 UI 플러그인. |
| Docs | 리치 문서 모델, 편집 UI, 목록, 하이퍼링크, drawing integration, 댓글, quick insert, 공유 문서 아키텍처. |
| Slides | 프레젠테이션 데이터 모델과 UI 패키지. 현재 활발히 개발 중입니다. |
| Runtime | 브라우저 앱, Node.js headless 사용, Web Worker/RPC 패턴, multi-instance 사용, 서버 지향 자동화. |
| Integrations | React, Vue, Web Components, 프레임워크 템플릿, 테마, 로컬라이제이션, 커스텀 플러그인. |
Sheets는 현재 가장 성숙한 제품 영역입니다. Docs와 Slides는 Univer의 아키텍처를 공유하며 같은 SDK 안에서 계속 발전하고 있습니다.
🔓 Open Source와 Pro
이 저장소에는 Univer의 오픈소스 코어와 first-party OSS 플러그인이 포함되어 있습니다. 일부 엔터프라이즈 기능은 Univer Pro 패키지로 개발되며 별도 통합이 필요합니다.
| Open source | Univer Pro / commercial |
|---|---|
| Core SDK, 플러그인 시스템, 렌더링 엔진, 수식 엔진, Facade API, Sheets/Docs/Slides 패키지, 테마, i18n, 다양한 first-party 플러그인. | 실시간 협업, import/export, printing, charts, pivot tables, sparklines, advanced formula capabilities, edit history, Pro server components, license management. |
Pro 기능은 Univer Pro guide에 문서화되어 있습니다. 여기서는 OSS 패키지의 범위를 명확히 하기 위해 의도적으로 분리했습니다.
🌐 생태계
- Core SDK:
dream-num/univer, 이 monorepo입니다. - Presets:
dream-num/univer-presets, 브라우저와 Node.js 앱을 위한 curated plugin bundle입니다. - AI agent skills:
dream-num/univer-sdk-skills, Univer 통합, Pro 기능, 플러그인 개발, Node 백엔드를 다루는 AI agent용 재사용 지침입니다. AI Skills guide를 참고하세요. - Documentation: docs.univer.ai, Sheets, Docs, Slides, recipes, Pro guides를 포함합니다.
- API Reference: docs.univer.ai/reference, Facade API와 생성된 API reference입니다.
- Examples and showcase: Univer Showcase와 이 저장소의
examples/. - AI-native spreadsheets:
dream-num/univer-mcp, 자연어로 Univer Sheets를 제어하기 위한 Univer Platform / MCP 통합입니다.
📦 저장소 안내
.
├── packages/ Core packages, engines, document types, UI plugins, feature plugins
├── examples/ 개발에 사용하는 로컬 브라우저 및 Node.js 데모
├── common/ 공유 내부 도구, mock data, storybook, utilities
├── e2e/ Playwright 및 visual comparison tests
├── tests/ 추가 integration test projects
└── docs/ architecture notes, images, repository-local documentation
패키지별 README는 packages/의 각 패키지 옆에 있습니다.
🧑💻 개발
요구 사항:
- Node.js
>=22.18 - pnpm
>=10
git clone https://github.com/dream-num/univer.git
cd univer
pnpm install
pnpm dev
유용한 명령:
| 명령 | 목적 |
|---|---|
pnpm dev | 로컬 examples 앱을 시작합니다. |
pnpm build | 내부 common 패키지를 제외하고 workspace 패키지를 빌드합니다. |
pnpm test | Turbo를 통해 unit tests를 실행합니다. |
pnpm typecheck | Turbo를 통해 TypeScript checks를 실행합니다. |
pnpm lint | ESLint를 실행합니다. |
pnpm test:e2e | Playwright tests를 실행합니다. |
pnpm storybook:dev | UI component 개발용 Storybook을 시작합니다. |
Pull request를 열기 전에 CONTRIBUTING.md를 읽어 주세요.
📝 Contributor Notes
더 깊은 변경을 하기 전에 읽어볼 만한 저장소 내부 문서입니다.
- Building Isomorphic Univer: 브라우저, Node.js, UI, 공유 플러그인 로직을 나누는 방법.
- Contributing to Facade API:
FUniver,FWorkbook,FRange등 Facade API의 설계 기준. - Naming Convention: 파일, 폴더, 인터페이스, 플러그인, 명령, DI token naming 규칙.
- Fixing Memory Leaks: Univer 인스턴스의 흔한 memory leak 패턴과 디버깅 흐름.
- Architecture TLDRs: formula engine, Web Worker, permission, selection, ref-range 동작에 대한 간단한 설계 메모.
💬 커뮤니티
- GitHub Discussions에서 질문할 수 있습니다.
- Discord에서 커뮤니티와 대화할 수 있습니다.
- Twitter / X와 YouTube를 팔로우하세요.
참여하기 전에 Code of Conduct를 읽어 주세요.
🔒 보안
보안 문제를 발견했다고 생각되면 Security Policy를 따라 주세요.
❤️ 스폰서
Univer는 커뮤니티와 스폰서의 지원을 받습니다. Open Collective를 통해 프로젝트를 지원할 수 있습니다.
📄 라이선스
Copyright (c) 2021-present DreamNum Co., Ltd.
Apache-2.0 라이선스로 배포됩니다.