# Univer Docs API

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

Univer Docs 提供专业级文档排版能力，相关概念会尽可能与 Microsoft Word 保持一致。

## 引入

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

## 操作文档

文档单元中 `unitId` 对应的是文档的唯一标识，文档不存在 `subUnitId`。

文档的文本内容存储在 `body.dataStream` 字符串中，此字符串不包含样式信息。

样式信息单独存储在另外的数据结构中，并通过下标索引与文本内容关联。

对于换行、分页、章节、段落、表格等元素， 在文本内容中使用不同的特殊字符来标记，这些特殊字符在渲染时被转换为对应的元素。

> [!NOTE]
> 想要进一步了解文档的数据结构设计吗？推荐阅读[《Univer 文档架构及模块设计》](/blog/univer-doc-architecture) 和[《Univer
> 文档排版设计初探》](/blog/doc-typesetting-design)。

### 创建文档

使用 `univerAPI.createDocument(data)` 创建新的文档，并获取对应的 `FDocument` facade 包装对象。

参数是一个可选的文档数据对象，包含了文档的初始数据。如果传入 `{}`，则创建一个空文档。

如果直接使用底层 `univer` 实例而不是 Facade API，则使用 `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.ZH_CN,
})
console.log(statistics.words, statistics.charactersWithSpaces, statistics.paragraphs)
```

`getStatistics()` 返回单词、字符和段落数量。通过 `ranges` 可仅统计选中文本，通过 `signal` 可取消已不再需要的计算。