FDocument

Facade API object bounded to a document. It provides a set of methods to interact with the document.

Access

Access through:

• FUniver.createDocument()
• FUniver.getActiveDocument()
• FUniver.getDocument()
• FCollaboration.loadDocAsync()

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

FDocument.appendParagraph

Append a plain-text paragraph at the end of the body.

appendParagraph(text?: string, segmentId?: string): FDocumentParagraph

Parameters

• text — Optional. Default: ''. The paragraph text. Defaults to an empty paragraph.
• segmentId — Optional. Default: ''. The segment id of the body. Defaults to an empty string for the main body.

Returns

The appended paragraph wrapper.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.appendParagraph('Summary')console.log(paragraph.getText())const footerSegmentId = fDocument.ensurePageFooter()const footerParagraph = fDocument.appendParagraph('Confidential', footerSegmentId)console.log(footerParagraph.getText())

Types: FDocumentParagraph

Package: @univerjs/docs · Type definitions

FDocument.deleteRange

Delete a range from the body.

deleteRange(range: IFDocumentTextRange): boolean

Parameters

• range — Required. The text range to delete.

Returns

true if the range was deleted.

Examples

const fDocument = univerAPI.getActiveDocument()fDocument.deleteRange({ startOffset: 0, endOffset: 5 })const headerSegmentId = fDocument.ensurePageHeader()fDocument.deleteRange({ startOffset: 0, endOffset: 5, segmentId: headerSegmentId })

Types: IFDocumentTextRange

Package: @univerjs/docs · Type definitions

FDocument.dispose

Releases this facade's resources. Use univerAPI.disposeUnit() to unload the owning unit.

dispose(): void

Package: @univerjs/docs · Type definitions

FDocument.ensurePageFooter

Ensure the page footer segment exists and return its segment id.

ensurePageFooter(pageIndex?: number): string

Parameters

• pageIndex — Optional. Default: 0. The zero-based page index. Defaults to the first page.

Returns

The footer segment id.

Examples

const fDocument = univerAPI.getActiveDocument()const footerSegmentId = fDocument.ensurePageFooter()fDocument.insertText(0, 'Footer text', footerSegmentId)

Package: @univerjs/docs · Type definitions

FDocument.ensurePageHeader

Ensure the page header segment exists and return its segment id.

ensurePageHeader(pageIndex?: number): string

Parameters

• pageIndex — Optional. Default: 0. The zero-based page index. Defaults to the first page.

Returns

The header segment id.

Examples

const fDocument = univerAPI.getActiveDocument()const headerSegmentId = fDocument.ensurePageHeader()fDocument.insertText(0, 'Header text', headerSegmentId)

Package: @univerjs/docs · Type definitions

FDocument.findParagraphByText

Find a paragraph by its text content and segment id.

findParagraphByText(text: string, segmentId?: string): FDocumentParagraph | null

Parameters

• text — Required. The text content to search for.
• segmentId — Optional. Default: ''. The segment id of the body. Defaults to an empty string for the main body.

Returns

The paragraph facade instance, or null if the paragraph is not found.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.findParagraphByText('Hello')console.log(paragraph)const footerSegmentId = fDocument.ensurePageFooter()const footerParagraph = fDocument.findParagraphByText('Page', footerSegmentId)console.log(footerParagraph)

Types: FDocumentParagraph

Package: @univerjs/docs · Type definitions

FDocument.findParagraphs

Find paragraphs by a query object, which can include text content, paragraph id, and segment id.

findParagraphs(query: string | IFDocumentParagraphQuery): FDocumentParagraph[]

Parameters

• query — Required. The query object or text content to search for.

Returns

An array of paragraph facade instances that match the query.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraphsWithText = fDocument.findParagraphs('Hello')console.log(paragraphsWithText)const paragraphsWithId = fDocument.findParagraphs({ paragraphId: 'paragraph-01' })console.log(paragraphsWithId)const headerSegmentId = fDocument.ensurePageHeader()const paragraphsWithSegment = fDocument.findParagraphs({ segmentId: headerSegmentId })console.log(paragraphsWithSegment)

Types: FDocumentParagraph · IFDocumentParagraphQuery

Package: @univerjs/docs · Type definitions

FDocument.getBody

Get the document body or header/footer body by the segment id. The main body has an empty segment id. The header and footer body have their respective segment ids.

getBody(segmentId?: string): IDocumentBody

Parameters

• segmentId — Optional. Default: ''. The segment id of the body. Defaults to an empty string for the main body.

Returns

The document body.

Examples

const fDocument = univerAPI.getActiveDocument()console.log(fDocument.getBody()) // Get the main bodyconst footerSegmentId = fDocument.ensurePageFooter()console.log(fDocument.getBody(footerSegmentId)) // Get the footer body

Types: IDocumentBody

Package: @univerjs/docs · Type definitions

FDocument.getCustomBlockLayout

Returns the document's custom blocks in stable model order.

This method is available in Node/headless environments and does not perform font measurement, line wrapping, pagination, or rendering.

getCustomBlockLayout(): IDocumentCustomBlockLayout

Returns

Custom block identifiers and model positions.

Examples

const document = univerAPI.getActiveDocument()const layout = document?.getCustomBlockLayout()console.log(layout?.blocks)

Types: IDocumentCustomBlockLayout

Package: @univerjs/docs · Type definitions

FDocument.getDocumentDataModel

