# FDocumentFormula

> Language fallback: requested `zh-CN`; content is `en-US`.

- Human documentation: [https://docs.univer.ai/zh-CN/reference/facade/document-formula](https://docs.univer.ai/zh-CN/reference/facade/document-formula)

- Agent Markdown: [https://docs.univer.ai/zh-CN/reference/facade/document-formula.md](https://docs.univer.ai/zh-CN/reference/facade/document-formula.md)

- Requested language: `zh-CN`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade handle for one inline data formula in a Univer document.

The handle is identified by `rangeId`. It remains usable across recalculation,
but mutating methods return `false` after the underlying custom range is
removed. All writes execute public Doc Formula Commands; this class never
mutates document or Resource state directly.

## Access

Access through:

* [`FDocumentTextRange.replaceWithFormula()`](https://docs.univer.ai/zh-CN/reference/facade/document-text-range.md#replacewithformula)
* [`FDocumentParagraph.insertFormula()`](https://docs.univer.ai/zh-CN/reference/facade/document-paragraph.md#insertformula)
* [`FDocumentParagraph.appendFormula()`](https://docs.univer.ai/zh-CN/reference/facade/document-paragraph.md#appendformula)
* [`FDocument.getFormulas()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#getformulas)
* [`FDocument.getFormula()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#getformula)
* [`FDocument.getFormulaAt()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#getformulaat)
* [`FDocument.insertFormula()`](https://docs.univer.ai/zh-CN/reference/facade/document.md#insertformula)

## Example

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

export function inspectFirstDocFormula(univerAPI: FUniver) {
  const document = univerAPI.getActiveDocument()
  if (!document) throw new Error('No active document')

  const formula = document.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')

  const info = formula.describe()
  if (!info) throw new Error('The formula was removed')
  return info
}
```

## Setup

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

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

### `FDocumentFormula.convertToText`

Converts the formula to its current formatted display text.

The Command resolves the presentation; the Facade does not duplicate
formatting business logic. A stale persisted presentation is permitted
and is converted exactly as displayed. The operation is undoable.

```typescript
convertToText(): boolean
```

**Returns**

Whether conversion committed successfully.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function convertFormula(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')
  if (!formula.convertToText()) {
    throw new Error('No presentation was available to convert')
  }
}
```

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

### `FDocumentFormula.describe`

Returns an agent-friendly snapshot of identity, range, persisted config,
and current presentation.

```typescript
describe(): IDocFormulaInfo | null
```

**Returns**

A detached description, or `null` if either side of the
custom-range/Resource pair no longer exists.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function describeFormulas(univerAPI: FUniver) {
  const formulas = univerAPI.getActiveDocument()?.getFormulas() ?? []
  return formulas.map((formula) => formula.describe()).filter((value) => value !== null)
}
```

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

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

### `FDocumentFormula.getConfig`

Returns a detached copy of the persisted formula configuration.

`lastValue` is the last successful scalar result. It is saved as Host
content, inherits the document's read permissions, and may be stale until
the current calculation session succeeds.

```typescript
getConfig(): IDocFormulaConfig | null
```

**Returns**

The configuration, or `null` when its Resource entry is gone.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function readFormulaConfig(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  const config = formula?.getConfig()
  if (!config) throw new Error('Formula config is unavailable')
  return config
}
```

**Types:** [`IDocFormulaConfig`](https://unpkg.com/@univerjs-pro/docs-formula@1.0.0-rc.0/lib/types/common/type.d.ts)

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

### `FDocumentFormula.getFormula`

Returns the editable formula text from the unit-scoped Doc Formula
Resource.

```typescript
getFormula(): string
```

**Returns**

Formula text, or an empty string when the Resource entry is gone.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function readFormulaText(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')
  return formula.getFormula()
}
```

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

### `FDocumentFormula.getId`

Returns the stable identity shared by the custom range, Resource entry,
Other Formula registration, and this Facade handle.

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

**Returns**

The formula's stable `rangeId`.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function readFormulaId(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')
  return formula.getId()
}
```

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

### `FDocumentFormula.getRange`

Returns the current main-body data-stream range.

The formula occupies exactly one U+FFFC object token internally, so
`endOffset` is exclusive and normally equals `startOffset + 1`.

```typescript
getRange(): IDocFormulaRange | null
```

**Returns**

The live range, or `null` after the custom range is removed.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function readFormulaRange(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  const range = formula?.getRange()
  if (!range) throw new Error('Formula range is unavailable')
  return range
}
```

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

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

### `FDocumentFormula.getResult`

Returns the latest calculated or persisted presentation.

`source: 'calculated'` identifies a live result. During reload or Source
unavailability, the API can return the previous successful value with
`source: 'persisted'` and `stale: true`. Formula errors and timeouts never
overwrite that persisted value.

```typescript
getResult(): IDocFormulaResult | null
```

**Returns**

The current result, or `null` when the formula is not registered.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function readFormulaResult(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  const result = formula?.getResult()
  if (!result) throw new Error('Formula result is unavailable')
  return result
}
```

Wait through the shared Formula facade, then read this result

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

export async function insertAndReadFormula(univerAPI: FUniver) {
  const document = univerAPI.getActiveDocument()
  if (!document) throw new Error('No active document')
  const paragraph = document.getParagraphs()[0]
  if (!paragraph) throw new Error('No target paragraph')

  // Start watching before the write so a fast calculation cannot be missed.
  const applied = univerAPI.getFormula().onCalculationResultApplied(5_000)
  const formula = paragraph.appendFormula('=SUM(1,2,3)')
  if (!formula) throw new Error('Doc Formula insertion failed')

  await applied
  const result = formula.getResult()
  if (!result) throw new Error('Formula result is unavailable')
  return result
}
```

**Types:** [`IDocFormulaResult`](https://unpkg.com/@univerjs-pro/docs-formula@1.0.0-rc.0/lib/types/common/type.d.ts)

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

### `FDocumentFormula.remove`

Removes the formula object and its one-character token.

```typescript
remove(): boolean
```

**Returns**

Whether the remove command committed successfully.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function removeFormula(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')
  if (!formula.remove()) throw new Error('Failed to remove Doc Formula')
}
```

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

### `FDocumentFormula.replaceWithText`

Replaces the formula object with caller-provided plain text.

Use `convertToText()` when the desired text is the current formatted
formula presentation.

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

**Parameters**

* `text` — Required. Plain replacement text.

**Returns**

Whether the replace command committed successfully.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function replaceFormula(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')
  if (!formula.replaceWithText('Total: 42')) {
    throw new Error('Failed to replace Doc Formula')
  }
}
```

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

### `FDocumentFormula.setNumberFormat`

Updates only the explicit number format through a Command.

Passing `undefined` removes the explicit format. This operation preserves
the raw `lastValue`, immediately re-formats the current presentation, and
participates in normal undo/redo and collaboration.

```typescript
setNumberFormat(numberFormat?: { pattern: string; }): boolean
```

**Parameters**

* `numberFormat` — Optional. New format, or `undefined` to inherit/default.

**Returns**

Whether the command committed successfully.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function formatFormula(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')
  if (!formula.setNumberFormat({ pattern: '$#,##0.00' })) {
    throw new Error('Failed to format Doc Formula')
  }
}
```

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

### `FDocumentFormula.update`

Replaces the formula binding through `UpdateDocFormulaCommand`.

The command validates and persists all external Source bindings, clears
the previous `lastValue`, and records one undo item. The caller should
provide every newly selected external Source in `externalReferences`.

```typescript
update(options: IDocFormulaUpdateFacadeOptions): boolean
```

**Parameters**

* `options` — Required. Replacement formula, optional number format, and stable
  external Source bindings.

**Returns**

Whether the command committed successfully.

**Examples**

```ts
import type { FUniver } from '@univerjs/core/facade'
import '@univerjs-pro/docs-formula/facade'
export function updateFormula(univerAPI: FUniver) {
  const formula = univerAPI.getActiveDocument()?.getFormulas()[0]
  if (!formula) throw new Error('No Doc Formula')
  const updated = formula.update({
    formula: '=SUM(1, 2, 3)',
    numberFormat: { pattern: '0.00' },
  })
  if (!updated) throw new Error('Failed to update Doc Formula')
}
```

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

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