# Univer Docs API

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Univer Docs provides professional document typesetting capabilities, with concepts closely aligned with Microsoft Word.

## Importing

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

## Operate Documents

For document units, `unitId` corresponds to the unique identifier of the document, and documents do not have a `subUnitId`.

The text content of the document is stored in the `body.dataStream` string, which does not contain style information.

Style information is stored separately in another data structure and is associated with the text content through index references.

For elements such as line breaks, page breaks, sections, paragraphs, and tables, different special characters are used to mark them in the text content. These special characters are converted to corresponding elements during rendering.

> [!NOTE]
> Want to learn more about the design of document data structures? We recommend reading [Univer Document Architecture
> and Module Design](/blog/univer-doc-architecture) and [An Initial Exploration of Univer Document Typesetting
> Design](/blog/doc-typesetting-design).

### Create Document

Use `univerAPI.createDocument(data)` to create a new document and get its `FDocument` facade wrapper.

The parameter is an optional document data object that contains the initial data for the document. If `{}` is passed, an empty document is created.

When working with the underlying `univer` instance directly instead of the Facade API, use `univer.createUnit(UniverInstanceType.UNIVER_DOC, data)`.

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

### Get Document unitId

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

### Get Document Data

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

### Dispose Document

When we no longer need the document, we can call the `dispose` method of the Univer instance to destroy the instance.

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

## Operate Text

Modify text elements in the rich text area

### Insert Text

To append specified text to the end of this text area.

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

### Delete Text

Delete text by document offsets.

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

## Modify Style

Set text style on a paragraph.

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

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

## Insert Page Break

The `\f` character is a page break, used to insert a page break in the document.

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

## Document statistics

Use the underlying `DocumentDataModel` to calculate statistics for the whole document or selected ranges.

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

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

`getStatistics()` returns word, character, and paragraph counts. Pass `ranges` to count selected text or an `AbortSignal` in `signal` to cancel obsolete calculations.