Get the document data model of the document.

getDocumentDataModel(segmentId?: string): DocumentDataModel

Parameters

• segmentId — Optional. Default: ''. The segment id used to get the header/footer data model. Defaults to an empty string for the document data model of the document.

Returns

The document data model.

Examples

const fDocument = univerAPI.getActiveDocument()console.log(fDocument.getDocumentDataModel())const headerSegmentId = fDocument.ensurePageHeader()console.log(fDocument.getDocumentDataModel(headerSegmentId))

Types: DocumentDataModel

Package: @univerjs/docs · Type definitions

FDocument.getDocumentFlavor

Returns the document's explicit layout flavor.

Use this method when all three states matter. Do not infer a Traditional document from !isModern(): that expression is also true for DocumentFlavor.UNSPECIFIED.

getDocumentFlavor(): DocumentFlavor

Returns

TRADITIONAL, MODERN, or UNSPECIFIED.

Examples

const document = univerAPI.getActiveDocument()if (!document) {  throw new Error('No active document')}switch (document.getDocumentFlavor()) {  case univerAPI.Enum.DocumentFlavor.TRADITIONAL:    console.log('Word-compatible physical pagination is available')    break  case univerAPI.Enum.DocumentFlavor.MODERN:    console.log('Use Modern Doc layout APIs such as ColumnGroup')    break  default:    console.log('Resolve the unspecified flavor before using flavor-specific APIs')}

Types: DocumentFlavor

Package: @univerjs/docs · Type definitions

FDocument.getEntityPermission

Returns the permission facade for an entity with a stable id, such as a Table, Drawing, or Custom Block.

Parent Section and Paragraph permission ceilings are resolved from the current Document model.

getEntityPermission(segmentId: string, entityType: string, entityId: string): FDocumentObjectPermission

Parameters

• segmentId — Required. Segment id, or an empty string for the main body.
• entityType — Required. Stable entity type used by the owning Doc feature.
• entityId — Required. Stable entity id.

Returns

Effective permission facade for the entity.

Examples

Make one drawing read-only

const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active Document.')const snapshot = document.getDocumentDataModel().getSnapshot()const drawingId = snapshot.drawingsOrder?.[0]if (!drawingId) throw new Error('Drawing not found.')await document.getEntityPermission('', 'drawing', drawingId).setReadOnly()

Types: FDocumentObjectPermission

Package: @univerjs/docs · Type definitions

FDocument.getHeaderFooterOptions

Returns document-level header/footer switches and margins. Margin values use 96-DPI layout pixels.

getHeaderFooterOptions(): IHeaderFooterProps

Examples

const fDocument = univerAPI.getActiveDocument()console.log(fDocument?.getHeaderFooterOptions())

Types: IHeaderFooterProps

Package: @univerjs/docs · Type definitions

FDocument.getId

Get the document id.

getId(): string

Returns

The document id.

Examples

const fDocument = univerAPI.getActiveDocument()console.log(fDocument.getId())

Package: @univerjs/docs · Type definitions

FDocument.getName

Get the document name.

getName(): string

Returns

The document name.

Examples

const fDocument = univerAPI.getActiveDocument()console.log(fDocument.getName())

Package: @univerjs/docs · Type definitions

FDocument.getParagraph

Get a paragraph by its paragraph id and segment id.

getParagraph(paragraphId: string, segmentId?: string): FDocumentParagraph | null

Parameters

• paragraphId — Required. The paragraph id.
• segmentId — Optional. Default: ''. The segment id of the body. Defaults to an empty string for the main body.

Returns

The paragraph facade instance, or null if the paragraph is not found.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.getParagraph('paragraph-01')console.log(paragraph)const headerSegmentId = fDocument.ensurePageHeader()const headerParagraph = fDocument.getParagraph('header-paragraph-01', headerSegmentId)console.log(headerParagraph)

Types: FDocumentParagraph

Package: @univerjs/docs · Type definitions

FDocument.getParagraphs

Get all paragraphs in the document body or header/footer body by the segment id.

getParagraphs(segmentId?: string): FDocumentParagraph[]

Parameters

• segmentId — Optional. Default: ''. The segment id of the body. Defaults to an empty string for the main body.

Returns

An array of paragraph facade instances.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraphs = fDocument.getParagraphs()console.log(paragraphs)const headerSegmentId = fDocument.ensurePageHeader()const headerParagraphs = fDocument.getParagraphs(headerSegmentId)console.log(headerParagraphs)

Types: FDocumentParagraph

Package: @univerjs/docs · Type definitions

FDocument.getPermission

Returns the Document unit permission facade.

getPermission(): FDocumentPermission

Returns

Permission facade for Edit, Copy, Print, Export, and Comment.

Examples

const document = univerAPI.getActiveDocument()if (!document) throw new Error('No active Document.')await document.getPermission().setReadOnly()

Types: FDocumentPermission

Package: @univerjs/docs · Type definitions

FDocument.getSection

Returns a traditional section by zero-based index, or null in modern documents.

getSection(index: number): FDocumentSection | null

Parameters

• index — Required. Zero-based section index.

Returns

The matching section, or null if none exists or the document is not Traditional.

Examples

const fDocument = univerAPI.getActiveDocument()const firstSection = fDocument?.getSection(0)console.log(firstSection?.describe())

Types: FDocumentSection

Package: @univerjs/docs · Type definitions

FDocument.getSectionAt

