FDocumentTextRange

本 API 页面目前提供英文正文。代码签名与标识符不随界面语言变化。

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.

Setup

Register @univerjs/docs or a preset that includes it. In plugin mode, import @univerjs/docs/facade. Additional methods below require their listed plugin packages. See Facade setup.

`@univerjs/docs`

`FDocumentTextRange.describe`

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

TypeScript

describe(): IFDocumentTextRangeDescription

Examples

TypeScript

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

Types: IFDocumentTextRangeDescription

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: ITextStyle

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: IFDocumentTextStyleRun

Package: @univerjs/docs · Type definitions

`FDocumentTextRange.getRange`

Returns the serializable document range.

TypeScript

getRange(): IFDocumentTextRange

Examples

TypeScript

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

Types: IFDocumentTextRange

Package: @univerjs/docs · Type definitions

`FDocumentTextRange.getText`

Returns the plain data-stream text in this range.

TypeScript

getText(): string

Examples

TypeScript

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

Package: @univerjs/docs · Type definitions

`FDocumentTextRange.setText`

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

TypeScript

setText(text: string): boolean

Parameters

text — Required.

Examples

TypeScript

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

Package: @univerjs/docs · Type definitions

`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

TypeScript

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

Types: ITextStyle

Package: @univerjs/docs · Type definitions

`@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

TypeScript

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

Types: Promise · ThreadComment.ThreadCommentContent · IDocumentTextRangeCommentCreateOptions

Package: @univerjs/docs-thread-comment · Type definitions

`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

TypeScript

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

Types: ThreadComment.IFacadeThreadCommentInfo

Package: @univerjs/docs-thread-comment · Type definitions

`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

TypeScript

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

Types: ThreadComment.IFacadeThreadCommentInfo · Promise

Package: @univerjs/docs-thread-comment · Type definitions

`@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

TypeScript

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 · IDocFormulaCreateFacadeOptions

Package: @univerjs-pro/docs-formula · Type definitions

`@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

TypeScript

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 · IDocsLatexCreateFacadeOptions

Package: @univerjs-pro/docs-latex · Type definitions

`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

TypeScript

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 · IDocsLatexCreateFacadeOptions

Package: @univerjs-pro/docs-latex · Type definitions

`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

TypeScript

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 · IDocsLatexCreateFacadeOptions

Package: @univerjs-pro/docs-latex · Type definitions

你觉得这篇文档如何？