FDocumentParagraph

A paragraph facade wrapper.

Paragraph identity is backed by the persisted paragraphId. The id is re-resolved before each method call, so insertions before this paragraph do not break the wrapper.

Access

Access through:

• FDocument.insertHorizontalRule()
• FDocument.getParagraphs()
• FDocument.getParagraph()
• FDocument.findParagraphByText()
• FDocument.findParagraphs()
• FDocument.insertParagraph()
• FDocument.appendParagraph()
• FDocumentColumn.getParagraphs()

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

FDocumentParagraph.appendText

Append plain text before this paragraph's trailing paragraph break.

appendText(text: string): boolean

Parameters

• text — Required. The plain text to append.

Returns

true if the text was appended.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]paragraph?.appendText(' Appended text')console.log(paragraph?.getText())

Package: @univerjs/docs · Type definitions

FDocumentParagraph.findAllText

Finds every non-overlapping literal text occurrence inside this paragraph.

Results are ordered from the start of the paragraph. The returned ranges are fixed when created; use them immediately and resolve new ranges after edits that change earlier document content.

findAllText(text: string, options?: Omit<IFDocumentFindTextOptions, 'occurrence'>): FDocumentTextRange[]

Parameters

• text — Required. Literal text to find. It must not be empty.
• options — Optional. Default: {}. Case-sensitivity option.

Returns

All matching fixed text ranges, or an empty array when no matches exist.

Examples

const univerAPI = FUniver.newAPI(univer)const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active document')const paragraph = document.findParagraphByText('x plus x')if (!paragraph) throw new Error('Target paragraph not found')const matches = paragraph.findAllText('x')console.log(matches.map((range) => range.describe()))

Types: FDocumentTextRange · Omit · IFDocumentFindTextOptions

Package: @univerjs/docs · Type definitions

FDocumentParagraph.findText

Finds one literal text occurrence inside this paragraph.

The returned text range is fixed when it is created. Resolve a new range after edits that insert or remove content before the match.

findText(text: string, options?: IFDocumentFindTextOptions): FDocumentTextRange | null

Parameters

• text — Required. Literal text to find. It must not be empty.
• options — Optional. Default: {}. Case sensitivity and zero-based occurrence.

Returns

The matching fixed text range, or null when no such occurrence exists.

Examples

const univerAPI = FUniver.newAPI(univer)const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active document')const paragraph = document.findParagraphByText('Launch formula')if (!paragraph) throw new Error('Target paragraph not found')const range = paragraph.findText('formula')if (!range) throw new Error('Target text not found')console.log(range.describe())

Types: FDocumentTextRange · IFDocumentFindTextOptions

Package: @univerjs/docs · Type definitions

FDocumentParagraph.getId

Get the persisted paragraph id.

getId(): string

Returns

The paragraph id.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]console.log(paragraph?.getId())

Package: @univerjs/docs · Type definitions

FDocumentParagraph.getInfo

Get this paragraph's metadata.

getInfo(): IFDocumentParagraphInfo

Returns

The paragraph info.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]console.log(paragraph?.getInfo())

Types: IFDocumentParagraphInfo

Package: @univerjs/docs · Type definitions

FDocumentParagraph.getPermission

Returns this Paragraph's permission facade.

getPermission(): FDocumentObjectPermission

Returns

Permission facade combining Document, Section, and Paragraph Edit points.

Examples

const paragraph = univerAPI.getActiveDocument()?.getParagraphs()[0]if (!paragraph) throw new Error('Paragraph not found.')await paragraph.getPermission().setReadOnly()

Types: FDocumentObjectPermission

Package: @univerjs/docs · Type definitions

FDocumentParagraph.getRange

Get the current text range occupied by this paragraph.

getRange(): IFDocumentTextRange

Returns

The paragraph text range, excluding the trailing paragraph break.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]console.log(paragraph?.getRange())

Types: IFDocumentTextRange

Package: @univerjs/docs · Type definitions

FDocumentParagraph.getSegmentId

Get the segment id of this paragraph. The main body paragraphs have an empty string segment id. The header and footer paragraphs have a non-empty string segment id.

getSegmentId(): string

Returns

The segment id.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]console.log(paragraph?.getSegmentId())

Package: @univerjs/docs · Type definitions

FDocumentParagraph.getText

Get this paragraph's plain text.

getText(): string

Returns