Returns the traditional section containing a data-stream offset, or null in modern documents.

getSectionAt(offset: number): FDocumentSection | null

Parameters

• offset — Required. Zero-based data-stream offset in the main document body.

Returns

The matching section, or null if none exists or the document is not Traditional.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument?.findParagraphByText('Launch')const offset = paragraph?.getInfo().startOffsetconst section = offset == null ? null : fDocument?.getSectionAt(offset)console.log(section?.getId())

Types: FDocumentSection

Package: @univerjs/docs · Type definitions

FDocument.getSections

Returns traditional document sections backed by persisted SectionBreak ids. Modern documents use ColumnGroup instead and return an empty array from this read API.

getSections(): FDocumentSection[]

Examples

const fDocument = univerAPI.getActiveDocument()const sections = fDocument?.getSections() ?? []console.log(sections.map((section) => section.describe()))

Types: FDocumentSection

Package: @univerjs/docs · Type definitions

FDocument.getTextRange

Creates a facade for reading and styling a document text range. The end offset is exclusive, and offsets are scoped to the selected body segment.

getTextRange(startOffset: number, endOffset: number, segmentId?: string): FDocumentTextRange

Parameters

• startOffset — Required. The inclusive start offset.
• endOffset — Required. The exclusive end offset.
• segmentId — Optional. Default: ''. The header/footer segment id, or an empty string for the main body.

Returns

A fixed text-range facade.

Examples

const range = univerAPI.getActiveDocument()?.getTextRange(0, 5)console.log(range?.describe())range?.setTextStyle({ bl: 1 })

Types: FDocumentTextRange

Package: @univerjs/docs · Type definitions

FDocument.id

The document unit id used to identify this document in commands and snapshots.

readonly id: string

Package: @univerjs/docs · Type definitions

FDocument.insertColumnBreak

Inserts a column-break token in a traditional document. In a single-column section, the traditional renderer advances to the next physical page. Modern documents must use ColumnGroup. Unspecified documents must resolve their flavor first. Both throw DocsSectionUnsupportedDocumentFlavorError.

insertColumnBreak(offset: number): boolean

Parameters

• offset — Required. Zero-based data-stream offset at which to insert the column break.

Returns

Whether the insertion succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()if (fDocument?.isTraditional()) {  const paragraph = fDocument.findParagraphByText('Continue in next column')  const offset = paragraph?.getInfo().startOffset  if (offset != null) {    fDocument.insertColumnBreak(offset)  }}

Package: @univerjs/docs · Type definitions

FDocument.insertHorizontalRule

Inserts a horizontal rule using the existing paragraph borderBottom mechanism. The returned paragraph can be inspected or removed with normal paragraph APIs. Border width and padding are in points (pt).

insertHorizontalRule(offset: number, border?: IParagraphBorder, segmentId?: string): FDocumentParagraph | null

Parameters

• offset — Required. Zero-based insertion offset in the selected body segment.
• border — Optional. Default: { padding: 5, color: { rgb: '#CDD0D8' }, width: 1, dashStyle: DashStyleType.SOLID, }. Bottom border appearance. Defaults to a solid gray 1 pt line with 5 pt padding.
• segmentId — Optional. Default: ''. Header/footer segment ID, or an empty string for the main body (default).

Returns

The inserted paragraph, or null if insertion fails.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument?.findParagraphByText('Summary')const offset = paragraph?.getInfo().startOffsetconst rule = offset == null ? null : fDocument?.insertHorizontalRule(offset)console.log(rule?.getId())

Types: FDocumentParagraph · IParagraphBorder

Package: @univerjs/docs · Type definitions

FDocument.insertParagraph

Insert a plain-text paragraph before the paragraph at the given paragraph index.

insertParagraph(index: number, text?: string, segmentId?: string): FDocumentParagraph

Parameters

• index — Required. The zero-based paragraph insertion index.
• text — Optional. Default: ''. The paragraph text. Defaults to an empty paragraph.
• segmentId — Optional. Default: ''. The segment id of the body. Defaults to an empty string for the main body.

Returns

The inserted paragraph facade instance.

Examples

const fDocument = univerAPI.getActiveDocument()const paragraph = fDocument.insertParagraph(0, 'Document title')paragraph.appendText(' suffix')const headerSegmentId = fDocument.ensurePageHeader()const headerParagraph = fDocument.insertParagraph(0, 'Header title', headerSegmentId)headerParagraph.appendText(' suffix')

Types: FDocumentParagraph

Package: @univerjs/docs · Type definitions

FDocument.insertSectionBreak

Inserts a traditional document section break and returns its stable facade.

options configures the section created before the inserted break. Set options.nextSectionType to control how the existing section after the break begins. For example, use SectionType.NEXT_PAGE to start a chapter on a new physical page. Both changes are executed by one command and are undone or redone together.

The offset must be a top-level document position. To insert a break before a table or block such as a callout, use that object's start offset instead of an offset inside the object.

Modern documents must use ColumnGroup. Unspecified documents must resolve their flavor first. Both throw DocsSectionUnsupportedDocumentFlavorError. Numeric layout values in options are in 96-DPI layout pixels.

insertSectionBreak(offset: number, options?: IFDocumentInsertSectionBreakOptions): FDocumentSection | null

Parameters

• offset — Required. Top-level data-stream offset where the section break is inserted.
• options — Optional. Default: {}. Section properties and the optional type of the following section.

