# 註解與原生文字

> 插入受支援的 PDF 註解，並將匯入的原生文字提升為可編輯文字方塊。

- Human documentation: [https://docs.univer.ai/zh-TW/guides/pdfs/features/core/annotations-and-native-text](https://docs.univer.ai/zh-TW/guides/pdfs/features/core/annotations-and-native-text)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/pdfs/features/core/annotations-and-native-text.md](https://docs.univer.ai/zh-TW/guides/pdfs/features/core/annotations-and-native-text.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

可編輯註解是持久覆蓋層。匯入文字會保持原生狀態，直到透過 Facade 提升某個可見文字片段。

## 插入註解

```ts
const highlight = page.insertAnnotation({
  annotationType: univerAPI.Enum.PdfAnnotationType.HIGHLIGHT,
  left: 36,
  top: 72,
  width: 180,
  height: 18,
  markup: {
    color: '#fde047',
    opacity: 0.6,
  },
})
```

Facade 插入支援醒目提示、底線、刪除線、波浪線和筆跡註解。筆跡必須包含非空路徑；此插入 API 不接受其他核心註解子類型。

## 讀取註解資料與樣式

```ts
const markup = highlight.getMarkup()
const style = highlight.getStyle()

highlight.setStyle({
  stroke: { color: '#ca8a04', width: 1 },
  opacity: 0.75,
})
```

`getMarkup()` 和 `getInk()` 傳回以 PDF 點表示的分離幾何。`setStyle()` 更新受支援的填滿、筆畫和不透明度；不透明度必須介於 `0` 和 `1` 之間。

## 取代匯入的原生文字

```ts
const matchingSpan = page
  .getTextSpans()
  .find((span) => span.getText().includes('Draft'))

if (matchingSpan) {
  const textBox = matchingSpan.replaceText('Final')
  textBox.setTextStyle({ bold: true })
}
```

`getTextSpans()` 傳回目前可見且未被抑制的原生文字快照。`replaceText()` 會不可分地抑制來源操作，並在擷取位置插入可編輯的 `FPdfTextBox`。

`FPdfTextSpan` 是快照控制代碼。取代後該控制代碼即失效，因此下一次原生文字操作前應重新列舉 `getTextSpans()`。