# Univer Docs API

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [docs/features/core/docs-api.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/core/docs-api.zh-TW.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_TW,
})
console.log(statistics.words, statistics.charactersWithSpaces, statistics.paragraphs)
```

`getStatistics()` 會傳回單字、字元與段落數量。透過 `ranges` 可只統計選取的文字，透過 `signal` 可取消已不再需要的計算。