Returns

The section created before the break, or null when the command rejects the insertion.

Examples

const document = univerAPI.getActiveDocument()if (!document) {  throw new Error('No active document')}if (!document.isTraditional()) {  throw new Error('Traditional document sections are required')}const chapter = document.findParagraphByText('Chapter 2')if (!chapter) {  throw new Error('Chapter heading not found')}// Insert the boundary immediately before the chapter heading. The command// also marks the following section as NEXT_PAGE, so the two model changes// share one undo/redo step.const sectionBeforeChapter = document.insertSectionBreak(chapter.getInfo().startOffset, {  nextSectionType: univerAPI.Enum.SectionType.NEXT_PAGE,})if (!sectionBeforeChapter) {  throw new Error('The chapter heading is not at a valid top-level offset')}console.log({  insertedSection: sectionBeforeChapter.describe(),  chapterSection: document.getSectionAt(chapter.getInfo().startOffset)?.describe(),})

Types: FDocumentSection · IFDocumentInsertSectionBreakOptions

Package: @univerjs/docs · Type definitions

FDocument.insertText

Insert plain text at a document body offset.

insertText(index: number, text: string, segmentId?: string): boolean

Parameters

• index — Required. The zero-based insertion offset.
• text — Required. The plain text to insert.
• segmentId — Optional. Default: ''. The segment id of the body. Defaults to an empty string for the main body.

Returns

true if the edit was applied.

Examples

const fDocument = univerAPI.getActiveDocument()fDocument.insertText(0, 'Hello ')const headerSegmentId = fDocument.ensurePageHeader()fDocument.insertText(0, 'Header text', headerSegmentId)

Package: @univerjs/docs · Type definitions

FDocument.isModern

Whether this is a Modern document.

A false result can mean either Traditional or Unspecified. Use isTraditional() before Traditional-only APIs, or getDocumentFlavor() when all three states matter.

isModern(): boolean

Returns

true only for DocumentFlavor.MODERN.

Examples

const fDocument = univerAPI.getActiveDocument()console.log(fDocument?.isModern())

Package: @univerjs/docs · Type definitions

FDocument.isTraditional

Whether this is a Traditional document with Word-compatible physical pagination.

Prefer this positive guard before calling section, column-break, page-setup, or paragraph-pagination APIs.

isTraditional(): boolean

Returns

true only for DocumentFlavor.TRADITIONAL.

Examples

const document = univerAPI.getActiveDocument()if (document?.isTraditional()) {  console.log(document.getSection(0)?.getEffectivePageSetup())}

Package: @univerjs/docs · Type definitions

FDocument.redo

Redo the last undone operation in the document.

redo(): boolean

Returns

true if the redo operation was successful, or false if it failed.

Examples

const fDocument = univerAPI.getActiveDocument()const success = fDocument.redo()console.log(success)

Package: @univerjs/docs · Type definitions

FDocument.save

Save the document snapshot data, including the document content and resource data, etc.

save(): IDocumentData

Returns

The document snapshot data.

Examples

const fDocument = univerAPI.getActiveDocument()const snapshot = fDocument.save()console.log(snapshot)

Types: IDocumentData

Package: @univerjs/docs · Type definitions

FDocument.setHeaderFooterOptions

Updates document-level header/footer switches and margins.

Traditional and Unspecified documents keep the legacy header/footer behavior. Modern documents reject this API. marginHeader and marginFooter use 96-DPI layout pixels.

setHeaderFooterOptions(options: IHeaderFooterProps): boolean

Parameters

• options — Required. Header/footer switches and margins to update. Omitted properties are preserved.

Returns

Whether the update command succeeded.

Examples

const fDocument = univerAPI.getActiveDocument()if (fDocument && fDocument.getDocumentFlavor() !== univerAPI.Enum.DocumentFlavor.MODERN) {  fDocument.setHeaderFooterOptions({ marginHeader: 36, marginFooter: 36 })}

Types: IHeaderFooterProps

Package: @univerjs/docs · Type definitions

FDocument.setName

Set the document name.

setName(name: string): this

Parameters

• name — Required. The new document name.

Returns

The current document for chaining.

Examples

const document = univerAPI.getActiveDocument()document?.setName('Quarterly Report')

Package: @univerjs/docs · Type definitions

FDocument.undo

Undo the last operation in the document.

undo(): boolean

Returns

true if the undo operation was successful, or false if it failed.

Examples

const fDocument = univerAPI.getActiveDocument()const success = fDocument.undo()console.log(success)

Package: @univerjs/docs · Type definitions

@univerjs/docs-drawing

FDocument.getImage

Gets an image by its drawing id.

getImage(imageId: string): FDocumentImage | null

Parameters

• imageId — Required. The drawing id of the image.

Returns

The image facade, or null when the image does not exist.

Examples

const fDocument = univerAPI.getActiveDocument()const image = fDocument.getImage('image-1')console.log(image)

Types: FDocumentImage

Package: @univerjs/docs-drawing · Type definitions

FDocument.getImages

Gets all images in the document in drawing order.

getImages(): FDocumentImage[]

Returns

The image facades in drawing order.

Examples

const fDocument = univerAPI.getActiveDocument()const images = fDocument.getImages()console.log(images)

Types: FDocumentImage

Package: @univerjs/docs-drawing · Type definitions

FDocument.insertImage

Inserts an image into the document.

