# 富文字使用指南

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/features/core/rich-text.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/core/rich-text.zh-TW.mdx)

---

Univer 提供了強大的富文字功能，可以在多個場景中使用，包括單元格內容、評論和超連結等。本指南將介紹如何使用富文字功能。

## Facade API

Facade API 提供了一系列建立富文字相關物件的方法：

```typescript
// 建立富文字
const richText = univerAPI.newRichText()
const richTextValue = univerAPI.newRichTextValue({ body: { dataStream: 'Hello Univer\r\n' } })

// 建立段落樣式
const paragraphStyle = univerAPI.newParagraphStyle()
const paragraphStyleValue = univerAPI.newParagraphStyleValue()

// 建立文字樣式
const textStyle = univerAPI.newTextStyle()
const textStyleValue = univerAPI.newTextStyleValue()

// 建立文字裝飾
const decoration = univerAPI.newTextDecoration()
```

每個建立方法都有對應的 Builder 和 Value 版本：

* Builder 版本（如 `newRichText`）用於建立和修改樣式
* Value 版本（如 `newRichTextValue`）用於建立只讀的樣式物件

## 基礎概念

富文字系統主要包含兩個核心元件：

1. **TextStyle（文字樣式）**：控制文字的外觀，如字型、大小、顏色等
2. **ParagraphStyle（段落樣式）**：控制段落級別的格式，如對齊方式、縮排、行距等

## 文字樣式設定

### 建立文字樣式

```typescript
// 建立一個基礎的文字樣式
const textStyle = univerAPI.newTextStyle()
  .setFontFamily('Arial')
  .setFontSize(12)
  .setItalic(true)
  .setBold(true)
  .build()

// 建立帶顏色的文字樣式
const coloredStyle = univerAPI.newTextStyle()
  .setColor({ rgb: '#FF0000' }) // 設定紅色文字
  .setBackground({ rgb: '#FFFF00' }) // 設定黃色背景
  .build()
```

### 文字裝飾

```typescript
// 新增下劃線
const underlineStyle = univerAPI.newTextStyle()
  .setUnderline(
    univerAPI.newTextDecoration()
      .setShow(true)
      .setColor({ rgb: '#0000FF' })
      .setLineType(univerAPI.Enum.TextDecoration.SINGLE),
  )
  .build()

// 新增刪除線
const strikethroughStyle = univerAPI.newTextStyle()
  .setStrikethrough(
    univerAPI.newTextDecoration()
      .setShow(true),
  )
  .build()
```

## 段落樣式設定

### 建立段落樣式

```typescript
// 建立基礎段落樣式
const paragraphStyle = univerAPI.newParagraphStyle()
  .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER) // 居中對齊
  .setLineSpacing(1.5) // 1.5倍行距
  .build()

// 設定段落縮排
const indentedStyle = univerAPI.newParagraphStyle()
  .setIndentFirstLine({ value: 2, unit: 'cm' }) // 首行縮排2釐米
  .setIndentStart({ value: 1, unit: 'cm' }) // 左側縮排1釐米
  .build()
```

## 應用場景

### 1. 單元格富文字

有兩種方式可以設定單元格的富文字：[`setRichTextValueForCell`](https://docs.univer.ai/zh-TW/reference/facade/range.md#setrichtextvalueforcell) 和 [`setRichTextValues`](https://docs.univer.ai/zh-TW/reference/facade/range.md#setrichtextvalues)。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:B2')
console.log(fRange.getValue(true))

// A1 單元格設定為富文字
const richText = univerAPI.newRichText()
  .insertText('Hello Univer')
  .setStyle(0, 1, { bl: 1, cl: { rgb: '#c81e1e' } })
  .setStyle(6, 7, { bl: 1, cl: { rgb: '#c81e1e' } })
fRange.setRichTextValueForCell(richText)
console.log(fRange.getValue(true).toPlainText()) // Hello Univer

// A1:B2 單元格設定為富文字
fRange.setRichTextValues([
  [richText, richText],
  [null, null],
])
console.log(fRange.getValue(true).toPlainText()) // Hello Univer
```

### 2. 評論富文字

```typescript
// 新增帶格式的評論
const range = univerAPI.getActiveWorkbook()
  .getActiveSheet()
  .getActiveRange()

// 建立評論內容
const comment = univerAPI.newTheadComment()
  .setContent(
    univerAPI.newRichText()
      .insertText('你好，請檢查這個單元格的資料'),
  )

// 非同步新增評論
const success = await range.addCommentAsync(comment)
if (success) {
  console.log('評論新增成功')
}
```

### 3. 超連結富文字

```typescript
// 建立帶超連結的富文字
const range = univerAPI.getActiveWorkbook()
  .getActiveSheet()
  .getActiveRange()

// 使用 newRichText().insertLink 建立超連結
const richText = univerAPI.newRichText()
  .insertLink('訪問 Univer', '/')

// 設定到單元格
range.setRichTextValueForCell(richText)
```