# FDocumentTextRange

- Human documentation: [https://docs.univer.ai/reference/facade/document-text-range](https://docs.univer.ai/reference/facade/document-text-range)

- Agent Markdown: [https://docs.univer.ai/reference/facade/document-text-range.md](https://docs.univer.ai/reference/facade/document-text-range.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [facade/document-text-range.mdx](https://github.com/dream-num/documentation/blob/dev/content/reference/facade/document-text-range.mdx)

---

Facade wrapper for reading and styling a fixed document text range.

Offsets are fixed when the wrapper is created. Create a new range after edits
that insert or remove content before it.

## Access

Access through:

* [`FDocumentParagraph.getTextRange()`](https://docs.univer.ai/reference/facade/document-paragraph.md#gettextrange)
* [`FDocumentParagraph.findText()`](https://docs.univer.ai/reference/facade/document-paragraph.md#findtext)
* [`FDocumentParagraph.findAllText()`](https://docs.univer.ai/reference/facade/document-paragraph.md#findalltext)
* [`FDocument.getTextRange()`](https://docs.univer.ai/reference/facade/document.md#gettextrange)
* [`FDocumentColumn.getTextRange()`](https://docs.univer.ai/reference/facade/document-column.md#gettextrange)

## Setup

Register [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) or a preset that includes it. In plugin mode, import `@univerjs/docs/facade`. Additional methods below require their listed plugin packages. See [Facade setup](https://docs.univer.ai/guides/docs/getting-started/facade.md).

## `@univerjs/docs`

### `FDocumentTextRange.describe`

Returns a serializable summary suitable for an agent/tool response.

```typescript
describe(): IFDocumentTextRangeDescription
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const range = fDocument?.findParagraphByText('Launch')?.getTextRange()
console.log(range?.describe())
```

**Types:** [`IFDocumentTextRangeDescription`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

**Package:** [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.getCommonExplicitTextStyle`

Returns top-level style properties that have the same explicit value
across the complete range. Unstyled gaps make a property non-common.

```typescript
getCommonExplicitTextStyle(): ITextStyle
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const range = fDocument?.findParagraphByText('Launch')?.getTextRange()
console.log(range?.getCommonExplicitTextStyle())
```

**Types:** [`ITextStyle`](https://docs.univer.ai/reference/types/text-style.md)

**Package:** [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.getExplicitTextStyleRuns`

Returns explicit text-style runs intersecting this range.
Returned offsets are clipped to the range and remain document-relative.

```typescript
getExplicitTextStyleRuns(): IFDocumentTextStyleRun[]
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const range = fDocument?.findParagraphByText('Launch')?.getTextRange()
console.log(range?.getExplicitTextStyleRuns())
```

**Types:** [`IFDocumentTextStyleRun`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

**Package:** [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.getRange`

Returns the serializable document range.

```typescript
getRange(): IFDocumentTextRange
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const range = fDocument?.findParagraphByText('Launch')?.getTextRange()
console.log(range?.getRange())
```

**Types:** [`IFDocumentTextRange`](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/utils.d.ts)

**Package:** [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.getText`

Returns the plain data-stream text in this range.

```typescript
getText(): string
```

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const range = fDocument?.findParagraphByText('Launch')?.getTextRange()
console.log(range?.getText())
```

**Package:** [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.setText`

Replaces the range with plain text while preserving document mutation semantics.

```typescript
setText(text: string): boolean
```

**Parameters**

* `text` — Required.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const range = fDocument?.findParagraphByText('Draft')?.getTextRange()
range?.setText('Final')
```

**Package:** [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.setTextStyle`

Merges a text-style patch into every character in the range.
Existing text-run splitting, merging, and normalization are handled by
the document mutation pipeline.
`style.fs` is a font size in points (pt), not CSS pixels.

```typescript
setTextStyle(style: ITextStyle): boolean
```

**Parameters**

* `style` — Required.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const range = fDocument?.findParagraphByText('Launch')?.getTextRange()
range?.setTextStyle({ fs: 10.5, bl: univerAPI.Enum.BooleanNumber.TRUE })
```

**Types:** [`ITextStyle`](https://docs.univer.ai/reference/types/text-style.md)

**Package:** [`@univerjs/docs`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

## `@univerjs/docs-thread-comment`

### `FDocumentTextRange.createCommentAsync`

Creates a comment on this text range.

```typescript
createCommentAsync(content: ThreadComment.ThreadCommentContent, options?: IDocumentTextRangeCommentCreateOptions): Promise<boolean>
```

**Parameters**

* `content` — Required. Plain text or a Univer document body for rich comment content.
* `options` — Optional. Default: `{}`. Optional stable IDs, author, attachments, and creation time.

**Returns**

`true` when the create command succeeds; otherwise, `false`.

**Throws**

If the content is empty.

**Examples**

```ts
const range = univerAPI.getActiveDocument()?.getTextRange(0, 12)
await range?.createCommentAsync('Verify this introduction.', { id: 'review-intro' })
```

**Types:** [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`ThreadComment.ThreadCommentContent`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`IDocumentTextRangeCommentCreateOptions`](https://unpkg.com/@univerjs/docs-thread-comment@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

**Package:** [`@univerjs/docs-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/docs-thread-comment@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.getComments`

Returns locally loaded comments whose comment decorations overlap this text range.

```typescript
getComments(): ThreadComment.IFacadeThreadCommentInfo[]
```

**Returns**

Matching comment threads. The returned anchors use `DOC_TEXT_RANGE`.

**Examples**

```ts
const range = univerAPI.getActiveDocument()?.getTextRange(0, 12)
const comments = range?.getComments() ?? []
comments.forEach(({ root, children }) => console.log(root.id, children.length))
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts)

**Package:** [`@univerjs/docs-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/docs-thread-comment@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.listCommentsAsync`

Synchronizes known document threads and returns comments whose decorations overlap this text range.

```typescript
listCommentsAsync(): Promise<ThreadComment.IFacadeThreadCommentInfo[]>
```

**Returns**

A promise resolving to the synchronized matching comment threads.

**Examples**

```ts
const range = univerAPI.getActiveDocument()?.getTextRange(0, 12)
const comments = range ? await range.listCommentsAsync() : []
console.log(comments.length)
```

**Types:** [`ThreadComment.IFacadeThreadCommentInfo`](https://unpkg.com/@univerjs/thread-comment@1.0.0-rc.0/lib/types/services/thread-comment-api.service.d.ts) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts)

**Package:** [`@univerjs/docs-thread-comment`](https://docs.univer.ai/reference/packages/plugins/univerjs/docs-thread-comment.md) · [Type definitions](https://unpkg.com/@univerjs/docs-thread-comment@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

## `@univerjs-pro/docs-formula`

### `FDocumentTextRange.replaceWithFormula`

Replaces this complete text range with one whole-entity Doc Formula.

The fixed range must be in the main body and must not cross paragraph,
table-cell, section, column, or protected structural boundaries.

```typescript
replaceWithFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null
```

**Parameters**

* `formula` — Required. Formula text.
* `options` — Optional. Default: `{}`. Optional number format and complete external Source bindings.

**Returns**

The inserted formula, or `null` when range/binding validation fails.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'

export function replacePlaceholderWithFormula(univerAPI: FUniver) {
  const document = univerAPI.getActiveDocument()
  if (!document) throw new Error('No active document')
  const paragraph = document.findParagraphByText('FORMULA_PLACEHOLDER')
  const range = paragraph?.findText('FORMULA_PLACEHOLDER')
  if (!range) throw new Error('Formula placeholder not found')
  const formula = range.replaceWithFormula('=SUM(10,20)')
  if (!formula) throw new Error('Failed to replace the range')
  return formula.describe()
}
```

**Types:** [`FDocumentFormula`](https://docs.univer.ai/reference/facade/document-formula.md) · [`IDocFormulaCreateFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-formula@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-formula`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-formula.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-formula@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

## `@univerjs-pro/docs-latex`

### `FDocumentTextRange.insertLatexAfter`

Inserts one inline LaTeX formula immediately after this text range.

The original range content is preserved.

```typescript
insertLatexAfter(latex: string, options?: IDocsLatexCreateFacadeOptions): FDocumentLatex | null
```

**Parameters**

* `latex` — Required. LaTeX source without `$` or `$$` delimiters.
* `options` — Optional. Default: `{}`. Optional visual properties.

**Returns**

The inserted formula, or `null` when the command fails.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')

const paragraph = document.findParagraphByText('Force')
const range = paragraph?.findText('Force')
if (!range) throw new Error('Target text not found')

const formula = range.insertLatexAfter('F = ma')
if (!formula) throw new Error('Failed to insert LaTeX formula')
```

**Types:** [`FDocumentLatex`](https://docs.univer.ai/reference/facade/document-latex.md) · [`IDocsLatexCreateFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-latex@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-latex`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-latex.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-latex@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.insertLatexBefore`

Inserts one inline LaTeX formula immediately before this text range.

The original range content is preserved.

```typescript
insertLatexBefore(latex: string, options?: IDocsLatexCreateFacadeOptions): FDocumentLatex | null
```

**Parameters**

* `latex` — Required. LaTeX source without `$` or `$$` delimiters.
* `options` — Optional. Default: `{}`. Optional visual properties.

**Returns**

The inserted formula, or `null` when the command fails.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')

const paragraph = document.findParagraphByText('result')
const range = paragraph?.findText('result')
if (!range) throw new Error('Target text not found')

const formula = range.insertLatexBefore('x = 1')
if (!formula) throw new Error('Failed to insert LaTeX formula')
```

**Types:** [`FDocumentLatex`](https://docs.univer.ai/reference/facade/document-latex.md) · [`IDocsLatexCreateFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-latex@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-latex`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-latex.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-latex@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)

### `FDocumentTextRange.replaceWithLatex`

Replaces this text range with one inline LaTeX formula.

The range is fixed when created. Resolve a new range after edits that
insert or remove content before it. The range must not cross paragraph,
table-cell, column, block, or section boundaries.

```typescript
replaceWithLatex(latex: string, options?: IDocsLatexCreateFacadeOptions): FDocumentLatex | null
```

**Parameters**

* `latex` — Required. LaTeX source without `$` or `$$` delimiters.
* `options` — Optional. Default: `{}`. Optional visual properties.

**Returns**

The inserted formula, or `null` when the command fails.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')

const paragraph = document.findParagraphByText('FORMULA_PLACEHOLDER')
if (!paragraph) throw new Error('Target paragraph not found')

const matches = paragraph.findAllText('FORMULA_PLACEHOLDER')
if (matches.length !== 1) {
  throw new Error(`Expected one placeholder, found ${matches.length}`)
}

const formula = matches[0].replaceWithLatex('F = ma')
if (!formula) throw new Error('Failed to replace text with LaTeX')
console.log(formula.describe())
```

**Types:** [`FDocumentLatex`](https://docs.univer.ai/reference/facade/document-latex.md) · [`IDocsLatexCreateFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-latex@1.0.0-rc.0/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-latex`](https://docs.univer.ai/reference/packages/plugins/univerjs-pro/docs-latex.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-latex@1.0.0-rc.0/lib/types/facade/f-document-text-range.d.ts)