When width and height are both omitted, the intrinsic size is proportionally limited to 500 by 500 pixels. For ordinary content, prefer INLINE, WRAP_SQUARE, or WRAP_TOP_AND_BOTTOM. Use BEHIND_TEXT for backgrounds or watermarks and IN_FRONT_OF_TEXT only for intentional overlays, because these two styles do not cause text to reflow.

insertImage(options: IFDocumentInsertImageOptions): Promise<FDocumentImage | null>

Parameters

• options — Required. The image source, optional transform, and insertion range.

Returns

The inserted image facade, or null when the insertion command fails.

Examples

const fDocument = univerAPI.getActiveDocument()const image = await fDocument.insertImage({  source: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',  imageSourceType: univerAPI.Enum.ImageSourceType.URL,  width: 320,  // Keep the image in the text flow so it cannot cover surrounding text.  wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,  textRange: {    startOffset: 30,  },})console.log(image)

const fDocument = univerAPI.getActiveDocument()const image = await fDocument.insertImage({  source: 'https://avatars.githubusercontent.com/u/61444807?s=48&v=4',  imageSourceType: univerAPI.Enum.ImageSourceType.URL,  width: 320,  // Float the image and let body text flow beside its rectangular bounds.  wrappingStyle: univerAPI.Enum.TextWrappingStyle.WRAP_SQUARE,  textRange: {    startOffset: 30,  },})console.log(image)

Types: FDocumentImage · Promise · IFDocumentInsertImageOptions

Package: @univerjs/docs-drawing · Type definitions

@univerjs/docs-ui

FDocument.setSelection

Sets the selection to a specified text range in the document. A computed offscreen target is selected after its render data is loaded. A newer pointer/selection action or changed text supersedes that request.

setSelection(startOffset: number, endOffset: number): void

Parameters

• startOffset — Required. The starting offset of the selection in the document.
• endOffset — Required. The ending offset of the selection in the document.

Examples

const fDocument = univerAPI.getActiveDocument()fDocument.setSelection(10, 20)

Package: @univerjs/docs-ui · Type definitions

@univerjs-pro/docs-callout

FDocument.findCalloutByText

Finds the first callout whose text contains the given string.

findCalloutByText(text: string): FDocumentCallout | null

Parameters

• text — Required. Text to search inside callout content.

Returns

The first matching FDocumentCallout instance, or null if no match is found.

Examples

const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('important')console.log(callout)

Types: FDocumentCallout

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

FDocument.findCallouts

Finds callouts by text or block id.

findCallouts(query: string | IDocsCalloutFindQuery): FDocumentCallout[]

Parameters

• query — Required. A plain text query or a structured callout query.

Returns

An array of matching FDocumentCallout instances, or an empty array if no match is found.

Examples

const fDocument = univerAPI.getActiveDocument()const calloutsWithText = fDocument.findCallouts('important')const calloutsWithId = fDocument.findCallouts({ blockId: 'block-id-123' })console.log(calloutsWithText, calloutsWithId)

Types: FDocumentCallout · IDocsCalloutFindQuery

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

FDocument.getCallout

Returns a callout block range by its block id.

getCallout(blockId: string): FDocumentCallout | null

Parameters

• blockId — Required. The callout block range id.

Returns

The FDocumentCallout instance, or null if no callout block range with the id exists in the document.

Examples

const fDocument = univerAPI.getActiveDocument()const callout = fDocument.getCallout('block-id-123')console.log(callout)

Types: FDocumentCallout

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

FDocument.getCalloutAt

Returns the callout block range that contains a document data stream offset.

getCalloutAt(offset: number): FDocumentCallout | null

Parameters

• offset — Required. The document data stream offset.

Returns

The FDocumentCallout instance, or null if no callout block range contains the offset.

Examples

const fDocument = univerAPI.getActiveDocument()const callout = fDocument.getCalloutAt(150)console.log(callout)

Types: FDocumentCallout

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

FDocument.getCallouts

Returns all callout block ranges in this document.

getCallouts(): FDocumentCallout[]

Returns

An array of FDocumentCallout instances, or an empty array if no callout block ranges exist in the document.

Examples

const fDocument = univerAPI.getActiveDocument()const callouts = fDocument.getCallouts()console.log(callouts)

Types: FDocumentCallout

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

FDocument.insertCallout

Inserts a callout around a paragraph element. The paragraph wrapper is resolved by persisted paragraphId before the command runs, so facade edits inserted before the paragraph do not require recalculating offsets.

This API writes keepLines and widowControl to every inserted paragraph. For multiple paragraphs it also writes keepNext = TRUE between adjacent paragraphs and keepNext = FALSE on the final paragraph, so the callout does not capture the following body paragraph. Callers do not need to add these pagination styles manually.

Traditional Docs apply the styles during physical pagination. A callout that fits on a fresh page stays together; content taller than a fresh page remains splittable. Modern and Unspecified Docs preserve the styles in the model but do not apply them during physical pagination.

insertCallout(paragraph: FDocumentParagraph, options?: IDocsCalloutInsertParagraphFacadeOptions): FDocumentCallout | nullinsertCallout(options?: IDocsCalloutInsertFacadeOptions): FDocumentCallout | null

Parameters

• paragraph — Optional. The paragraph to convert to a callout.
• options — Optional. Optional block id and visual config.

Returns

The inserted FDocumentCallout instance, or null if the insert callout failed.

Examples

const fDocument = univerAPI.getActiveDocument()if (!fDocument) {  throw new Error('No active document')}// Insert a callout around a paragraph with the icon config.const paragraph = fDocument.appendParagraph('Remember to review the launch checklist.')const callout = fDocument.insertCallout(paragraph, {  config: { icon: '!' },})if (!callout) {  throw new Error('Failed to insert the callout')}console.log({  blockId: callout.getId(),  wordPaginationApplied: fDocument.isTraditional(),})

const fDocument = univerAPI.getActiveDocument()if (!fDocument) {  throw new Error('No active document')}// Insert a callout around the text 'Risk' in a table cell with the icon config.const table = fDocument.findTableByText('Risk')const range = table?.getCell(1, 0)?.getContentRange()if (!range) {  throw new Error('Risk table cell not found')}const callout = fDocument.insertCallout({ ...range, config: { icon: '!' } })if (!callout) {  throw new Error('Failed to insert the table-cell callout')}console.log(callout.getId())// Insert a callout around the text 'Callout' and next paragraph with the icon config.const paragraph = fDocument.findParagraphByText('Callout')if (paragraph) {  const paragraphs = fDocument.getParagraphs()  const { paragraphIndex, startOffset } = paragraph.getInfo()  const finalParagraph = paragraphs[paragraphIndex + 1]  if (!finalParagraph) {    throw new Error('Expected a paragraph after the callout start')  }  const { endOffset } = finalParagraph.getInfo()  const callout2 = fDocument.insertCallout({ startOffset, endOffset, config: { icon: '!' } })  if (!callout2) {    throw new Error('Failed to insert the multi-paragraph callout')  }  console.log(callout2.getId())}

Types: FDocumentCallout · FDocumentParagraph · IDocsCalloutInsertParagraphFacadeOptions · IDocsCalloutInsertFacadeOptions

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

@univerjs-pro/docs-chart

FDocument.getChart

Returns a Document Chart by its Chart resource id or drawing id.

getChart(chartIdOrDrawingId: string): FDocumentChart | null

Parameters

• chartIdOrDrawingId — Required. A Chart resource id or Document drawing id.

Returns

The live Document Chart facade, or null if it does not exist.

Examples

const fDocument = univerAPI.getActiveDocument()const fChart = fDocument.getChart('chartIdOrDrawingId')console.log(fChart?.getInfo())

Types: FDocumentChart

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

FDocument.getCharts

Returns all Charts in this Document.

getCharts(): FDocumentChart[]

Returns

Live Chart facades in Document drawing order.

Examples

const fDocument = univerAPI.getActiveDocument()const fCharts = fDocument.getCharts()fCharts.forEach((fChart) => {  console.log(fChart.getId(), fChart.getDrawingId(), fChart.getInfo())})

Types: FDocumentChart

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

FDocument.insertChart

Inserts a Chart into this Document from detached Chart information.

insertChart(info: IDocumentChartInfo): Promise<FDocumentChart>

Parameters

• info — Required. The configuration, data source, and layout produced by a Document Chart Builder.

Returns

A live facade for the inserted Document Chart.

Throws

If the data source, insertion anchor, layout, or command is invalid.

Examples

const fDocument = univerAPI.getActiveDocument()const chartInfo = fDocument  .newChart(univerAPI.Enum.ChartTypeString.Column)  .setSource([    ['Quarter', 'Sales'],    ['Q1', 120],    ['Q2', 180],  ])  .setPosition({    kind: univerAPI.Enum.DocsChartInsertAnchorKind.BodyOffset,    offset: 0,  })  .setInline()  .setSize(640, 360)  .build()const fChart = await fDocument.insertChart(chartInfo)fChart.setTitle('Quarterly sales')

Types: FDocumentChart · Promise · IDocumentChartInfo

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

FDocument.newChart

Creates a detached, type-specific Chart Builder for this Document.

newChart<T extends ChartTypeString>(type: T): FDocumentChartBuilderOf<T>

Parameters

• type — Required. The Chart type to create.

Returns

A detached Builder that produces insertable Document Chart information.

Examples

const fDocument = univerAPI.getActiveDocument()if (!fDocument) throw new Error('No active document.')const chartInfo = fDocument  .newChart(univerAPI.Enum.ChartTypeString.Line)  .setSource([    ['Month', 'Sales'],    ['Jan', 120],    ['Feb', 180],    ['Mar', 160],  ])  .setFloating()  .setAbsolutePosition(120, 80)  .setSize(640, 360)  .setTitle('Monthly sales')  .setLineStyle({ width: 2 })  .build()const fChart = await fDocument.insertChart(chartInfo)console.log(fChart.getId(), fChart.getDrawingId())

Types: FDocumentChartBuilderOf

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

@univerjs-pro/docs-code

FDocument.findCodeByText

Finds the first code whose text contains the given string.

findCodeByText(text: string): FDocumentCode | null

Parameters

• text — Required. Text to search inside code content.

Returns

The first matching FDocumentCode instance, or null if no match is found.

Examples

const fDocument = univerAPI.getActiveDocument()const code = fDocument.findCodeByText('function')console.log(code)

Types: FDocumentCode

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

FDocument.findCodes

Finds codes by text or block id.

findCodes(query: string | IDocsCodeFindQuery): FDocumentCode[]

Parameters

• query — Required. A plain text query or a structured code query.

Returns

An array of matching FDocumentCode instances, or an empty array if no match is found.

Examples

const fDocument = univerAPI.getActiveDocument()const codesWithText = fDocument.findCodes('function')const codesWithId = fDocument.findCodes({ blockId: 'block-id-123' })console.log(codesWithText, codesWithId)

Types: FDocumentCode · IDocsCodeFindQuery

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

FDocument.getCode

Returns a code block range by its block id.

getCode(blockId: string): FDocumentCode | null

Parameters

• blockId — Required. The code block range id.

Returns

The FDocumentCode instance, or null if no code block range with the id exists in the document.

Examples

const fDocument = univerAPI.getActiveDocument()const code = fDocument.getCode('block-id-123')console.log(code)

Types: FDocumentCode

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

FDocument.getCodeAt

Returns the code that contains a document data stream offset.

getCodeAt(offset: number): FDocumentCode | null

Parameters

• offset — Required. The document data stream offset.

Returns

The FDocumentCode instance, or null if no code block range contains the offset.

Examples

const fDocument = univerAPI.getActiveDocument()const code = fDocument.getCodeAt(150)console.log(code)

Types: FDocumentCode

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

FDocument.getCodes

Returns all code block ranges in this document.

getCodes(): FDocumentCode[]

Returns

An array of FDocumentCode instances, or an empty array if no code block ranges exist in the document.

Examples

const fDocument = univerAPI.getActiveDocument()const codes = fDocument.getCodes()console.log(codes)

Types: FDocumentCode

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

FDocument.insertCode

Inserts a code block around a paragraph element. The paragraph wrapper is resolved by persisted paragraphId before the command runs, so facade edits inserted before the paragraph do not require recalculating offsets.

This API writes keepLines and widowControl to every inserted paragraph. For multiple paragraphs it also writes keepNext = TRUE between adjacent paragraphs and keepNext = FALSE on the final paragraph, so the code block does not capture the following body paragraph. Callers do not need to add these pagination styles manually.

Traditional Docs apply the styles during physical pagination. A code block that fits on a fresh page stays together; content taller than a fresh page remains splittable. Modern and Unspecified Docs preserve the styles in the model but do not apply them during physical pagination.

insertCode(paragraph: FDocumentParagraph, options?: IDocsCodeInsertParagraphFacadeOptions): FDocumentCode | nullinsertCode(options?: IDocsCodeInsertFacadeOptions): FDocumentCode | null

Parameters

• paragraph — Optional. The paragraph to convert to a code block.
• options — Optional. Optional block id and code config.

Returns

The newly inserted FDocumentCode instance, or null if the insert code failed.

Examples

const fDocument = univerAPI.getActiveDocument()if (!fDocument) {  throw new Error('No active document')}// Insert a code block around a paragraph with TypeScript language config.const paragraph = fDocument.appendParagraph('const total = rows.length;')const code = fDocument.insertCode(paragraph, {  config: { language: 'typescript' },})if (!code) {  throw new Error('Failed to insert the code block')}console.log({  language: code.getConfig()?.language,  wordPaginationApplied: fDocument.isTraditional(),})

const fDocument = univerAPI.getActiveDocument()if (!fDocument) {  throw new Error('No active document')}// Insert a code block around the text "Snippet" in a table cell with TypeScript language config.const table = fDocument.findTableByText('Snippet')const range = table?.getCell(1, 0)?.getContentRange()if (!range) {  throw new Error('Snippet table cell not found')}const code = fDocument.insertCode({ ...range, config: { language: 'typescript' } })if (!code) {  throw new Error('Failed to insert the table-cell code block')}console.log(code.getId())// Insert a code block around the text "const" and the next three paragraphs with TypeScript language config.// const cell = {//   width: 960,//   blocks: ['code', 'callout', 'quote']// };const paragraph = fDocument.findParagraphByText('const')if (paragraph) {  const paragraphs = fDocument.getParagraphs()  const { paragraphIndex, startOffset } = paragraph.getInfo()  const finalParagraph = paragraphs[paragraphIndex + 3]  if (!finalParagraph) {    throw new Error('Expected three paragraphs after the code start')  }  const { endOffset } = finalParagraph.getInfo()  const code2 = fDocument.insertCode({ startOffset, endOffset, config: { language: 'typescript' } })  if (!code2) {    throw new Error('Failed to insert the multi-paragraph code block')  }  console.log(code2.getId())}

Types: FDocumentCode · FDocumentParagraph · IDocsCodeInsertParagraphFacadeOptions · IDocsCodeInsertFacadeOptions

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

@univerjs-pro/docs-column

FDocument.findColumnGroupByText

Finds the first column group that contains a column with matching text.

findColumnGroupByText(text: string): FDocumentColumnGroup | null

Parameters

• text — Required. Plain text to search inside columns.

Returns

The first matching column group, or null when no group contains the text.

Examples

const fDocument = univerAPI.getActiveDocument()const group = fDocument.findColumnGroupByText('Launch')console.log(group?.describe())

Types: FDocumentColumnGroup

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

FDocument.findColumnGroups

Finds column groups by text or by id.

findColumnGroups(query: string | IDocsColumnFindQuery): FDocumentColumnGroup[]

Parameters

• query — Required. Plain text to search inside columns, or a structured query.

Returns

Matching column groups in document order.

Examples

const fDocument = univerAPI.getActiveDocument()const groupsWithText = fDocument.findColumnGroups('Launch')const groupsWithId = fDocument.findColumnGroups({ columnGroupId: 'column-group-1' })console.log(groupsWithText, groupsWithId)

Types: FDocumentColumnGroup · IDocsColumnFindQuery

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

FDocument.getColumnGroup

Returns a column group by id.

getColumnGroup(columnGroupId: string): FDocumentColumnGroup | null

Parameters

• columnGroupId — Required. The column group id stored in body.columnGroups.

Returns

The column group wrapper, or null if no group has the id.

Examples

const fDocument = univerAPI.getActiveDocument()const group = fDocument.getColumnGroup('column-group-1')console.log(group?.describe())

Types: FDocumentColumnGroup

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

FDocument.getColumnGroupAt

Returns the column group that contains a data-stream offset.

getColumnGroupAt(offset: number): FDocumentColumnGroup | null

Parameters

• offset — Required. Zero-based document body data-stream offset.

Returns

The containing column group, or null when the offset is outside all groups.

Examples

const fDocument = univerAPI.getActiveDocument()const group = fDocument.getColumnGroupAt(128)console.log(group?.describe())

Types: FDocumentColumnGroup

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

FDocument.getColumnGroups

Returns all column groups in this document.

getColumnGroups(): FDocumentColumnGroup[]

Returns

Column group wrappers, or an empty array when the document has no column groups.

Examples

const fDocument = univerAPI.getActiveDocument()const groups = fDocument.getColumnGroups()console.log(groups.map((group) => group.describe()))

Types: FDocumentColumnGroup

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

FDocument.insertColumnGroup

Inserts an empty column group into the document.

By default the group is inserted before the final body section break. Pass offset when you need to insert at a specific data-stream position. Every inserted column contains an editable empty paragraph. Column groups are supported only in modern documents; traditional documents throw DocsColumnUnsupportedDocumentFlavorError.

insertColumnGroup(columnCount: number, options?: IDocsColumnInsertFacadeOptions): FDocumentColumnGroup | null

Parameters

• columnCount — Required. Number of columns to create. Values below two are normalized to two; values above five fail.
• options — Optional. Default: {}. Optional id, column ids, insertion offset, gap, and initial width ratios.

Returns

The inserted column group wrapper, or null if insertion failed.

Examples

const fDocument = univerAPI.getActiveDocument()const group = fDocument.insertColumnGroup(3, {  gap: 18,  widthRatios: [1.1, 1, 0.9],})const [left, middle, right] = group?.getColumns() ?? []const leftOffset = left?.getInsertOffset()if (leftOffset != null) {  fDocument.insertText(leftOffset, 'Editorial brief\rUse columns for compact narrative layout.')}const middleOffset = middle?.getInsertOffset()if (middleOffset != null) {  fDocument.insertText(middleOffset, 'Production checklist\rDrag content into this column.')}const rightOffset = right?.getInsertOffset()if (rightOffset != null) {  fDocument.insertTableFromData(    [      ['Metric', 'Now', 'Next'],      ['Adoption', '68%', '80%'],      ['Quality', 'A-', 'A'],    ],    {      offset: rightOffset,      headerRowCount: 1,    },  )}console.log(group?.describe())

Types: FDocumentColumnGroup · IDocsColumnInsertFacadeOptions

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

@univerjs-pro/docs-formula

FDocument.getFormula

Resolves one complete Doc Formula by stable rangeId.

getFormula(rangeId: string): FDocumentFormula | null

Parameters

• rangeId — Required. Identity returned by insertion or FDocumentFormula.getId.

Returns

A handle, or null when either the range or Resource entry is absent.

Examples

import type { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/docs-formula/facade'export function getDocFormula(univerAPI: FUniver, rangeId: string) {  const document = univerAPI.getActiveDocument()  if (!document) throw new Error('No active document')  const formula = document.getFormula(rangeId)  if (!formula) throw new Error(`Doc Formula ${rangeId} was not found`)  return formula}

Types: FDocumentFormula

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

FDocument.getFormulaAt

Resolves the whole-entity Doc Formula containing a main-body offset.

getFormulaAt(offset: number): FDocumentFormula | null

Parameters

• offset — Required. Document data-stream offset.

Returns

A handle, or null when the offset is not a complete Doc Formula.

Examples

import type { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/docs-formula/facade'export function getDocFormulaAt(univerAPI: FUniver, offset: number) {  const document = univerAPI.getActiveDocument()  if (!document) throw new Error('No active document')  return document.getFormulaAt(offset)}

Types: FDocumentFormula

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

FDocument.getFormulas

Lists complete Formula custom-range/Resource pairs in the main body.

Incomplete or unsupported persisted data remains preserved by the core plugin but is intentionally omitted from calculation and this list.

getFormulas(): FDocumentFormula[]

Returns

Formula handles in document order, or an empty array.

Examples

import type { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/docs-formula/facade'export function listDocFormulas(univerAPI: FUniver) {  const document = univerAPI.getActiveDocument()  if (!document) throw new Error('No active document')  return document.getFormulas().map((formula) => formula.describe())}

Types: FDocumentFormula

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

FDocument.insertFormula

Replaces an explicit main-body range with one inline Doc Formula.

The offsets are snapshot-relative and resolved immediately. This API is suitable when the caller already owns a current range in the same synchronous workflow. Agent and delayed headless workflows should prefer a stable FDocumentParagraph handle with insertFormula() or appendFormula().