The paragraph text without the trailing paragraph break.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]console.log(paragraph?.getText())

Package: @univerjs/docs · Type definitions

FDocumentParagraph.getTextRange

Returns an agent-friendly facade for reading and styling this paragraph's text.

getTextRange(): FDocumentTextRange

Returns

The paragraph text range, excluding the trailing paragraph break.

Examples

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

Types: FDocumentTextRange

Package: @univerjs/docs · Type definitions

FDocumentParagraph.isListItem

Check whether this paragraph is a bullet, ordered, or checklist item.

isListItem(): boolean

Returns

true if the paragraph has list metadata.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]console.log(paragraph?.isListItem())

Package: @univerjs/docs · Type definitions

FDocumentParagraph.isTask

Check whether this paragraph is a task/checklist item.

isTask(): boolean

Returns

true if this paragraph is an unchecked or checked task item.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]console.log(paragraph?.isTask())

Package: @univerjs/docs · Type definitions

FDocumentParagraph.remove

Remove this paragraph.

remove(): boolean

Returns

true if the paragraph was removed.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]const success = paragraph?.remove()console.log(success ? 'Paragraph removed' : 'Failed to remove paragraph')

Package: @univerjs/docs · Type definitions

FDocumentParagraph.setStyle

Applies a paragraph and optional text-style patch through one document command.

Pagination values use BooleanNumber.TRUE or BooleanNumber.FALSE; explicit false is preserved and overrides inherited true. The paragraph and text-style changes share one undo/redo item. A stale paragraph handle returns false without applying a partial update.

The Traditional renderer applies these Word-compatible pagination rules: use pageBreakBefore for a hard chapter-page boundary, keepLines for a short paragraph that should stay intact, keepNext for a heading or caption that should accompany the next paragraph, and widowControl for natural multi-line body text. Do not enable every rule on every paragraph. Modern and Unspecified Docs preserve the values in the model but do not apply them to physical pages.

style.textStyle.fs is a font size in points (pt), not CSS pixels.

setStyle(style: IParagraphStyle): boolean

Parameters

• style — Required. The Univer paragraph style patch.

Returns

true when the complete patch was applied; otherwise false.

Examples

