# Annotations and Native Text

> Insert supported PDF annotations and promote imported native text into editable text boxes.

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Editable annotations are durable overlays. Imported text remains native until a visible text span is promoted through the Facade.

## Insert annotations

```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 insertion supports highlight, underline, strikeout, squiggly, and ink annotations. Ink requires non-empty paths; other core annotation subtypes are not accepted by this insertion API.

## Read annotation data and style

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

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

`getMarkup()` and `getInk()` return detached geometry in PDF points. `setStyle()` updates supported fill, stroke, and opacity fields; opacity must be between `0` and `1`.

## Replace imported native text

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

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

`getTextSpans()` returns snapshots of currently visible, unsuppressed native text. `replaceText()` atomically suppresses the source operation and inserts an editable `FPdfTextBox` at the captured position.

An `FPdfTextSpan` is a snapshot handle. After replacement it is stale, so enumerate `getTextSpans()` again before the next native-text operation.