# FDocumentCallout

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

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

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

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

---

Facade object for a single docs callout block.

## Access

Access through:

* [`FDocument.getCallouts()`](https://docs.univer.ai/reference/facade/document.md#getcallouts)
* [`FDocument.getCallout()`](https://docs.univer.ai/reference/facade/document.md#getcallout)
* [`FDocument.getCalloutAt()`](https://docs.univer.ai/reference/facade/document.md#getcalloutat)
* [`FDocument.findCalloutByText()`](https://docs.univer.ai/reference/facade/document.md#findcalloutbytext)
* [`FDocument.findCallouts()`](https://docs.univer.ai/reference/facade/document.md#findcallouts)
* [`FDocument.insertCallout()`](https://docs.univer.ai/reference/facade/document.md#insertcallout)

## Example

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

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

const callout = fDocument.findCalloutByText('Important')
console.log(callout?.getText())
if (callout) {
  console.log(callout.getStyle())
  callout.setBackgroundColor('#FFF4E5')
  callout.setBorder({ color: '#E6A23C', width: 2 })
  callout.setTextColor('#5C3B00')
  console.log(callout.describe())
}
```

## Setup

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

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

### `FDocumentCallout.describe`

Returns an agent-friendly description of the callout.

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

**Returns**

The callout id, range, text, config, and compact style, or `null` if it no longer exists.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument.findCalloutByText('Important')

if (callout) {
  console.log(callout.describe())
}
```

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

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

### `FDocumentCallout.getConfig`

Returns the normalized callout visual config.

```typescript
getConfig(): IDocsCalloutConfig
```

**Returns**

The callout config, falling back to default config when metadata is missing.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument.findCalloutByText('Important')

if (callout) {
  console.log(callout.getConfig())
}
```

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

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

### `FDocumentCallout.getId`

Returns the callout block id.

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

**Returns**

The callout block range id.

**Examples**

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

// Get the id of the first callout.
if (callouts.length > 0) {
  const callout = callouts[0]
  console.log(callout.getId())
}
```

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

### `FDocumentCallout.getRange`

Returns the callout block range in the document data stream.

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

**Returns**

The callout range, or `null` if it no longer exists.

**Examples**

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

// Get the range of the first callout.
if (callouts.length > 0) {
  const callout = callouts[0]
  console.log(callout.getRange())
}
```

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

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

### `FDocumentCallout.getStyle`

Returns the Callout colors and border as one compact, serializable object.
This is preferable to `getConfig()` for agents that only need appearance and should not modify layout metadata.

```typescript
getStyle(): IDocsCalloutStyle
```

**Returns**

The current background, border, and first effective text color.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument?.findCalloutByText('Important')
if (!callout) {
  throw new Error('Callout not found')
}
const style = callout.getStyle()
console.log(JSON.stringify(style, null, 2))
```

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

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

### `FDocumentCallout.getText`

Returns plain text inside the callout.

```typescript
getText(): string
```

**Returns**

The callout text with block tokens removed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument.findCalloutByText('Important')

if (callout) {
  console.log(callout.getText())
}
```

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

### `FDocumentCallout.remove`

Removes this callout block and its content.

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

**Returns**

Whether the callout block was removed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument.findCalloutByText('Important')

if (callout) {
  const success = callout.remove()
  console.log(success)
}
```

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

### `FDocumentCallout.resetTextColor`

Restores the inherited document text color for all text in this Callout.

```typescript
resetTextColor(): boolean
```

**Returns**

Whether the text style command succeeded.

**Examples**

```ts
const callout = univerAPI.getActiveDocument()?.findCalloutByText('Important')
const reset = callout?.resetTextColor() ?? false
console.log({ reset })
```

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

### `FDocumentCallout.setBackgroundColor`

Sets only the Callout background color through the command pipeline.

```typescript
setBackgroundColor(backgroundColor: string): boolean
```

**Parameters**

* `backgroundColor` — Required. A CSS color value supported by Univer, such as `#FFF4E5`.

**Returns**

Whether the update command succeeded.

**Examples**

```ts
const callout = univerAPI.getActiveDocument()?.findCalloutByText('Important')
const updated = callout?.setBackgroundColor('#FFF4E5') ?? false
console.log({ updated })
```

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

### `FDocumentCallout.setBorder`

Updates one or more border properties as a single undoable Callout config command.
Omitted properties retain their current values.

```typescript
setBorder(border: Partial<IDocsCalloutBorderStyle>): boolean
```

**Parameters**

* `border` — Required. Border color, line style, or width.

**Returns**

Whether the update command succeeded.

**Examples**

```ts
import { DashStyleType } from '@univerjs/core'

const callout = univerAPI.getActiveDocument()?.findCalloutByText('Important')
if (!callout) {
  throw new Error('Callout not found')
}
const updated = callout.setBorder({
  color: '#E6A23C',
  opacity: 0.75,
  style: DashStyleType.DASH,
  width: 2,
})
console.log({ updated, style: callout.getStyle() })
```

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IDocsCalloutBorderStyle`](https://unpkg.com/@univerjs-pro/docs-callout@1.0.0-rc.0/lib/types/facade/types.d.ts)

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

### `FDocumentCallout.setIcon`

Updates only the callout icon.

```typescript
setIcon(icon: string): boolean
```

**Parameters**

* `icon` — Required. The emoji or text icon to display.

**Returns**

Whether the update command succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument.findCalloutByText('Important')

if (callout) {
  const success = callout.setIcon('💡')
  console.log(success)
}
```

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

### `FDocumentCallout.setIconVisible`

Shows or hides the callout icon without changing document paragraph layout.

```typescript
setIconVisible(showIcon: boolean): boolean
```

**Parameters**

* `showIcon` — Required.

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

### `FDocumentCallout.setTextColor`

Applies one text color to all text in this Callout through the document command pipeline.

```typescript
setTextColor(value: string): boolean
```

**Parameters**

* `value` — Required. A CSS color value supported by Univer.

**Returns**

Whether the text style command succeeded.

**Examples**

```ts
const callout = univerAPI.getActiveDocument()?.findCalloutByText('Important')
const updated = callout?.setTextColor('#5C3B00') ?? false
console.log({ updated })
```

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

### `FDocumentCallout.unwrap`

Unwraps this callout by removing only the callout block formatting.

```typescript
unwrap(): boolean
```

**Returns**

Whether the callout block formatting was removed.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument.findCalloutByText('Important')

if (callout) {
  const success = callout.unwrap()
  console.log(success)
}
```

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

### `FDocumentCallout.updateConfig`

Updates the callout layout and icon config.

```typescript
updateConfig(config: Partial<IDocsCalloutConfig>): boolean
```

**Parameters**

* `config` — Required. Partial config, such as icon or border radius.

**Returns**

Whether the update command succeeded.

**Examples**

```ts
const fDocument = univerAPI.getActiveDocument()
const callout = fDocument.findCalloutByText('Important')

if (callout) {
  const success = callout.updateConfig({ borderRadius: 12 })
  console.log(success)
}
```

**Types:** [`Partial`](https://unpkg.com/@typescript/typescript-darwin-arm64@7.0.2/lib/lib.es5.d.ts) · [`IDocsCalloutConfig`](https://unpkg.com/@univerjs-pro/docs-callout@1.0.0-rc.0/lib/types/common/type.d.ts)

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