FUniver

The root Facade API object to interact with Univer. Please use newAPI static method to create a new instance.

APIs

addEvent

Add an event listener

Signature

addEvent<T extends keyof IEventParamConfig>(event: T, callback: (params: IEventParamConfig[T]) => void): IDisposable

Parameters

• event (T) — key of event
• callback ((params: IEventParamConfig[T]) => void) — callback when event triggered

Returns

• (IDisposable) — The Disposable instance, for remove the listener

Examples

// Add life cycle changed event listener
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, (params) => {
  const { stage } = params
  console.log('life cycle changed', params)
})

// Remove the event listener, use `disposable.dispose()`

disposeUnit

Dispose the UniverSheet by the unitId. The UniverSheet would be unload from the application.

Signature

disposeUnit(unitId: string): boolean

Parameters

• unitId (string) — The unit id of the UniverSheet.

Returns

• (boolean) — Whether the Univer instance is disposed successfully.

Examples

const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook?.getId()

if (unitId) {
  univerAPI.disposeUnit(unitId)
}

Enum

Signature

get Enum(): FEnum

Event

Signature

get Event(): FEventName

executeCommand

Execute a command with the given id and parameters.

Signature

executeCommand<P extends object = object, R = boolean>(id: string, params?: P, options?: IExecutionOptions): Promise<R>

Parameters

• id (string) — Identifier of the command.
• params (P) — Parameters of this execution.
• options (IExecutionOptions) — Options of this execution.

Returns

• (Promise<R>) — The result of the execution. It is a boolean value by default which indicates the command is executed.

Examples

univerAPI.executeCommand('sheet.command.set-range-values', {
  value: { v: 'Hello, Univer!' },
  range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 },
})

fireEvent

Fire an event, used in internal only.

Signature

fireEvent<T extends keyof IEventParamConfig>(event: T, params: IEventParamConfig[T]): boolean | undefined

Parameters

• event (T) — key of event
• params (IEventParamConfig[T]) — params of event

Returns

• (boolean | undefined) — should cancel

Examples

this.fireEvent(univerAPI.Event.LifeCycleChanged, params)

getCurrentLifecycleStage

Get the current lifecycle stage.

Signature

getCurrentLifecycleStage(): LifecycleStages

Returns

• (LifecycleStages) — - The current lifecycle stage.

Examples

const stage = univerAPI.getCurrentLifecycleStage()
console.log(stage)

getHooks

Get hooks.

Deprecated use addEvent instead.

Signature

getHooks(): FHooks

Returns

• (FHooks) — FHooks instance

getUserManager

Signature

getUserManager(): FUserManager

loadLocales

Load locales for the given locale.

Signature

loadLocales(locale: string, locales: ILanguagePack): void

Parameters

• locale (string) — - A unique locale identifier.
• locales (ILanguagePack) — - The locales object containing the translations.

Tags

• @description — This method is utilized to load locales, which can be either built-in or custom-defined.

Examples

univerAPI.loadLocales('esES', {
  'Hello World': 'Hola Mundo',
})

newAPI

Create an FUniver instance, if the injector is not provided, it will create a new Univer instance.

Signature

static newAPI(wrapped: Univer | Injector): FUniver

Parameters

• wrapped (Univer | Injector) — - The Univer instance or injector instance.

Returns

• (FUniver) — - The FUniver instance.

Tags

• @static

Examples

const univerAPI = FUniver.newAPI(univer)

newBlob

Create a new blob.

Signature

newBlob(): FBlob

Returns

• (FBlob) — The new blob instance

Examples

const blob = univerAPI.newBlob()

newColor

Create a new color.

Deprecated Deprecated.

Signature

newColor(): ColorBuilder

Returns

• (ColorBuilder) — The new color instance

Examples

const color = univerAPI.newColor()

newParagraphStyle

Create a new paragraph style.

Signature

newParagraphStyle(style?: IParagraphStyle): ParagraphStyleBuilder

Parameters

• style (IParagraphStyle) — - The paragraph style

Returns

• (ParagraphStyleBuilder) — The new paragraph style instance

Examples

const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } })
const paragraphStyle = univerAPI.newParagraphStyle({ textStyle: { ff: 'Arial', fs: 12, it: univerAPI.Enum.BooleanNumber.TRUE, bl: univerAPI.Enum.BooleanNumber.TRUE } })
richText.insertParagraph(paragraphStyle)
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1')
range.setRichTextValueForCell(richText)

