# FDocument

> Language fallback: requested `ko-KR`; content is `en-US`.

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

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

- Requested language: `ko-KR`

- Content language: `en-US`

- Documentation version: `1.0.4`

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

---

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

## Access

Access through:

* [`FUniver.createDocument()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#createdocument)
* [`FUniver.getActiveDocument()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getactivedocument)
* [`FUniver.getDocument()`](https://docs.univer.ai/ko-KR/reference/facade/univer.md#getdocument)
* [`FCollaboration.loadDocAsync()`](https://docs.univer.ai/ko-KR/reference/facade/collaboration.md#loaddocasync)

## Setup

Register [`@univerjs/docs`](https://docs.univer.ai/ko-KR/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/ko-KR/guides/docs/getting-started/facade.md).

## `@univerjs/docs`

### `FDocument.appendParagraph`

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

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md)

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

### `FDocument.deleteRange`

Delete a range from the body.

```typescript
deleteRange(range: IFDocumentTextRange): boolean
```

**Parameters**

* `range` — Required. The text range to delete.

**Returns**

`true` if the range was deleted.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
fDocument.deleteRange({ startOffset: 0, endOffset: 5 })

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

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

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

### `FDocument.dispose`

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

```typescript
dispose(): void
```

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

### `FDocument.ensurePageFooter`

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

```typescript
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**

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

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

### `FDocument.ensurePageHeader`

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

```typescript
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**

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

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

### `FDocument.findParagraphByText`

Find a paragraph by its text content and segment id.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md)

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

### `FDocument.findParagraphs`

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

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`IFDocumentParagraphQuery`](https://unpkg.com/@univerjs/docs/lib/types/facade/f-document.d.ts)

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

### `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.

```typescript
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**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument.getBody()) // Get the main body

const footerSegmentId = fDocument.ensurePageFooter()
console.log(fDocument.getBody(footerSegmentId)) // Get the footer body
```

**Types:** [`IDocumentBody`](https://docs.univer.ai/ko-KR/reference/types/document-body.md)

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

### `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.

```typescript
getCustomBlockLayout(): IDocumentCustomBlockLayout
```

**Returns**

Custom block identifiers and model positions.

**Examples**

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

**Types:** [`IDocumentCustomBlockLayout`](https://unpkg.com/@univerjs/docs/lib/types/facade/f-document.d.ts)

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

### `FDocument.getDocumentDataModel`

Get the document data model of the document.

```typescript
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**

```ts
const fDocument = univerAPI.getActiveDocument()
console.log(fDocument.getDocumentDataModel())

const headerSegmentId = fDocument.ensurePageHeader()
console.log(fDocument.getDocumentDataModel(headerSegmentId))
```

**Types:** [`DocumentDataModel`](https://unpkg.com/@univerjs/core/lib/types/docs/data-model/document-data-model.d.ts)

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

### `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`.

```typescript
getDocumentFlavor(): DocumentFlavor
```

**Returns**

`TRADITIONAL`, `MODERN`, or `UNSPECIFIED`.

**Examples**

```ts
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`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `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.

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

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-object-permission.md)

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

### `FDocument.getHeaderFooterOptions`

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

```typescript
getHeaderFooterOptions(): IHeaderFooterProps
```

**Examples**

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

**Types:** [`IHeaderFooterProps`](https://unpkg.com/@univerjs/docs/lib/types/commands/commands/create-header-footer.command.d.ts)

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

### `FDocument.getId`

Get the document id.

```typescript
getId(): string
```

**Returns**

The document id.

**Examples**

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

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

### `FDocument.getName`

Get the document name.

```typescript
getName(): string
```

**Returns**

The document name.

**Examples**

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

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

### `FDocument.getParagraph`

Get a paragraph by its paragraph id and segment id.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md)

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

### `FDocument.getParagraphs`

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

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md)

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

### `FDocument.getPermission`

Returns the Document unit permission facade.

```typescript
getPermission(): FDocumentPermission
```

**Returns**

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

**Examples**

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

**Types:** [`FDocumentPermission`](https://docs.univer.ai/ko-KR/reference/facade/document-permission.md)

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

### `FDocument.getSection`

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

```typescript
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**

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

**Types:** [`FDocumentSection`](https://docs.univer.ai/ko-KR/reference/facade/document-section.md)

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

### `FDocument.getSectionAt`

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

```typescript
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**

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

**Types:** [`FDocumentSection`](https://docs.univer.ai/ko-KR/reference/facade/document-section.md)

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

### `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.

```typescript
getSections(): FDocumentSection[]
```

**Examples**

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

**Types:** [`FDocumentSection`](https://docs.univer.ai/ko-KR/reference/facade/document-section.md)

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

### `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.

```typescript
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**

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

**Types:** [`FDocumentTextRange`](https://docs.univer.ai/ko-KR/reference/facade/document-text-range.md)

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

### `FDocument.id`

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

```typescript
readonly id: string
```

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

### `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`.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs/docs.md) · [Type definitions](https://unpkg.com/@univerjs/docs/lib/types/facade/f-document.d.ts)

### `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).

```typescript
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**

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

**Types:** [`FDocumentParagraph`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`IParagraphBorder`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.insertParagraph`

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

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md)

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

### `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.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-section.md) · [`IFDocumentInsertSectionBreakOptions`](https://unpkg.com/@univerjs/docs/lib/types/facade/f-document.d.ts)

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

### `FDocument.insertText`

Insert plain text at a document body offset.

```typescript
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**

```ts
const fDocument = univerAPI.getActiveDocument()
fDocument.insertText(0, 'Hello ')

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

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

### `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.

```typescript
isModern(): boolean
```

**Returns**

`true` only for `DocumentFlavor.MODERN`.

**Examples**

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

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

### `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.

```typescript
isTraditional(): boolean
```

**Returns**

`true` only for `DocumentFlavor.TRADITIONAL`.

**Examples**

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

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

### `FDocument.redo`

Redo the last undone operation in the document.

```typescript
redo(): boolean
```

**Returns**

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

**Examples**

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

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

### `FDocument.save`

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

```typescript
save(): IDocumentData
```

**Returns**

The document snapshot data.

**Examples**

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

**Types:** [`IDocumentData`](https://docs.univer.ai/ko-KR/reference/types/document-data.md)

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

### `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.

```typescript
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**

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

**Types:** [`IHeaderFooterProps`](https://unpkg.com/@univerjs/docs/lib/types/commands/commands/create-header-footer.command.d.ts)

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

### `FDocument.setName`

Set the document name.

```typescript
setName(name: string): this
```

**Parameters**

* `name` — Required. The new document name.

**Returns**

The current document for chaining.

**Examples**

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

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

### `FDocument.undo`

Undo the last operation in the document.

```typescript
undo(): boolean
```

**Returns**

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

**Examples**

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

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

## `@univerjs/docs-drawing`

### `FDocument.getImage`

Gets an image by its drawing id.

```typescript
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**

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

**Types:** [`FDocumentImage`](https://docs.univer.ai/ko-KR/reference/facade/document-image.md)

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

### `FDocument.getImages`

Gets all images in the document in drawing order.

```typescript
getImages(): FDocumentImage[]
```

**Returns**

The image facades in drawing order.

**Examples**

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

**Types:** [`FDocumentImage`](https://docs.univer.ai/ko-KR/reference/facade/document-image.md)

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

### `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.

```typescript
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**

```ts
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)
```

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-image.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IFDocumentInsertImageOptions`](https://unpkg.com/@univerjs/docs-drawing/lib/types/facade/f-document.d.ts)

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

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

```typescript
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**

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

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

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

### `FDocument.findCalloutByText`

Finds the first callout whose text contains the given string.

```typescript
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**

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

**Types:** [`FDocumentCallout`](https://docs.univer.ai/ko-KR/reference/facade/document-callout.md)

**Package:** [`@univerjs-pro/docs-callout`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-callout.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/f-document.d.ts)

### `FDocument.findCallouts`

Finds callouts by text or block id.

```typescript
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**

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

**Types:** [`FDocumentCallout`](https://docs.univer.ai/ko-KR/reference/facade/document-callout.md) · [`IDocsCalloutFindQuery`](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-callout`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-callout.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/f-document.d.ts)

### `FDocument.getCallout`

Returns a callout block range by its block id.

```typescript
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**

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

**Types:** [`FDocumentCallout`](https://docs.univer.ai/ko-KR/reference/facade/document-callout.md)

**Package:** [`@univerjs-pro/docs-callout`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-callout.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/f-document.d.ts)

### `FDocument.getCalloutAt`

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

```typescript
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**

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

**Types:** [`FDocumentCallout`](https://docs.univer.ai/ko-KR/reference/facade/document-callout.md)

**Package:** [`@univerjs-pro/docs-callout`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-callout.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/f-document.d.ts)

### `FDocument.getCallouts`

Returns all callout block ranges in this document.

```typescript
getCallouts(): FDocumentCallout[]
```

**Returns**

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

**Examples**

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

**Types:** [`FDocumentCallout`](https://docs.univer.ai/ko-KR/reference/facade/document-callout.md)

**Package:** [`@univerjs-pro/docs-callout`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-callout.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/f-document.d.ts)

### `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.

```typescript
insertCallout(paragraph: FDocumentParagraph, options?: IDocsCalloutInsertParagraphFacadeOptions): FDocumentCallout | null
insertCallout(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**

```ts
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(),
})
```

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-callout.md) · [`FDocumentParagraph`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`IDocsCalloutInsertParagraphFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/types.d.ts) · [`IDocsCalloutInsertFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-callout`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-callout.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-callout/lib/types/facade/f-document.d.ts)

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

### `FDocument.getChart`

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

```typescript
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**

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

**Types:** [`FDocumentChart`](https://docs.univer.ai/ko-KR/reference/facade/document-chart.md)

**Package:** [`@univerjs-pro/docs-chart`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-chart/lib/types/facade/f-document.d.ts)

### `FDocument.getCharts`

Returns all Charts in this Document.

```typescript
getCharts(): FDocumentChart[]
```

**Returns**

Live Chart facades in Document drawing order.

**Examples**

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

**Types:** [`FDocumentChart`](https://docs.univer.ai/ko-KR/reference/facade/document-chart.md)

**Package:** [`@univerjs-pro/docs-chart`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-chart/lib/types/facade/f-document.d.ts)

### `FDocument.insertChart`

Inserts a Chart into this Document from detached Chart information.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-chart.md) · [`Promise`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IDocumentChartInfo`](https://unpkg.com/@univerjs-pro/docs-chart/lib/types/chart-builder/types.d.ts)

**Package:** [`@univerjs-pro/docs-chart`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-chart/lib/types/facade/f-document.d.ts)

### `FDocument.newChart`

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

```typescript
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**

```ts
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`](https://unpkg.com/@univerjs-pro/docs-chart/lib/types/facade/f-document.d.ts)

**Package:** [`@univerjs-pro/docs-chart`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-chart.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-chart/lib/types/facade/f-document.d.ts)

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

### `FDocument.findCodeByText`

Finds the first code whose text contains the given string.

```typescript
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**

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

**Types:** [`FDocumentCode`](https://docs.univer.ai/ko-KR/reference/facade/document-code.md)

**Package:** [`@univerjs-pro/docs-code`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-code.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/f-document.d.ts)

### `FDocument.findCodes`

Finds codes by text or block id.

```typescript
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**

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

**Types:** [`FDocumentCode`](https://docs.univer.ai/ko-KR/reference/facade/document-code.md) · [`IDocsCodeFindQuery`](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-code`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-code.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/f-document.d.ts)

### `FDocument.getCode`

Returns a code block range by its block id.

```typescript
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**

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

**Types:** [`FDocumentCode`](https://docs.univer.ai/ko-KR/reference/facade/document-code.md)

**Package:** [`@univerjs-pro/docs-code`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-code.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/f-document.d.ts)

### `FDocument.getCodeAt`

Returns the code that contains a document data stream offset.

```typescript
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**

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

**Types:** [`FDocumentCode`](https://docs.univer.ai/ko-KR/reference/facade/document-code.md)

**Package:** [`@univerjs-pro/docs-code`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-code.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/f-document.d.ts)

### `FDocument.getCodes`

Returns all code block ranges in this document.

```typescript
getCodes(): FDocumentCode[]
```

**Returns**

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

**Examples**

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

**Types:** [`FDocumentCode`](https://docs.univer.ai/ko-KR/reference/facade/document-code.md)

**Package:** [`@univerjs-pro/docs-code`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-code.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/f-document.d.ts)

### `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.

```typescript
insertCode(paragraph: FDocumentParagraph, options?: IDocsCodeInsertParagraphFacadeOptions): FDocumentCode | null
insertCode(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**

```ts
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(),
})
```

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-code.md) · [`FDocumentParagraph`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`IDocsCodeInsertParagraphFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/types.d.ts) · [`IDocsCodeInsertFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-code`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-code.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-code/lib/types/facade/f-document.d.ts)

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

### `FDocument.findColumnGroupByText`

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

```typescript
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**

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

**Types:** [`FDocumentColumnGroup`](https://docs.univer.ai/ko-KR/reference/facade/document-column-group.md)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/f-document.d.ts)

### `FDocument.findColumnGroups`

Finds column groups by text or by id.

```typescript
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**

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

**Types:** [`FDocumentColumnGroup`](https://docs.univer.ai/ko-KR/reference/facade/document-column-group.md) · [`IDocsColumnFindQuery`](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/f-document.d.ts)

### `FDocument.getColumnGroup`

Returns a column group by id.

```typescript
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**

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

**Types:** [`FDocumentColumnGroup`](https://docs.univer.ai/ko-KR/reference/facade/document-column-group.md)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/f-document.d.ts)

### `FDocument.getColumnGroupAt`

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

```typescript
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**

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

**Types:** [`FDocumentColumnGroup`](https://docs.univer.ai/ko-KR/reference/facade/document-column-group.md)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/f-document.d.ts)

### `FDocument.getColumnGroups`

Returns all column groups in this document.

```typescript
getColumnGroups(): FDocumentColumnGroup[]
```

**Returns**

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

**Examples**

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

**Types:** [`FDocumentColumnGroup`](https://docs.univer.ai/ko-KR/reference/facade/document-column-group.md)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/f-document.d.ts)

### `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`.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-column-group.md) · [`IDocsColumnInsertFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-column`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-column.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-column/lib/types/facade/f-document.d.ts)

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

### `FDocument.getFormula`

Resolves one complete Doc Formula by stable `rangeId`.

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-formula.md)

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

### `FDocument.getFormulaAt`

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

```typescript
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**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-formula.md)

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

### `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.

```typescript
getFormulas(): FDocumentFormula[]
```

**Returns**

Formula handles in document order, or an empty array.

**Examples**

```ts
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`](https://docs.univer.ai/ko-KR/reference/facade/document-formula.md)

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

### `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()`.

The Command validates the range, formula syntax, and complete external
Source bindings before it commits TextX, Host External Reference, and Doc
Formula Resource mutations as one undoable user action.

```typescript
insertFormula(options: IDocFormulaInsertFacadeOptions): FDocumentFormula | null
```

**Parameters**

* `options` — Required. Formula, half-open replacement range, number format, and
  any stable external Source bindings.

**Returns**

The inserted handle, or `null` if validation or a mutation fails.

**Examples**

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

export function insertConstantFormula(univerAPI: FUniver) {
  const document = univerAPI.getActiveDocument()
  if (!document) throw new Error('No active document')
  const formula = document.insertFormula({
    formula: '=1+2',
    startOffset: 0,
    endOffset: 0,
    numberFormat: { pattern: '0.00' },
  })
  if (!formula) throw new Error('Doc Formula insertion failed')
  return formula.getId()
}
```

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

export function insertBoundFormula(univerAPI: FUniver) {
  const document = univerAPI.getActiveDocument()
  if (!document) throw new Error('No active document')
  const formula = document.insertFormula({
    formula: "='[Sales Source]Data'!A1",
    startOffset: 0,
    endOffset: 0,
    externalReferences: [
      {
        qualifier: 'Sales Source',
        sourceUnitId: 'sales-source-v1',
        sourceUnitType: UniverInstanceType.UNIVER_SHEET,
      },
    ],
  })
  if (!formula) throw new Error('Source binding or range was invalid')
  return formula.getId()
}
```

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

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

### `FDocument.saveFormulaDisplayTextSnapshot`

Saves a detached external-format projection of this document.

Native `save()` preserves Formula custom ranges and Resource entries.
This method instead replaces every main-body Doc Formula object with its
persisted `lastValue` display text and removes the Doc Formula Resource from
the returned snapshot. It never mutates the live document and is intended
for Markdown, HTML, TXT, DOCX, and other non-native exporters.

Export never triggers calculation, waits for a result, or reads the
current in-memory presentation. The last successful persisted value is
emitted with its inherited or explicit number format. A missing or empty
`lastValue` becomes an empty string; U+FFFC is never returned.

```typescript
saveFormulaDisplayTextSnapshot(): IDocumentData
```

**Returns**

A detached `IDocumentData` projection safe for external export.

**Examples**

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

export function saveForExternalExporter(univerAPI: FUniver) {
  const document = univerAPI.getActiveDocument()
  if (!document) throw new Error('No active document')
  const snapshot = document.saveFormulaDisplayTextSnapshot()
  if (snapshot.body?.dataStream.includes('\uFFFC')) {
    throw new Error('External snapshot contains an object token')
  }
  return snapshot
}
```

**Types:** [`IDocumentData`](https://docs.univer.ai/ko-KR/reference/types/document-data.md)

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

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

### `FDocument.findLatexFormulaByText`

Finds the first LaTeX formula whose source contains the given text.

```typescript
findLatexFormulaByText(latex: string, segmentId?: string): FDocumentLatex | null
```

**Parameters**

* `latex` — Required. Text to search for inside formula source.
* `segmentId` — Optional. Default: `''`. Header/footer segment id. Omit it for the main document body.

**Returns**

The first matching formula, or `null` if no match is found.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')
const existing = document.getLatexFormulas()[0]
if (!existing) throw new Error('No LaTeX formula')
const formula = document.findLatexFormulaByText(existing.getLatex())
if (!formula) throw new Error('Cannot find LaTeX formula by text')
console.log(formula.getRange())
```

**Types:** [`FDocumentLatex`](https://docs.univer.ai/ko-KR/reference/facade/document-latex.md)

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

### `FDocument.findLatexFormulas`

Finds LaTeX formulas by source text or range id.

```typescript
findLatexFormulas(query: string | IDocsLatexFindQuery, segmentId?: string): FDocumentLatex[]
```

**Parameters**

* `query` — Required. A source-text query or a structured query.
* `segmentId` — Optional. Default: `''`. Header/footer segment id. Omit it for the main document body.

**Returns**

Matching formula facade objects, or an empty array if no match is found.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')
const existing = document.getLatexFormulas()[0]
if (!existing) throw new Error('No LaTeX formula')
const byText = document.findLatexFormulas(existing.getLatex())
const byId = document.findLatexFormulas({ rangeId: existing.getId() })
console.log(byText, byId)
```

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

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

### `FDocument.getLatexFormula`

Returns a LaTeX formula by its range id.

```typescript
getLatexFormula(rangeId: string, segmentId?: string): FDocumentLatex | null
```

**Parameters**

* `rangeId` — Required. The formula custom range id.
* `segmentId` — Optional. Default: `''`. Header/footer segment id. Omit it for the main document body.

**Returns**

The matching formula facade object, or `null` if no formula has that id.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')
const existing = document.getLatexFormulas()[0]
if (!existing) throw new Error('No LaTeX formula')
const formula = document.getLatexFormula(existing.getId())
if (!formula) throw new Error('Cannot find LaTeX formula by id')
console.log(formula.describe())
```

**Types:** [`FDocumentLatex`](https://docs.univer.ai/ko-KR/reference/facade/document-latex.md)

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

### `FDocument.getLatexFormulaAt`

Returns the LaTeX formula that contains a document data-stream offset.

```typescript
getLatexFormulaAt(offset: number, segmentId?: string): FDocumentLatex | null
```

**Parameters**

* `offset` — Required. The document data-stream offset.
* `segmentId` — Optional. Default: `''`. Header/footer segment id. Omit it for the main document body.

**Returns**

The formula at the offset, or `null` if the offset is not inside a formula.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')
const existing = document.getLatexFormulas()[0]
if (!existing) throw new Error('No LaTeX formula')
const range = existing.getRange()
if (!range) throw new Error('LaTeX formula has no range')
const formula = document.getLatexFormulaAt(range.startOffset)
if (!formula) throw new Error('Cannot find LaTeX formula at offset')
console.log(formula.getLatex())
```

**Types:** [`FDocumentLatex`](https://docs.univer.ai/ko-KR/reference/facade/document-latex.md)

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

### `FDocument.getLatexFormulas`

Returns all LaTeX formulas in this document.

```typescript
getLatexFormulas(segmentId?: string): FDocumentLatex[]
```

**Parameters**

* `segmentId` — Optional. Default: `''`. Header/footer segment id. Omit it for the main document body.

**Returns**

An array of formula facade objects, or an empty array if the document has none.

**Examples**

```ts
const univerAPI = FUniver.newAPI(univer)
const document = univerAPI.getActiveDocument()
if (!document) throw new Error('No active document')
const formulas = document.getLatexFormulas()
console.log(formulas.map((formula) => formula.getLatex()))
```

**Types:** [`FDocumentLatex`](https://docs.univer.ai/ko-KR/reference/facade/document-latex.md)

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

### `FDocument.insertLatexAtOffset`

Inserts a LaTeX formula at an explicit document offset.

This is a low-level API. Agent-authored code should prefer
`FDocumentParagraph.appendLatex` or `FDocumentTextRange.replaceWithLatex`.

```typescript
insertLatexAtOffset(offset: number, latex: string, options?: IDocsLatexCreateFacadeOptions & { segmentId?: string; }): FDocumentLatex | null
```

**Parameters**

* `offset` — Required. Inclusive insertion offset.
* `latex` — Required. LaTeX source without `$` or `$$` delimiters.
* `options` — Optional. Default: `{}`. Segment and 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.appendParagraph('Energy: ')
const formula = document.insertLatexAtOffset(paragraph.getInfo().endOffset, 'E = mc^2')
if (!formula) throw new Error('Failed to insert LaTeX formula')
console.log(formula.describe())
```

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

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

### `FDocument.insertLatexAtSelection`

Inserts or replaces a LaTeX formula at the active editor selection.

This UI-selection API is not suitable for headless runtimes.

```typescript
insertLatexAtSelection(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 no valid selection exists.

**Examples**

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

// The user must first select text in the active Docs editor.
const formula = document.insertLatexAtSelection('F = ma')
if (!formula) {
  throw new Error('No valid Docs selection, or the insertion failed')
}
console.log(formula.describe())
```

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

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

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

### `FDocument.describeListItems`

Returns agent-friendly list item descriptions in this document body or header/footer body by the segment id.

```typescript
describeListItems(segmentId?: string): IDocsListItemInfo[]
```

**Parameters**

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

**Returns**

An array of list item info objects, or an empty array if no list items exist in the document.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const listItemInfos = fDocument.describeListItems()
console.log(listItemInfos)

const headerSegmentId = fDocument.ensurePageHeader()
const headerListItemInfos = fDocument.describeListItems(headerSegmentId)
console.log(headerListItemInfos)

const footerSegmentId = fDocument.ensurePageFooter()
const footerListItemInfos = fDocument.describeListItems(footerSegmentId)
console.log(footerListItemInfos)
```

**Types:** [`IDocsListItemInfo`](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.findListItemByText`

Finds the first list item in this document body or header/footer body that contains the given text.

```typescript
findListItemByText(text: string, segmentId?: string): FDocumentListItem | null
```

**Parameters**

* `text` — Required. Text to search inside list item content.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const listItem = fDocument.findListItemByText('Ship API')
console.log(listItem)

const headerSegmentId = fDocument.ensurePageHeader()
const headerListItem = fDocument.findListItemByText('Ship API', headerSegmentId)
console.log(headerListItem)

const footerSegmentId = fDocument.ensurePageFooter()
const footerListItem = fDocument.findListItemByText('Ship API', footerSegmentId)
console.log(footerListItem)
```

**Types:** [`FDocumentListItem`](https://docs.univer.ai/ko-KR/reference/facade/document-list-item.md)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.findListItems`

Finds list items in this document body or header/footer body that match the given query.

```typescript
findListItems(query: string | IDocsListFindQuery, segmentId?: string): FDocumentListItem[]
```

**Parameters**

* `query` — Required. A plain text query or a structured list item query.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const listItems = fDocument.findListItems({ text: 'API', nestingLevel: 2 })
console.log(listItems)

const headerSegmentId = fDocument.ensurePageHeader()
const headerListItems = fDocument.findListItems({ text: 'API', nestingLevel: 2 }, headerSegmentId)
console.log(headerListItems)

const footerSegmentId = fDocument.ensurePageFooter()
const footerListItems = fDocument.findListItems({ text: 'API', nestingLevel: 2 }, footerSegmentId)
console.log(footerListItems)
```

**Types:** [`FDocumentListItem`](https://docs.univer.ai/ko-KR/reference/facade/document-list-item.md) · [`IDocsListFindQuery`](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.getList`

Returns a list in this document body or header/footer body by the list id and segment id.

```typescript
getList(listId: string, segmentId?: string): FDocumentList | null
```

**Parameters**

* `listId` — Required. The list id stored on paragraph bullets.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

The FDocumentList instance, or `null` if no list with the id exists in the document.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const list = fDocument.getList('list-id-123')
console.log(list)

const headerSegmentId = fDocument.ensurePageHeader()
const headerList = fDocument.getList('list-id-123', headerSegmentId)
console.log(headerList)

const footerSegmentId = fDocument.ensurePageFooter()
const footerList = fDocument.getList('list-id-123', footerSegmentId)
console.log(footerList)
```

**Types:** [`FDocumentList`](https://docs.univer.ai/ko-KR/reference/facade/document-list.md)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.getListItem`

Returns a list item in this document body or header/footer body by the paragraph start index and segment id.

```typescript
getListItem(paragraphStartIndex: number, segmentId?: string): FDocumentListItem | null
```

**Parameters**

* `paragraphStartIndex` — Required. The paragraph start index that identifies a list item.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

The FDocumentListItem instance, or `null` if no list item with the paragraph start index exists in the document.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const listItem = fDocument.getListItem(10)
console.log(listItem)

const headerSegmentId = fDocument.ensurePageHeader()
const headerListItem = fDocument.getListItem(10, headerSegmentId)
console.log(headerListItem)

const footerSegmentId = fDocument.ensurePageFooter()
const footerListItem = fDocument.getListItem(10, footerSegmentId)
console.log(footerListItem)
```

**Types:** [`FDocumentListItem`](https://docs.univer.ai/ko-KR/reference/facade/document-list-item.md)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.getListItemAt`

Returns the list item in this document body or header/footer body that contains the given offset.

```typescript
getListItemAt(offset: number, segmentId?: string): FDocumentListItem | null
```

**Parameters**

* `offset` — Required. The document data stream offset.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

The FDocumentListItem instance, or `null` if no list item contains the offset.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const listItem = fDocument.getListItemAt(150)
console.log(listItem)

const headerSegmentId = fDocument.ensurePageHeader()
const headerListItem = fDocument.getListItemAt(150, headerSegmentId)
console.log(headerListItem)

const footerSegmentId = fDocument.ensurePageFooter()
const footerListItem = fDocument.getListItemAt(150, footerSegmentId)
console.log(footerListItem)
```

**Types:** [`FDocumentListItem`](https://docs.univer.ai/ko-KR/reference/facade/document-list-item.md)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.getListItems`

Returns all list items in this document body or header/footer body by the segment id.

```typescript
getListItems(segmentId?: string): FDocumentListItem[]
```

**Parameters**

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

**Returns**

An array of FDocumentListItem instances, or an empty array if no list items exist in the document.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const listItems = fDocument.getListItems()
console.log(listItems)

const headerSegmentId = fDocument.ensurePageHeader()
const headerListItems = fDocument.getListItems(headerSegmentId)
console.log(headerListItems)

const footerSegmentId = fDocument.ensurePageFooter()
const footerListItems = fDocument.getListItems(footerSegmentId)
console.log(footerListItems)
```

**Types:** [`FDocumentListItem`](https://docs.univer.ai/ko-KR/reference/facade/document-list-item.md)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.getLists`

Returns all docs lists in this document body or header/footer body by the segment id.

```typescript
getLists(segmentId?: string): FDocumentList[]
```

**Parameters**

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

**Returns**

An array of FDocumentList instances.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const lists = fDocument.getLists()
console.log(lists)

const headerSegmentId = fDocument.ensurePageHeader()
const headerLists = fDocument.getLists(headerSegmentId)
console.log(headerLists)

const footerSegmentId = fDocument.ensurePageFooter()
const footerLists = fDocument.getLists(footerSegmentId)
console.log(footerLists)
```

**Types:** [`FDocumentList`](https://docs.univer.ai/ko-KR/reference/facade/document-list.md)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.insertList`

Applies list formatting to a paragraph element in this document body or header/footer body.
The paragraph wrapper is resolved by persisted `paragraphId` before the command runs, so facade edits
inserted before the paragraph do not require recalculating offsets.

```typescript
insertList(paragraph: FDocumentParagraph, options?: IDocsListInsertParagraphFacadeOptions): FDocumentList | null
insertList(options?: IDocsListInsertFacadeOptions): FDocumentList | null
```

**Parameters**

* `paragraph` — Optional. The paragraph to convert to a list item.
* `options` — Optional. Optional list type.

**Returns**

The inserted list facade, or `null` if the insert list command failed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Insert a bullet list around a paragraph with the default list type.
const paragraph = fDocument.appendParagraph('Ship docs facade examples')
const list = fDocument.insertList(paragraph, {
  listType: univerAPI.Enum.PresetListType.BULLET_LIST,
})
console.log(list.describe())

// Insert an ordered list around a paragraph in the header and footer with different list types.
const headerSegmentId = fDocument.ensurePageHeader()
const headerParagraph = fDocument.appendParagraph('Header list item', headerSegmentId)
const headerList = fDocument.insertList(headerParagraph, {
  listType: univerAPI.Enum.PresetListType.ORDER_LIST,
})
console.log(headerList.describe())

const footerSegmentId = fDocument.ensurePageFooter()
const footerParagraph = fDocument.appendParagraph('Footer list item', footerSegmentId)
const footerList = fDocument.insertList(footerParagraph, {
  listType: univerAPI.Enum.PresetListType.ORDER_LIST_2,
})
console.log(footerList.describe())
```

```ts
const fDocument = univerAPI.getActiveDocument()

// Insert a bullet list in a table cell range with the default list type.
const table = fDocument.findTableByText('Revenue')
const range = table?.getCell(1, 0)?.getContentRange()
if (range) {
  const list = fDocument.insertList({
    ...range,
    listType: univerAPI.Enum.PresetListType.BULLET_LIST,
  })
  console.log(list.describe())
}

const paragraph = fDocument.findParagraphByText('List item 1')
if (paragraph) {
  const paragraphs = fDocument.getParagraphs()
  const { paragraphIndex, startOffset } = paragraph.getInfo()
  const { endOffset } = paragraphs[paragraphIndex + 3].getInfo()
  const list2 = fDocument.insertList({
    startOffset,
    endOffset,
    listType: univerAPI.Enum.PresetListType.BULLET_LIST,
  })
  console.log(list2.describe())
}

// Insert a list in the page footer by passing the footer segment id.
const footerSegmentId = fDocument.ensurePageFooter()
const footerList = fDocument.insertList({
  startOffset: 0,
  endOffset: 20,
  segmentId: footerSegmentId,
  listType: univerAPI.Enum.PresetListType.ORDER_LIST,
})
console.log(footerList.describe())
```

**Types:** [`FDocumentList`](https://docs.univer.ai/ko-KR/reference/facade/document-list.md) · [`FDocumentParagraph`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`IDocsListInsertParagraphFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/types.d.ts) · [`IDocsListInsertFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.setBullet`

Agent-friendly shorthand for applying a bullet list to a paragraph.

```typescript
setBullet(paragraph: FDocumentParagraph, options?: Omit<IDocsListInsertParagraphFacadeOptions, 'listType'>): FDocumentList | null
```

**Parameters**

* `paragraph` — Required.
* `options` — Optional. Default: `{}`.

**Types:** [`FDocumentList`](https://docs.univer.ai/ko-KR/reference/facade/document-list.md) · [`FDocumentParagraph`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IDocsListInsertParagraphFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

### `FDocument.setOrderedList`

Agent-friendly shorthand for applying an ordered list to a paragraph.

```typescript
setOrderedList(paragraph: FDocumentParagraph, options?: Omit<IDocsListInsertParagraphFacadeOptions, 'listType'>): FDocumentList | null
```

**Parameters**

* `paragraph` — Required.
* `options` — Optional. Default: `{}`.

**Types:** [`FDocumentList`](https://docs.univer.ai/ko-KR/reference/facade/document-list.md) · [`FDocumentParagraph`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IDocsListInsertParagraphFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-list`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-list.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-list/lib/types/facade/f-document.d.ts)

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

### `FDocument.findQuoteByText`

Finds the first quote whose text contains the given string.

```typescript
findQuoteByText(text: string): FDocumentQuote | null
```

**Parameters**

* `text` — Required. Text to search inside quote content.

**Returns**

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const quote = fDocument.findQuoteByText('Decision')
console.log(quote)
```

**Types:** [`FDocumentQuote`](https://docs.univer.ai/ko-KR/reference/facade/document-quote.md)

**Package:** [`@univerjs-pro/docs-quote`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-quote.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/f-document.d.ts)

### `FDocument.findQuotes`

Finds quotes by text or block id.

```typescript
findQuotes(query: string | IDocsQuoteFindQuery): FDocumentQuote[]
```

**Parameters**

* `query` — Required. A plain text query or a structured quote query.

**Returns**

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const quotesWithText = fDocument.findQuotes('Decision')
const quotesWithId = fDocument.findQuotes({ blockId: 'block-id-123' })
console.log(quotesWithText, quotesWithId)
```

**Types:** [`FDocumentQuote`](https://docs.univer.ai/ko-KR/reference/facade/document-quote.md) · [`IDocsQuoteFindQuery`](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-quote`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-quote.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/f-document.d.ts)

### `FDocument.getQuote`

Returns a quote block range by its block id.

```typescript
getQuote(blockId: string): FDocumentQuote | null
```

**Parameters**

* `blockId` — Required. The quote block range id.

**Returns**

The FDocumentQuote instance, or `null` if no quote block range with the id exists in the document.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const quote = fDocument.getQuote('block-id-123')
console.log(quote)
```

**Types:** [`FDocumentQuote`](https://docs.univer.ai/ko-KR/reference/facade/document-quote.md)

**Package:** [`@univerjs-pro/docs-quote`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-quote.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/f-document.d.ts)

### `FDocument.getQuoteAt`

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

```typescript
getQuoteAt(offset: number): FDocumentQuote | null
```

**Parameters**

* `offset` — Required. The document data stream offset.

**Returns**

The FDocumentQuote instance, or `null` if no quote block range contains the offset.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const quote = fDocument.getQuoteAt(150)
console.log(quote)
```

**Types:** [`FDocumentQuote`](https://docs.univer.ai/ko-KR/reference/facade/document-quote.md)

**Package:** [`@univerjs-pro/docs-quote`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-quote.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/f-document.d.ts)

### `FDocument.getQuotes`

Returns all quote block ranges in this document.

```typescript
getQuotes(): FDocumentQuote[]
```

**Returns**

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

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const quotes = fDocument.getQuotes()
console.log(quotes)
```

**Types:** [`FDocumentQuote`](https://docs.univer.ai/ko-KR/reference/facade/document-quote.md)

**Package:** [`@univerjs-pro/docs-quote`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-quote.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/f-document.d.ts)

### `FDocument.insertQuote`

Inserts a quote 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 quote 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 quote 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.

```typescript
insertQuote(paragraph: FDocumentParagraph, options?: IDocsQuoteInsertParagraphFacadeOptions): FDocumentQuote | null
insertQuote(options?: IDocsQuoteInsertFacadeOptions): FDocumentQuote | null
```

**Parameters**

* `paragraph` — Optional. The paragraph to convert to a quote.
* `options` — Optional. Optional block id.

**Returns**

The inserted FDocumentQuote instance, or `null` if the insert quote failed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
if (!fDocument) {
  throw new Error('No active document')
}

// Insert a quote around a paragraph.
const paragraph = fDocument.appendParagraph('Simplicity is prerequisite for reliability.')
const quote = fDocument.insertQuote(paragraph)
if (!quote) {
  throw new Error('Failed to insert the quote')
}
console.log({
  text: quote.getText(),
  wordPaginationApplied: fDocument.isTraditional(),
})
```

```ts
const fDocument = univerAPI.getActiveDocument()
if (!fDocument) {
  throw new Error('No active document')
}

// Insert a quote around the text 'Decision' in a table cell.
const table = fDocument.findTableByText('Decision')
const range = table?.getCell(1, 0)?.getContentRange()
if (!range) {
  throw new Error('Decision table cell not found')
}
const quote = fDocument.insertQuote(range)
if (!quote) {
  throw new Error('Failed to insert the table-cell quote')
}
console.log(quote.getId())

// Insert a quote around the text 'Quote' and the next paragraph.
const paragraph = fDocument.findParagraphByText('Quote')
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 quote start')
  }
  const { endOffset } = finalParagraph.getInfo()
  const quote2 = fDocument.insertQuote({ startOffset, endOffset })
  if (!quote2) {
    throw new Error('Failed to insert the multi-paragraph quote')
  }
  console.log(quote2.getId())
}
```

**Types:** [`FDocumentQuote`](https://docs.univer.ai/ko-KR/reference/facade/document-quote.md) · [`FDocumentParagraph`](https://docs.univer.ai/ko-KR/reference/facade/document-paragraph.md) · [`IDocsQuoteInsertParagraphFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/types.d.ts) · [`IDocsQuoteInsertFacadeOptions`](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-quote`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-quote.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-quote/lib/types/facade/f-document.d.ts)

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

### `FDocument.deleteEndnote`

Removes an endnote and its body reference; supports undo and collaboration.

```typescript
deleteEndnote(noteId: string): boolean
```

**Parameters**

* `noteId` — Required. Stable endnote segment id.

**Returns**

Whether deletion succeeded.

**Examples**

```ts
const document = univerAPI.getActiveDocument()
const note = document?.getEndnotes()[0]
if (note) document.deleteEndnote(note.noteId)
```

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

### `FDocument.deleteFootnote`

Removes a footnote together with its body reference. Supports undo and collaboration.

```typescript
deleteFootnote(noteId: string): boolean
```

**Parameters**

* `noteId` — Required. Stable segment id returned by insertFootnote or getFootnotes.

**Returns**

Whether the deletion was applied.

**Examples**

```ts
const document = univerAPI.getActiveDocument()
const note = document?.getFootnotes()[0]
if (note) document.deleteFootnote(note.noteId)
```

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

### `FDocument.getEndnotes`

Returns detached endnotes in body reference order.

```typescript
getEndnotes(): IDocumentNote[]
```

**Returns**

Endnote data.

**Examples**

```ts
console.log(univerAPI.getActiveDocument()?.getEndnotes())
```

**Types:** [`IDocumentNote`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.getEndnoteSettings`

Returns explicit document settings or section overrides.

```typescript
getEndnoteSettings(sectionId?: string): IEndnoteSettings | undefined
```

**Parameters**

* `sectionId` — Optional. Optional section id.

**Returns**

Detached explicit settings.

**Examples**

```ts
console.log(univerAPI.getActiveDocument()?.getEndnoteSettings())
```

**Types:** [`IEndnoteSettings`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.getFootnotes`

Returns detached note data in reference order. Automatic labels depend on layout
when numbering restarts on each page; the persisted segment id remains stable.

```typescript
getFootnotes(): IDocumentNote[]
```

**Returns**

Notes referenced by the main body.

**Examples**

```ts
console.log(univerAPI.getActiveDocument()?.getFootnotes())
```

**Types:** [`IDocumentNote`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.getFootnoteSettings`

Reads explicit document defaults or a section override, without expanding inherited values.

```typescript
getFootnoteSettings(sectionId?: string): IFootnoteSettings | undefined
```

**Parameters**

* `sectionId` — Optional. Optional stable section id.

**Returns**

Detached explicit settings, or undefined if absent.

**Examples**

```ts
console.log(univerAPI.getActiveDocument()?.getFootnoteSettings())
```

**Types:** [`IFootnoteSettings`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.insertEndnote`

Inserts an endnote with its body reference as one undoable change.

```typescript
insertEndnote(offset: number, content?: Partial<Omit<IDocumentNote, 'noteId' | 'type'>>): string | null
```

**Parameters**

* `offset` — Required. UTF-16 body offset.
* `content` — Optional. Default: `{}`. Optional rich content and custom mark.

**Returns**

Stable note segment id, or null when insertion is rejected.

**Examples**

```ts
const id = univerAPI.getActiveDocument()?.insertEndnote(5)
```

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IDocumentNote`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.insertFootnote`

Inserts a traditional-document footnote at a UTF-16 body offset and selects its content.
The reference and rich content share one undo/collaboration mutation. Returns null
for a modern document, an invalid position/content, or insufficient edit permission.

```typescript
insertFootnote(offset: number, content?: Partial<Omit<IDocumentNote, 'noteId' | 'type'>>): string | null
```

**Parameters**

* `offset` — Required. Position in the main body, including structural tokens.
* `content` — Optional. Default: `{}`. Optional paragraphs, inline drawings, tables and custom mark.

**Returns**

Stable segment id, usable with getTextRange and getParagraphs.

**Examples**

```ts
const document = univerAPI.getActiveDocument()
const id = document?.insertFootnote(5, {
  body: { dataStream: 'Source details\r\n', paragraphs: [{ startIndex: 14 }] },
})
if (id) console.log(document.getParagraphs(id))
```

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`Omit`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts) · [`IDocumentNote`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.setEndnoteSettings`

Replaces endnote settings; null restores inherited defaults.

```typescript
setEndnoteSettings(settings: IEndnoteSettings | null, sectionId?: string): boolean
```

**Parameters**

* `settings` — Required. Endnote settings or null.
* `sectionId` — Optional. Optional section id.

**Returns**

Whether settings changed.

**Examples**

```ts
univerAPI.getActiveDocument()?.setEndnoteSettings({ position: 'sectEnd', restart: 'eachSect' })
```

**Types:** [`IEndnoteSettings`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

### `FDocument.setFootnoteSettings`

Replaces explicit footnote settings; null restores inherited defaults. Section overrides
support position, columns and numbering. Separator bodies belong to document defaults.

```typescript
setFootnoteSettings(settings: IFootnoteSettings | null, sectionId?: string): boolean
```

**Parameters**

* `settings` — Required. Replacement settings or null to reset.
* `sectionId` — Optional. Optional stable section id.

**Returns**

Whether the settings changed.

**Examples**

```ts
univerAPI.getActiveDocument()?.setFootnoteSettings({
  position: 'pageBottom',
  columnCount: 2,
  numberFormat: 'decimal',
  startNumber: 1,
  restart: 'eachSect',
})
```

**Types:** [`IFootnoteSettings`](https://unpkg.com/@univerjs/core/lib/types/types/interfaces/i-document-data.d.ts)

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

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

### `FDocument.getShape`

Returns a document Shape by its stable identifier.

```typescript
getShape(shapeId: string): FShape | FConnectorShape | null
```

**Parameters**

* `shapeId` — Required.

**Returns**

The Shape facade, or `null` when it does not exist.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const fShape = fDocument.getShape('shape-1')
console.log(fShape)
```

**Types:** [`FShape`](https://docs.univer.ai/ko-KR/reference/facade/shape.md) · [`FConnectorShape`](https://docs.univer.ai/ko-KR/reference/facade/connector-shape.md)

**Package:** [`@univerjs-pro/docs-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-shape/lib/types/facade/f-document.d.ts)

### `FDocument.getShapes`

Returns all Shapes and Connectors in document drawing order.

```typescript
getShapes(): Array<FShape | FConnectorShape>
```

**Returns**

The Shape facades in document drawing order.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const fShapes = fDocument.getShapes()
console.log(fShapes)
```

**Types:** [`FShape`](https://docs.univer.ai/ko-KR/reference/facade/shape.md) · [`FConnectorShape`](https://docs.univer.ai/ko-KR/reference/facade/connector-shape.md) · [`Array`](https://unpkg.com/@typescript/typescript-darwin-arm64/lib/lib.es5.d.ts)

**Package:** [`@univerjs-pro/docs-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-shape/lib/types/facade/f-document.d.ts)

### `FDocument.insertShape`

Inserts a Shape or Connector into this document.

A document Shape is anchored by a persisted paragraph id, so edits before that paragraph do not invalidate
the insertion target. Inline Shapes follow text flow and cannot specify a floating position. The other four
wrapping styles accept `placement.position`: its horizontal offset is page-relative and its vertical offset
is relative to the anchor paragraph. Prefer square or top-and-bottom wrapping for ordinary floating content.
Front-of-text and behind-text Shapes do not cause text to reflow: use them only for intentional overlays,
backgrounds, or watermarks. `transform` controls only width, height, and rotation.

```typescript
insertShape(input: IDocShapeCreateInput): FShape | FConnectorShape | null
```

**Parameters**

* `input` — Required. Shape data, document placement, size, and rotation.

**Returns**

A live document Shape facade, or `null` when creation fails.

**Examples**

Insert an inline Shape at the end of the first paragraph

```ts
const fDocument = univerAPI.getActiveDocument()
const paragraph = fDocument?.getParagraphs()[0]
if (!fDocument || !paragraph) throw new Error('Document paragraph not found.')

const fShape = fDocument.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  placement: {
    wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,
    anchor: {
      paragraphId: paragraph.getId(),
      segmentId: paragraph.getSegmentId(),
      position: univerAPI.Enum.DocShapeAnchorPosition.PARAGRAPH_END,
    },
  },
  transform: { width: 180, height: 72 },
})
if (!fShape) throw new Error('Shape could not be inserted.')
```

Insert a floating Shape with square text wrapping

```ts
const fDocument = univerAPI.getActiveDocument()
const paragraph = fDocument?.findParagraphByText('Quarterly revenue')
if (!fDocument || !paragraph) throw new Error('Anchor paragraph not found.')

const fShape = fDocument.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  placement: {
    wrappingStyle: univerAPI.Enum.TextWrappingStyle.WRAP_SQUARE,
    anchor: {
      paragraphId: paragraph.getId(),
      segmentId: paragraph.getSegmentId(),
    },
    position: { horizontalOffset: 96, verticalOffset: 24 },
  },
  transform: { width: 240, height: 120, rotation: 5 },
  shapeData: {
    fill: { fillType: univerAPI.Enum.ShapeFillEnum.SolidFill, color: '#dcfce7' },
    stroke: {
      lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine,
      color: '#16a34a',
      width: 2,
    },
  },
})
if (!fShape) throw new Error('Shape could not be inserted.')
fShape.getText().setText('Quarterly revenue')
```

Insert a top-and-bottom Formula Shape at a paragraph character offset

```ts
const fDocument = univerAPI.getActiveDocument()
const paragraph = fDocument?.getParagraphs()[0]
if (!fDocument || !paragraph) throw new Error('Document paragraph not found.')

const fShape = fDocument.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  placement: {
    wrappingStyle: univerAPI.Enum.TextWrappingStyle.WRAP_TOP_AND_BOTTOM,
    anchor: {
      paragraphId: paragraph.getId(),
      segmentId: paragraph.getSegmentId(),
      position: univerAPI.Enum.DocShapeAnchorPosition.OFFSET,
      offset: 0,
    },
    position: { horizontalOffset: 72, verticalOffset: 16 },
  },
  transform: { width: 280, height: 80 },
})
if (!fShape) throw new Error('Shape could not be inserted.')
fShape.setFormula({
  formula: '=SUM([Sales]Data!B2:B10)',
  externalReferences: [
    {
      qualifier: 'Sales',
      sourceUnitId: 'sales-workbook',
      sourceUnitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET,
    },
  ],
})
```

Insert an intentional foreground overlay that may cover document text

```ts
const fDocument = univerAPI.getActiveDocument()
const paragraph = fDocument?.getParagraphs()[0]
if (!fDocument || !paragraph) throw new Error('Document paragraph not found.')

const fShape = fDocument.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse,
  placement: {
    // This overlay does not reserve text-layout space and can cover body text.
    wrappingStyle: univerAPI.Enum.TextWrappingStyle.IN_FRONT_OF_TEXT,
    anchor: {
      paragraphId: paragraph.getId(),
      segmentId: paragraph.getSegmentId(),
    },
    position: { horizontalOffset: 120, verticalOffset: 24 },
  },
  transform: { width: 180, height: 100 },
})
if (!fShape) throw new Error('Shape could not be inserted.')
fShape.getText().setText('Foreground note')
```

Insert a background Shape behind document text

```ts
const fDocument = univerAPI.getActiveDocument()
const paragraph = fDocument?.getParagraphs()[0]
if (!fDocument || !paragraph) throw new Error('Document paragraph not found.')

const fShape = fDocument.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  placement: {
    // Text does not reflow, so use a low-contrast fill that preserves readability.
    wrappingStyle: univerAPI.Enum.TextWrappingStyle.BEHIND_TEXT,
    anchor: {
      paragraphId: paragraph.getId(),
      segmentId: paragraph.getSegmentId(),
    },
    position: { horizontalOffset: 72, verticalOffset: 12 },
  },
  transform: { width: 320, height: 120 },
  shapeData: {
    fill: { fillType: univerAPI.Enum.ShapeFillEnum.SolidFill, color: '#dbeafe' },
  },
})
if (!fShape) throw new Error('Shape could not be inserted.')
fShape.setSelectable(false)
```

**Types:** [`FShape`](https://docs.univer.ai/ko-KR/reference/facade/shape.md) · [`FConnectorShape`](https://docs.univer.ai/ko-KR/reference/facade/connector-shape.md) · [`IDocShapeCreateInput`](https://unpkg.com/@univerjs-pro/docs-shape/lib/types/common/types.d.ts)

**Package:** [`@univerjs-pro/docs-shape`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-shape.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-shape/lib/types/facade/f-document.d.ts)

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

### `FDocument.findTableByText`

Finds the first table whose data stream contains the given text in this document body or header/footer body by the segment id.

```typescript
findTableByText(text: string, segmentId?: string): FDocumentTable | null
```

**Parameters**

* `text` — Required. Text to search inside table cells.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

The first FDocumentTable instance matching the query, or `null` if no matches are found.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const table = fDocument.findTableByText('Revenue')
console.log(table)

const headerSegmentId = fDocument.ensurePageHeader()
const headerTable = fDocument.findTableByText('Revenue', headerSegmentId)
console.log(headerTable)
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)

### `FDocument.findTables`

Finds tables by text, id, header text, or title text in this document body or header/footer body by the segment id.

```typescript
findTables(query: string | IDocsTableFindQuery, segmentId?: string): FDocumentTable[]
```

**Parameters**

* `query` — Required. A plain text query or a structured table query.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

An array of FDocumentTable instances matching the query, or an empty array if no matches are found.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const tablesWithText = fDocument.findTables('Revenue')
console.log(tablesWithText)

const tablesWithId = fDocument.findTables({ tableId: 'table-1' })
console.log(tablesWithId)

const tablesWithHeader = fDocument.findTables({ headerText: 'Q1' })
console.log(tablesWithHeader)

const tablesWithTitle = fDocument.findTables({ titleText: 'Sales Data' })
console.log(tablesWithTitle)

const footerSegmentId = fDocument.ensurePageFooter()
const footerTablesWithText = fDocument.findTables('Revenue', footerSegmentId)
console.log(footerTablesWithText)
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md) · [`IDocsTableFindQuery`](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/types.d.ts)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)

### `FDocument.getTable`

Returns a table by table id in this document body or header/footer body by the segment id.

```typescript
getTable(tableId: string, segmentId?: string): FDocumentTable | null
```

**Parameters**

* `tableId` — Required. The table id stored in the document snapshot.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

The FDocumentTable instance, or `null` if no table with the given id exists in the document.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const table = fDocument.getTable('table-1')
console.log(table)

const headerSegmentId = fDocument.ensurePageHeader()
const headerTable = fDocument.getTable('table-1', headerSegmentId)
console.log(headerTable)
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)

### `FDocument.getTableAt`

Returns a table by its order in this document body or header/footer body by the segment id.

```typescript
getTableAt(index: number, segmentId?: string): FDocumentTable | null
```

**Parameters**

* `index` — Required. The zero-based table index.
* `segmentId` — Optional. Default: `''`. The segment id of the body. Defaults to an empty string for the main body.

**Returns**

The FDocumentTable instance, or `null` if the index is out of bounds.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const firstTable = fDocument.getTableAt(0)
console.log(firstTable)

const footerSegmentId = fDocument.ensurePageFooter()
const firstFooterTable = fDocument.getTableAt(0, footerSegmentId)
console.log(firstFooterTable)
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)

### `FDocument.getTableAtSelection`

Returns the table currently selected by the docs table selection service.

```typescript
getTableAtSelection(): FDocumentTable | null
```

**Returns**

The FDocumentTable instance, or `null` if there is no current table selection.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const selectedTable = fDocument.getTableAtSelection()
console.log(selectedTable)
console.log(selectedTable?.getSegmentId())
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)

### `FDocument.getTables`

Returns all enhanced docs tables in this document body or header/footer body by the segment id.

```typescript
getTables(segmentId?: string): FDocumentTable[]
```

**Parameters**

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

**Returns**

An array of FDocumentTable instances, or an empty array if the document contains no tables.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const tables = fDocument.getTables()
console.log(tables)

const headerSegmentId = fDocument.ensurePageHeader()
const headerTables = fDocument.getTables(headerSegmentId)
console.log(headerTables)
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)

### `FDocument.insertTable`

Inserts an empty table at the current document selection or at the position provided in options.

```typescript
insertTable(rows: number, columns: number, options?: IDocsTableInsertOptions): FDocumentTable | null
```

**Parameters**

* `rows` — Required. The row count.
* `columns` — Required. The column count.
* `options` — Optional. Default: `{}`. Optional table id, position, metadata, and layout options.

**Returns**

The inserted FDocumentTable instance, or `null` if the insert table failed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Insert a 3x4 table at the default position (document end)
const table = fDocument.insertTable(3, 4)

// Insert a 3x4 table at the current selection
const table2 = fDocument.insertTable(3, 4, {
  position: univerAPI.Enum.DocsTableInsertTablePosition.Selection,
})

// Insert a 3x4 table with cell values at a specific offset
const table3 = fDocument.insertTable(3, 4, {
  position: univerAPI.Enum.DocsTableInsertTablePosition.Offset,
  offset: 1000,
  values: [
    ['A1', 'B1', 'C1', 'D1'],
    ['A2', 'B2', 'C2', 'D2'],
    ['A3', 'B3', 'C3', 'D3'],
  ],
})

// Insert a 2x2 table into the page header
const headerSegmentId = fDocument.ensurePageHeader()
const headerTable = fDocument.insertTable(2, 2, {
  segmentId: headerSegmentId,
})
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md) · [`IDocsTableInsertOptions`](https://unpkg.com/@univerjs-pro/docs-table/lib/types/common/insert-table.d.ts)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)

### `FDocument.insertTableFromData`

Inserts a table and fills it with plain text cell data.

```typescript
insertTableFromData(data: string[][], options?: IDocsTableInsertOptions): FDocumentTable | null
```

**Parameters**

* `data` — Required. Two-dimensional cell text data.
* `options` — Optional. Default: `{}`. Optional table id, position, metadata, and layout options.

**Returns**

The inserted FDocumentTable instance, or `null` if the insert table failed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()

// Insert a table with 2 rows and 3 columns, and fill it with data
const table = fDocument.insertTableFromData(
  [
    ['Name', 'Status', 'Version'],
    ['Facade', 'Ready', '0.26.0'],
  ],
  {
    headerRowCount: 1,
  },
)

// Insert a table with data into the page footer
const footerSegmentId = fDocument.ensurePageFooter()
const footerTable = fDocument.insertTableFromData(
  [
    ['Reviewed by', 'Date'],
    ['Docs Team', '2026-07-03'],
  ],
  {
    segmentId: footerSegmentId,
  },
)
```

**Types:** [`FDocumentTable`](https://docs.univer.ai/ko-KR/reference/facade/document-table.md) · [`IDocsTableInsertOptions`](https://unpkg.com/@univerjs-pro/docs-table/lib/types/common/insert-table.d.ts)

**Package:** [`@univerjs-pro/docs-table`](https://docs.univer.ai/ko-KR/reference/packages/plugins/univerjs-pro/docs-table.md) · [Type definitions](https://unpkg.com/@univerjs-pro/docs-table/lib/types/facade/f-document.d.ts)