ko-KR.md

스프레드시트, 문서, 프레젠테이션을 만들기 위한 풀스택 동형 오피스 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: 빠르게 동작하는 앱이 필요할 때 이 저장소의 presets/에 있는 curated plugin collection을 사용할 수 있습니다.
• 완전한 제어를 위한 Plugin Mode: 커스텀 로딩, 더 작은 번들, 깊은 통합이 필요할 때 패키지를 직접 조합할 수 있습니다.
• Facade API: 워크북, 워크시트, 범위, 문서, 수식, 명령, 이벤트를 고수준 API로 다룰 수 있습니다.
• Canvas 렌더링 엔진: 큰 편집 가능한 문서 표면을 지원하고 여러 문서 타입이 렌더링 레이어를 공유합니다.
• 확장 가능한 UI: React, Vue, Web Components 및 프레임워크별 애플리케이션 셸에 통합할 수 있습니다.

⚡ 빠른 시작

전체 제품 기능을 활용하고 구성을 정밀하게 제어하려면 Plugin Mode를 사용하세요. 지원되는 Sheets, Docs, Node 프로필에서는 Preset Mode가 더 짧은 curated setup을 제공합니다.

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 SheetsFormulaEnUS from '@univerjs/sheets-formula/locale/en-US'
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/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,
      SheetsFormulaEnUS,
      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({})

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({})

페이지에는 컨테이너가 필요합니다.

<div id="app" style="height: 100vh"></div>

자세한 내용은 Installation & Basic Usage guide, createUniver reference, Facade API reference를 참고하세요.

🧩 Preset Mode vs Plugin Mode

선택	사용 시점	시작하기
Plugin Mode	패키지, 구성된 종속성, 지연 로딩, 런타임 구성을 엄격하게 제어해야 할 때.	이 저장소의 examples/ 및 architecture guide
Preset Mode	최소 설정으로 동작하는 Sheets, Docs, Node 구성이 필요할 때.	이 저장소의 presets/ 및 getting started guide
Headless Mode	UI 없이 서버 측 워크북/문서 처리, 수식 계산, 자동화가 필요할 때.	Headless Univer