newParagraphStyleValue

Create a new paragraph style value.

Signature

newParagraphStyleValue(style?: IParagraphStyle): ParagraphStyleValue

Parameters

• style (IParagraphStyle) — - The paragraph style

Returns

• (ParagraphStyleValue) — The new paragraph style value instance

Examples

const paragraphStyleValue = univerAPI.newParagraphStyleValue()

newRichText

Create a new rich text.

Signature

newRichText(data?: IDocumentData): RichTextBuilder

Parameters

• data (IDocumentData)

Returns

• (RichTextBuilder) — The new rich text instance

Examples

const richText = univerAPI.newRichText({ body: { dataStream: 'Hello World\r\n' } })
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1')
range.setRichTextValueForCell(richText)

newRichTextValue

Create a new rich text value.

Signature

newRichTextValue(data: IDocumentData): RichTextValue

Parameters

• data (IDocumentData) — - The rich text data

Returns

• (RichTextValue) — The new rich text value instance

Examples

const richTextValue = univerAPI.newRichTextValue({ body: { dataStream: 'Hello World\r\n' } })
const range = univerAPI.getActiveWorkbook().getActiveSheet().getRange('A1')
range.setRichTextValueForCell(richTextValue)

newTextDecoration

Create a new text decoration.

Signature

newTextDecoration(decoration?: ITextDecoration): TextDecorationBuilder

Parameters

• decoration (ITextDecoration) — - The text decoration

Returns

• (TextDecorationBuilder) — The new text decoration instance

Examples

const decoration = univerAPI.newTextDecoration()

newTextStyle

Create a new text style.

Signature

newTextStyle(style?: ITextStyle): TextStyleBuilder

Parameters

• style (ITextStyle) — - The text style

Returns

• (TextStyleBuilder) — The new text style instance

Examples

const textStyle = univerAPI.newTextStyle()

newTextStyleValue

Create a new text style value.

Signature

newTextStyleValue(style?: ITextStyle): TextStyleValue

Parameters

• style (ITextStyle) — - The text style

Returns

• (TextStyleValue) — The new text style value instance

Examples

const textStyleValue = univerAPI.newTextStyleValue()

onBeforeCommandExecute

Register a callback that will be triggered before invoking a command.

Deprecated use univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => \{\}) instead.

Signature

onBeforeCommandExecute(callback: CommandListener): IDisposable

Parameters

• callback (CommandListener) — The callback.

Returns

• (IDisposable) — The disposable instance.

onCommandExecuted

Register a callback that will be triggered when a command is invoked.

Deprecated use univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => \{\}) instead.

Signature

onCommandExecuted(callback: CommandListener): IDisposable

Parameters

• callback (CommandListener) — The callback.

Returns

• (IDisposable) — The disposable instance.

redo

Redo an editing on the currently focused document.

Signature

redo(): Promise<boolean>

Returns

• (Promise<boolean>) — redo result

Examples

await univerAPI.redo()

setLocale

Set the current locale.

Signature

setLocale(locale: string): void

Parameters

• locale (string) — - A unique locale identifier.

Examples

univerAPI.setLocale('esES')

syncExecuteCommand

Execute a command with the given id and parameters synchronously.

Signature

syncExecuteCommand<P extends object = object, R = boolean>(id: string, params?: P, options?: IExecutionOptions): R

Parameters

• id (string) — Identifier of the command.
• params (P) — Parameters of this execution.
• options (IExecutionOptions) — Options of this execution.

Returns

• (R) — The result of the execution. It is a boolean value by default which indicates the command is executed.

Examples

univerAPI.syncExecuteCommand('sheet.command.set-range-values', {
  value: { v: 'Hello, Univer!' },
  range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 },
})

toggleDarkMode

Toggle dark mode on or off.

Signature

toggleDarkMode(isDarkMode: boolean): void

Parameters

• isDarkMode (boolean) — - Whether the dark mode is enabled.

Examples

univerAPI.toggleDarkMode(true)

undo

Undo an editing on the currently focused document.

Signature

undo(): Promise<boolean>

Returns

• (Promise<boolean>) — undo result

Examples

await univerAPI.undo()

Util

Signature

get Util(): FUtil