const document = univerAPI.getActiveDocument()if (!document) {  throw new Error('No active document')}if (!document.isTraditional()) {  throw new Error('Traditional document pagination is required')}const heading = document.findParagraphByText('Appendix')const following = document.findParagraphByText('Supporting details')if (!heading || !following) {  throw new Error('Expected paragraphs were not found')}const headingUpdated = heading.setStyle({  pageBreakBefore: univerAPI.Enum.BooleanNumber.TRUE,  keepLines: univerAPI.Enum.BooleanNumber.TRUE,  keepNext: univerAPI.Enum.BooleanNumber.TRUE,})const followingUpdated = following.setStyle({  // Explicit FALSE terminates this authored keepNext chain even if a named  // style or document default enables it.  keepNext: univerAPI.Enum.BooleanNumber.FALSE,  widowControl: univerAPI.Enum.BooleanNumber.TRUE,})if (!headingUpdated || !followingUpdated) {  throw new Error('Failed to update paragraph pagination')}

Types: IParagraphStyle

Package: @univerjs/docs · Type definitions

FDocumentParagraph.setTaskChecked

Set the checked state of this task/checklist paragraph.

setTaskChecked(checked: boolean): boolean

Parameters

• checked — Required. Whether the task item should be checked.

Returns

true if the task state was updated, or false if this paragraph is not a task item.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]if (paragraph.isTask()) {  const success = paragraph.setTaskChecked(true)  console.log(success ? 'Task checked' : 'Failed to check task')}

Package: @univerjs/docs · Type definitions

FDocumentParagraph.setText

Replace this paragraph's plain text.

setText(text: string): boolean

Parameters

• text — Required. The replacement text. Do not include the paragraph break.

Returns

true if the paragraph text was replaced.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraphs()[0]paragraph?.setText('New text')console.log(paragraph?.getText())

Package: @univerjs/docs · Type definitions

@univerjs-pro/docs-formula

FDocumentParagraph.appendFormula

Appends one Formula before this paragraph's trailing paragraph token.

The Command resolves the persisted paragraphId and the semantic 'end' position together. It does not capture an absolute document offset or a paragraph length in advance. Header/footer paragraphs are rejected because Doc Formula v1 supports the main body only.

appendFormula(formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null

Parameters

• formula — Required. Formula text.
• options — Optional. Default: {}. Optional number format and stable external Source bindings.

Returns

The inserted formula, or null when the paragraph is missing, outside the main body, or the command validation fails.

Examples

import type { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/docs-formula/facade'export function appendParagraphFormula(univerAPI: FUniver) {  const document = univerAPI.getActiveDocument()  if (!document) throw new Error('No active document')  const paragraph = document.appendParagraph('Revenue: ')  const formula = paragraph.appendFormula('=1000/4', {    numberFormat: { pattern: '$#,##0.00' },  })  if (!formula) throw new Error('Failed to append Doc Formula')  return formula.describe()}

Types: FDocumentFormula · IDocFormulaCreateFacadeOptions

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

FDocumentParagraph.insertFormula

Inserts one Formula at a paragraph-relative UTF-16 offset.

The paragraph handle is backed by its persisted paragraphId. The Command resolves that id against the latest document snapshot and only then converts offset to a document position. Edits before this paragraph therefore do not invalidate the insertion anchor.

Use 0 to insert at the content start. Prefer appendFormula() for the current content end because it resolves the semantic 'end' position without requiring the caller to measure UTF-16 text length.

insertFormula(offset: number, formula: string, options?: IDocFormulaCreateFacadeOptions): FDocumentFormula | null

Parameters

• offset — Required. Zero-based UTF-16 offset relative to this paragraph's text.
• formula — Required. Formula text.
• options — Optional. Default: {}. Optional number format and stable external Source bindings.

Returns

The inserted formula, or null when the paragraph is missing, outside the main body, the offset is invalid, or Command validation fails.

Examples

Insert between a stable label and its suffix

import type { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/docs-formula/facade'export function insertFormulaInsideParagraph(univerAPI: FUniver) {  const document = univerAPI.getActiveDocument()  if (!document) throw new Error('No active document')  const paragraph = document.appendParagraph('Revenue: USD')  const paragraphId = paragraph.getId()  // This edit changes every following absolute document offset.  document.insertParagraph(0, 'Quarterly report')  const stableParagraph = document.getParagraph(paragraphId)  if (!stableParagraph) throw new Error('Revenue paragraph was removed')  const formula = stableParagraph.insertFormula('Revenue: '.length, '=1000/4', {    numberFormat: { pattern: '#,##0.00' },  })  if (!formula) throw new Error('Failed to insert Doc Formula')  return formula.describe()}

Types: FDocumentFormula · IDocFormulaCreateFacadeOptions

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

@univerjs-pro/docs-latex

FDocumentParagraph.appendLatex

Appends one inline LaTeX formula before this paragraph's trailing paragraph break.

The insert command generates and persists the underlying custom-range id. LaTeX source must not include $ or $$ delimiters.

appendLatex(latex: string, options?: IDocsLatexCreateFacadeOptions): FDocumentLatex | null

Parameters

• latex — Required. LaTeX source without delimiters.
• options — Optional. Default: {}. Optional visual properties.

Returns

The inserted formula, or null when the command fails.

Examples

const univerAPI = FUniver.newAPI(univer)const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active document')const paragraph = document.appendParagraph('Newton second law: ')const formula = paragraph.appendLatex('F = ma')if (!formula) throw new Error('Failed to append LaTeX formula')const description = formula.describe()if (!description || description.latex !== 'F = ma') {  throw new Error('LaTeX formula verification failed')}console.log(description)

Types: FDocumentLatex · IDocsLatexCreateFacadeOptions

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

FDocumentParagraph.prependLatex

Prepends one inline LaTeX formula at the start of this paragraph.

The insert command generates and persists the underlying custom-range id. LaTeX source must not include $ or $$ delimiters.

prependLatex(latex: string, options?: IDocsLatexCreateFacadeOptions): FDocumentLatex | null

Parameters

• latex — Required. LaTeX source without delimiters.
• options — Optional. Default: {}. Optional visual properties.

Returns

The inserted formula, or null when the command fails.

Examples

const univerAPI = FUniver.newAPI(univer)const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active document')const paragraph = document.appendParagraph(' is the energy equation.')const formula = paragraph.prependLatex('E = mc^2')if (!formula) throw new Error('Failed to prepend LaTeX formula')console.log(formula.describe())

Types: FDocumentLatex · IDocsLatexCreateFacadeOptions

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