모든 @univerjs/* 패키지는 같은 버전으로 유지하세요. Univer Pro 패키지를 사용하는 경우 @univerjs-pro/* 버전도 맞춰야 합니다.

API 호환성 기대치, experimental APIs, internal APIs, deprecation rules는 API Stability Policy를 참고하세요.

🧭 호환성

• 브라우저 런타임: Univer는 Chrome 88을 대상으로 컴파일되며 Edge >=88, Firefox >=90, Chrome >=88, Safari >=14.1, Electron >=12에서 잘 동작하도록 노력합니다.
• 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이 필요합니다.

🛠️ 만들 수 있는 것

영역	오픈소스 기능	Univer Pro 확장
Sheets	워크북, 워크시트, 범위, 선택, 수식, 숫자 서식, 필터링, 정렬, 데이터 유효성 검사, 조건부 서식, 하이퍼링크, 댓글, 찾기/바꾸기, 노트, 테이블, drawing integration, 확장 가능한 UI 플러그인.	실시간 협업, 편집 기록, import/export, printing, charts, pivot tables, sparklines, outlines, shapes, in-cell graphics, data connectors, server-side calculation, 향상된 formula 기능.
Docs	리치 문서 모델, 편집 UI, 목록, 하이퍼링크, drawing integration, 댓글, quick insert, 공유 문서 아키텍처.	협업, import/export, printing, 향상된 tables/lists, columns, callouts, code blocks, quotes, shapes, remote comment resources.
Slides	프레젠테이션 데이터 모델과 UI 패키지. 현재 활발히 개발 중입니다.	Pro slide model/UI, slide import/export, chart/table model 및 UI plugins, 공유 shape editing infrastructure.
Bases	Univer의 plugin, command, model 아키텍처 위에서 커스텀 structured-data 경험을 만들 수 있습니다.	Base database model, commands, formula integration, workbench UI, field editors, render-engine views.
Runtime	브라우저 앱, Node.js headless 사용, Web Worker/RPC 패턴, multi-instance 사용, 서버 지향 자동화.	Collaboration client/server packages, Node.js collaboration client, Pro server services, SSR, computing delegation, server-side calculation, changeset replay tooling.
Integrations	React, Vue, Web Components, 프레임워크 템플릿, 테마, 로컬라이제이션, 커스텀 플러그인.	Pro presets, enterprise deployment packages.

Sheets는 현재 가장 성숙한 제품 영역입니다. Docs와 Slides는 Univer의 아키텍처를 공유하며 같은 SDK 안에서 계속 발전하고 있습니다.

🔓 Open Source와 Pro

이 저장소에는 Univer의 오픈소스 코어와 first-party OSS 플러그인이 포함되어 있습니다. Univer Pro는 고급 product surfaces, collaboration, server features, enterprise integrations를 위한 commercial extension layer로 별도 개발됩니다.

카테고리	Open source	Univer Pro / commercial
Foundation	Core SDK, 플러그인 시스템, 렌더링 엔진, 수식 엔진, Facade API, 테마, i18n, framework adapters.	Pro presets, enterprise deployment packages.
Sheets	핵심 스프레드시트 편집, 수식, 숫자 서식, filter/sort, 데이터 유효성 검사, 조건부 서식, 노트, 테이블, 하이퍼링크, 댓글, drawing, 찾기/바꾸기.	협업, 편집 기록, import/export, print, charts, pivot tables, sparklines, outlines, shapes, in-cell graphics, data connectors, range preprocessing, 향상된 formula engine 기능.
Docs	문서 모델과 편집 UI, 목록, 하이퍼링크, 댓글, quick insert, drawing integration.	협업, import/export, print, 향상된 tables/lists, columns, callouts, code blocks, quotes, shapes, remote thread-comment resources.
Slides	OSS presentation model과 UI packages.	Pro slide model/UI packages, slide import/export, charts, tables, reusable shape editor UI.
Bases	커스텀 data-centric products를 위한 확장 가능한 plugin architecture.	Base database core model, commands, mutations, formula integration, workbench UI, field editors, render-engine integration.
Server and runtime	Node.js headless runtime, RPC/Web Worker patterns, server-oriented automation primitives.	Collaboration server, Node.js collaboration client, SSR services, computing delegation, server-side calculation, collaboration changeset replay tooling.

Pro 기능은 Univer Pro guide에 문서화되어 있습니다. 여기서는 OSS 패키지의 범위를 명확히 하기 위해 의도적으로 분리했습니다.

Boundary principles:

• 이 저장소의 OSS 패키지는 Apache-2.0 license 아래에서 독립적으로 유용하게 사용할 수 있도록 의도되었습니다. Univer Pro는 선택 사항이며, 공개 OSS SDK API를 사용하는 데 필요하지 않습니다.
• OSS 패키지의 bugs, regressions, security issues는 관련 Pro 기능이 있더라도 OSS 저장소에서 보고하고 수정해야 합니다.
• OSS documentation은 Pro-only capabilities가 공개 @univerjs/* packages에 포함된 것처럼 암시해서는 안 됩니다. Pro-only APIs, packages, deployment paths는 명확히 이름을 표시해야 합니다.
• OSS feature에 Pro enhancement가 있더라도 OSS behavior는 독립적으로 문서화되어야 하며, 사용자가 commercial docs를 먼저 읽지 않고도 open-source surface를 평가할 수 있어야 합니다.

🌐 생태계

• Core SDK: dream-num/univer, 이 monorepo입니다.
• Presets: 이 저장소의 presets/, 브라우저와 Node.js 앱을 위한 curated plugin collection입니다.
• 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 >=11

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, 공유 플러그인 로직을 나누는 방법.
• API Stability Policy: stable, experimental, internal, deprecated, breaking-change expectations.
• 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 라이선스로 배포됩니다.