# Univer Docs API

- Human documentation: [https://docs.univer.ai/ko-KR/guides/docs/features/core/docs-api](https://docs.univer.ai/ko-KR/guides/docs/features/core/docs-api)

- Agent Markdown: [https://docs.univer.ai/ko-KR/guides/docs/features/core/docs-api.md](https://docs.univer.ai/ko-KR/guides/docs/features/core/docs-api.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

- Source: [docs/features/core/docs-api.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/core/docs-api.ko-KR.mdx)

---

Univer Docs는 Microsoft Word와 유사한 개념을 바탕으로 전문적인 문서 조판 기능을 제공합니다.

## 가져오기

```typescript
import '@univerjs/docs/facade'
import '@univerjs/docs-ui/facade'
```

## 문서 조작

문서 유닛에서 `unitId`는 문서의 고유 식별자이며, 문서에는 `subUnitId`가 없습니다.

문서의 텍스트 콘텐츠는 `body.dataStream` 문자열에 저장되며, 이 문자열에는 스타일 정보가 포함되지 않습니다.

스타일 정보는 별도의 데이터 구조에 저장되고 인덱스 참조를 통해 텍스트 콘텐츠와 연결됩니다.

줄 바꿈, 페이지 나누기, 섹션, 단락, 표 등의 요소는 서로 다른 특수 문자로 텍스트 콘텐츠에 표시됩니다. 렌더링할 때 이러한 특수 문자가 해당 요소로 변환됩니다.

> [!NOTE]
> 문서 데이터 구조의 설계를 더 자세히 알아보고 싶다면 [Univer Document Architecture and Module
> Design](/blog/univer-doc-architecture)과 [An Initial Exploration of Univer Document Typesetting
> Design](/blog/doc-typesetting-design)을 읽어 보세요.

### 문서 만들기

`univerAPI.createDocument(data)`를 사용해 새 문서를 만들고 해당 `FDocument` facade 래퍼를 가져옵니다.

매개변수는 문서의 초기 데이터를 포함하는 선택적 문서 데이터 객체입니다. `{}`를 전달하면 빈 문서가 만들어집니다.

Facade API 대신 하위 수준의 `univer` 인스턴스를 직접 사용하는 경우 `univer.createUnit(UniverInstanceType.UNIVER_DOC, data)`를 사용하세요.

```typescript
// [!code word:data]
const doc = univerAPI.createDocument(data)
```

### 문서 unitId 가져오기

```typescript
const doc = univerAPI.getActiveDocument()
const unitId = doc?.getId()
```

### 문서 데이터 가져오기

```typescript
const doc = univerAPI.getActiveDocument()
const saveData = doc.save()
```

### 문서 폐기하기

문서가 더 이상 필요하지 않으면 Univer 인스턴스의 `dispose` 메서드를 호출해 인스턴스를 폐기할 수 있습니다.

```typescript
univer.dispose()
```

## 텍스트 조작

리치 텍스트 영역의 텍스트 요소를 수정합니다.

### 텍스트 삽입하기

이 텍스트 영역의 끝에 지정한 텍스트를 추가합니다.

```typescript
const doc = univerAPI.getActiveDocument()
doc?.insertText(0, 'Univer')
```

### 텍스트 삭제하기

문서 오프셋을 기준으로 텍스트를 삭제합니다.

```typescript
const doc = univerAPI.getActiveDocument()
doc?.deleteRange({ startOffset: 0, endOffset: 1 })
```

## 스타일 수정

단락의 텍스트 스타일을 설정합니다.

```typescript
const doc = univerAPI.getActiveDocument()
const paragraph = doc?.getParagraphs()[0]

paragraph?.setStyle({
  textStyle: {
    cl: {
      rgb: '#FF0000',
    },
  },
})
```

## 페이지 나누기 삽입

`\f` 문자는 페이지 나누기를 나타내며, 문서에 페이지 나누기를 삽입할 때 사용합니다.

```typescript
const doc = univerAPI.getActiveDocument()
doc?.insertText(0, '\f')
```

## 문서 통계

기반 `DocumentDataModel`을 사용해 전체 문서나 선택한 범위의 통계를 계산할 수 있습니다.

```typescript
const doc = univerAPI.getActiveDocument()
if (!doc) throw new Error('No active document')

const statistics = await doc.getDocumentDataModel().getStatistics({
  locale: univerAPI.Enum.LocaleType.KO_KR,
})
console.log(statistics.words, statistics.charactersWithSpaces, statistics.paragraphs)
```

`getStatistics()`는 단어, 문자, 단락 수를 반환합니다. `ranges`로 선택한 텍스트만 집계하고 `signal`로 더 이상 필요하지 않은 계산을 취소할 수 있습니다.