API 参考

FDocumentCallout

本 API 页面目前提供英文正文。代码签名与标识符不随界面语言变化。

Facade object for a single docs callout block.

Access

Access through:

Example

TypeScript
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 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.

@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

TypeScript
const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('Important')if (callout) {  console.log(callout.describe())}

Types: IDocsCalloutInfo

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

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

TypeScript
const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('Important')if (callout) {  console.log(callout.getConfig())}

Types: IDocsCalloutConfig

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

FDocumentCallout.getId

Returns the callout block id.

TypeScript
getId(): string

Returns

The callout block range id.

Examples

TypeScript
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 · Type definitions

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

TypeScript
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

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

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

TypeScript
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

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

FDocumentCallout.getText

Returns plain text inside the callout.

TypeScript
getText(): string

Returns

The callout text with block tokens removed.

Examples

TypeScript
const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('Important')if (callout) {  console.log(callout.getText())}

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

FDocumentCallout.remove

Removes this callout block and its content.

TypeScript
remove(): boolean

Returns

Whether the callout block was removed.

Examples

TypeScript
const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('Important')if (callout) {  const success = callout.remove()  console.log(success)}

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

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

TypeScript
const callout = univerAPI.getActiveDocument()?.findCalloutByText('Important')const reset = callout?.resetTextColor() ?? falseconsole.log({ reset })

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

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

TypeScript
const callout = univerAPI.getActiveDocument()?.findCalloutByText('Important')const updated = callout?.setBackgroundColor('#FFF4E5') ?? falseconsole.log({ updated })

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

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

TypeScript
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 · IDocsCalloutBorderStyle

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

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

TypeScript
const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('Important')if (callout) {  const success = callout.setIcon('💡')  console.log(success)}

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

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 · Type definitions

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

TypeScript
const callout = univerAPI.getActiveDocument()?.findCalloutByText('Important')const updated = callout?.setTextColor('#5C3B00') ?? falseconsole.log({ updated })

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

FDocumentCallout.unwrap

Unwraps this callout by removing only the callout block formatting.

TypeScript
unwrap(): boolean

Returns

Whether the callout block formatting was removed.

Examples

TypeScript
const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('Important')if (callout) {  const success = callout.unwrap()  console.log(success)}

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

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

TypeScript
const fDocument = univerAPI.getActiveDocument()const callout = fDocument.findCalloutByText('Important')if (callout) {  const success = callout.updateConfig({ borderRadius: 12 })  console.log(success)}

Types: Partial · IDocsCalloutConfig

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

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.