FUniver

The root Facade API for creating and finding units, subscribing to events, and accessing shared services. In Preset Mode, use the univerAPI returned by createUniver. In Plugin Mode, create it with FUniver.newAPI(univer) after registering the required plugins.

The shared UI methods updateMenuConfig(), createMenu(), and createSubmenu() require @univerjs/ui/facade in plugin mode. See menu configuration by product for Sheets, Docs, Slides, Boards, and PDFs, including the boundary between the Ribbon and the Boards canvas toolbar.

Access

After registering your plugins and importing their Facade entries, call FUniver.newAPI(univer) to obtain univerAPI. With presets, use the univerAPI returned by createUniver.

Setup

Register @univerjs/core or a preset that includes it. In plugin mode, import @univerjs/core/facade. Additional methods below require their listed plugin packages. See Facade setup.

@univerjs/core

FUniver.addEvent

Add an event listener

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

Parameters

• event — Required. key of event
• callback — Required. callback when event triggered

Returns

A disposable that removes the event listener.

Examples

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

Types: IDisposable · IEventParamConfig

Package: @univerjs/core · Type definitions

FUniver.disposeUnit

Disposes the document, workbook, or other Univer unit identified by unitId, unloading it from the application.

disposeUnit(unitId: string): boolean

Parameters

• unitId — Required. The ID of the unit to dispose.

Returns

Whether the Univer instance is disposed successfully.

Examples

const fWorkbook = univerAPI.getActiveWorkbook()const unitId = fWorkbook?.getId()if (unitId) {  univerAPI.disposeUnit(unitId)}

Package: @univerjs/core · Type definitions

FUniver.Enum

Enums exposed by the registered Facade extensions.

readonly Enum: FEnum

Types: FEnum

Package: @univerjs/core · Type definitions

FUniver.Event

Event names to use with addEvent.

readonly Event: FEventName

Types: FEventName

Package: @univerjs/core · Type definitions

FUniver.executeCommand

Execute a command with the given id and parameters.

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

Parameters

• id — Required. Identifier of the command.
• params — Optional. Parameters of this execution.
• options — Optional. Options of this execution.

Returns

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 },})

Types: Promise · IExecutionOptions

Package: @univerjs/core · Type definitions

FUniver.getCurrentLifecycleStage

Get the current lifecycle stage.

getCurrentLifecycleStage(): LifecycleStages

Returns

• The current lifecycle stage.

Examples

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

Types: LifecycleStages

Package: @univerjs/core · Type definitions

FUniver.getCurrentLocale

Get the current locale.

getCurrentLocale(): string

Returns

The current locale identifier.

Examples

const currentLocale = univerAPI.getCurrentLocale()console.log(currentLocale)

Package: @univerjs/core · Type definitions

FUniver.getCurrentRegion

Get the region currently used for locale-sensitive formatting.

getCurrentRegion(): string

Returns

The current region identifier.

Examples

const currentRegion = univerAPI.getCurrentRegion()console.log(currentRegion)

Package: @univerjs/core · Type definitions

FUniver.getCurrentTheme

Get the theme currently used by Univer.

getCurrentTheme(): Theme

Returns

The current theme.

Examples

const theme = univerAPI.getCurrentTheme()console.log(theme.primary[600])

Types: Theme

Package: @univerjs/core · Type definitions

FUniver.getLocales

Get the locales for the current locale.

getLocales(): ILanguagePack | undefined

Returns

The locales object for the current locale, it returns undefined if the locales is not loaded.

Examples

const locales = univerAPI.getLocales()console.log(locales)

Types: ILanguagePack

Package: @univerjs/core · Type definitions

FUniver.getUserManager

Gets the facade for reading the current user.

getUserManager(): FUserManager

Returns

The user manager facade.

Examples

const user = univerAPI.getUserManager().getCurrentUser()

Types: FUserManager

Package: @univerjs/core · Type definitions

FUniver.isDarkMode

Whether Univer is currently using dark mode.

isDarkMode(): boolean

Returns

Whether dark mode is enabled.

Examples

const darkMode = univerAPI.isDarkMode()

Package: @univerjs/core · Type definitions

FUniver.loadLocales

Load locales for the given locale.

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

Parameters

• locale — Required. A unique locale identifier.
• locales — Required. The locales object containing the translations.

Examples

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

Types: ILanguagePack

Package: @univerjs/core · Type definitions

FUniver.newAPI

Creates a Facade API instance for an existing Univer instance or its injector.

static newAPI(wrapped: Univer | Injector): FUniver

Parameters

• wrapped — Required. The Univer instance or injector instance.

Returns

• The FUniver instance.

Examples

const univerAPI = FUniver.newAPI(univer)

Types: FUniver · Univer · Injector

Package: @univerjs/core · Type definitions

FUniver.newBlob

Create a new blob.

newBlob(): FBlob

Returns

The new blob instance

Examples

const blob = univerAPI.newBlob()

Types: FBlob

Package: @univerjs/core · Type definitions

FUniver.newParagraphStyle

Create a new paragraph style.

This is an advanced document-model API. Application and agent code should normally use newRichText().paragraph({ ... }).

newParagraphStyle(style?: IParagraphStyle): ParagraphStyleBuilder

Parameters

• style — Optional. The paragraph style

Returns

The new paragraph style instance

Types: ParagraphStyleBuilder · IParagraphStyle

Package: @univerjs/core · Type definitions

FUniver.newParagraphStyleValue

Create a new paragraph style value.

newParagraphStyleValue(style?: IParagraphStyle): ParagraphStyleValue

Parameters

• style — Optional. The paragraph style

Returns

The new paragraph style value instance

Examples

const paragraphStyleValue = univerAPI.newParagraphStyleValue()

Types: ParagraphStyleValue · IParagraphStyle

Package: @univerjs/core · Type definitions

FUniver.newRichText

Create a new rich text.

newRichText(): RichTextBuilder

Returns

The new rich text instance

Examples

const richText = univerAPI  .newRichText()  .text('Read ')  .link('Univer documentation', 'https://docs.univer.ai')  .text(' for details.')

Types: RichTextBuilder

Package: @univerjs/core · Type definitions

FUniver.newRichTextFromDocumentData

Create a rich-text builder from raw Univer document data.

This is an advanced integration escape hatch for importers and adapters. Application and agent code should use the fluent builder returned by newRichText().

newRichTextFromDocumentData(data: IDocumentData): RichTextBuilder

Parameters

• data — Required. Raw Univer document data.

Returns

A rich-text builder initialized with the supplied document data.

Types: RichTextBuilder · IDocumentData

Package: @univerjs/core · Type definitions

FUniver.newRichTextValue

Create a new rich text value.

This is an advanced integration escape hatch for callers that already own Univer document data. Application and agent code should prefer the fluent value returned by newRichText().

newRichTextValue(data: IDocumentData): RichTextValue

Parameters

• data — Required. The raw Univer document data.

Returns

The new rich text value instance

Types: RichTextValue · IDocumentData

Package: @univerjs/core · Type definitions

FUniver.newTextDecoration

Create a new text decoration.

newTextDecoration(decoration?: ITextDecoration): TextDecorationBuilder

Parameters

• decoration — Optional. The text decoration

Returns

The new text decoration instance

Examples

const decoration = univerAPI.newTextDecoration()

Types: TextDecorationBuilder · ITextDecoration

Package: @univerjs/core · Type definitions

FUniver.newTextStyle

Create a new text style.

newTextStyle(style?: ITextStyle): TextStyleBuilder

Parameters

• style — Optional. The text style

Returns

The new text style instance

Examples

const textStyle = univerAPI.newTextStyle()

Types: TextStyleBuilder · ITextStyle

Package: @univerjs/core · Type definitions

FUniver.newTextStyleValue

Create a new text style value.

newTextStyleValue(style?: ITextStyle): TextStyleValue

Parameters

• style — Optional. The text style

Returns

The new text style value instance

Examples

const textStyleValue = univerAPI.newTextStyleValue()

Types: TextStyleValue · ITextStyle

Package: @univerjs/core · Type definitions

FUniver.redo

Redo an editing on the currently focused document.

redo(): Promise<boolean>

Returns

redo result

Examples

await univerAPI.redo()

Types: Promise

Package: @univerjs/core · Type definitions

FUniver.registerEventHandler

Registers a factory for the subscription that produces an event. The factory starts when listeners exist and its subscription is disposed when the last listener is removed.

registerEventHandler: (event: string, handler: () => IDisposable | Subscription) => IDisposable

Returns

A disposable that unregisters the factory and disposes its active subscription.

Types: IDisposable · Subscription

Package: @univerjs/core · Type definitions

FUniver.setDirection

Set the current layout direction.

setDirection(direction: 'ltr' | 'rtl'): void

Parameters

• direction — Required. The layout direction.

Examples

univerAPI.setDirection('rtl')

Package: @univerjs/core · Type definitions

FUniver.setLocale

Set the current locale.

setLocale(locale: string): void

Parameters

• locale — Required. A unique locale identifier.

Examples

univerAPI.setLocale('esES')

Package: @univerjs/core · Type definitions

FUniver.setRegion

Set the region used for locale-sensitive formatting.

setRegion(region: string): void

Parameters

• region — Required. A unique region identifier.

Examples

univerAPI.setRegion('enUS')

Package: @univerjs/core · Type definitions

FUniver.setTheme

Set the theme used by Univer.

setTheme(theme: Theme): void

Parameters

• theme — Required. The complete theme to use.

Examples

import { defaultTheme } from '@univerjs/themes'univerAPI.setTheme({  ...defaultTheme,  primary: {    ...defaultTheme.primary,    600: '#274fee',  },})

Types: Theme

Package: @univerjs/core · Type definitions

FUniver.syncExecuteCommand

Execute a command with the given id and parameters synchronously.

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

Parameters

• id — Required. Identifier of the command.
• params — Optional. Parameters of this execution.
• options — Optional. Options of this execution.

Returns

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 },})

Types: IExecutionOptions

Package: @univerjs/core · Type definitions

FUniver.toggleDarkMode

Toggle dark mode on or off.

toggleDarkMode(isDarkMode: boolean): void

Parameters

• isDarkMode — Required. Whether the dark mode is enabled.

Examples

univerAPI.toggleDarkMode(true)

Package: @univerjs/core · Type definitions

FUniver.undo

Undo an editing on the currently focused document.

undo(): Promise<boolean>

Returns

undo result

Examples

await univerAPI.undo()

Types: Promise

Package: @univerjs/core · Type definitions

FUniver.Util

Utility functions exposed by the registered Facade extensions.

readonly Util: FUtil

Types: FUtil

Package: @univerjs/core · Type definitions

@univerjs/docs

FUniver.createDocument

Create a new document and get the API handler of that document.

createDocument(data: Partial<IDocumentData>, options?: ICreateUnitOptions): FDocument

Parameters

• data — Required. The snapshot of the document.
• options — Optional. The options of creating the document.

Returns

The document API instance.

Examples

const fDocument = univerAPI.createDocument({ id: 'document-01', title: 'Document1' })console.log(fDocument)

Types: FDocument · Partial · IDocumentData · ICreateUnitOptions

Package: @univerjs/docs · Type definitions

FUniver.getActiveDocument

Get the currently focused Univer document.

getActiveDocument(): FDocument | null

Returns

The currently focused Univer document API instance, or null if there is no focused Univer document.

Examples

const fDocument = univerAPI.getActiveDocument()console.log(fDocument)

Types: FDocument

Package: @univerjs/docs · Type definitions

FUniver.getDocument

Get the document API handler by the document id.

getDocument(id: string): FDocument | null

Parameters

• id — Required. The document id.

Returns

The document API instance corresponding to the document id, or null if not found.

Examples

const fDocument = univerAPI.getDocument('document-01')console.log(fDocument)

Types: FDocument

Package: @univerjs/docs · Type definitions

@univerjs/engine-formula

FUniver.getFormula

Gets the formula engine facade for calculation, parsing, and dependency queries.

getFormula(): FFormula

Returns

The formula engine facade.

Examples

const formula = univerAPI.getFormula()await formula.onCalculationResultApplied()

Types: FFormula

Package: @univerjs/engine-formula · Type definitions

@univerjs/network

FUniver.createSocket

Set WebSocket URL for WebSocketService

createSocket(url: string): ISocket

Parameters

• url — Required. WebSocket URL

Returns

WebSocket instance

Examples

// Replace the URL with the address of your own WebSocket serviceconst ws = univerAPI.createSocket('wss://47.100.177.253:8449/ws')ws.open$.subscribe(() => {  console.log('websocket opened')  ws.send('hello')})ws.message$.subscribe((message) => {  console.log('websocket message', message)  const content = JSON.parse(message.data).content  if (!content.includes('command')) {    return  }  const commandInfo = JSON.parse(content)  const { command, options } = commandInfo  const { id, params } = command  // Upon receiving collaborative data, it is locally saved  univerAPI.executeCommand(id, params, options)})ws.close$.subscribe(() => {  console.log('websocket closed')})ws.error$.subscribe((error) => {  console.log('websocket error', error)})univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, type, params, options }) => {  // Only synchronize local mutations  if (    type !== univerAPI.Enum.CommandType.MUTATION ||    options?.fromCollab ||    options?.onlyLocal ||    id === 'doc.mutation.rich-text-editing'  ) {    return  }  const commandInfo = JSON.stringify({    command: { id, type, params },    options: { fromCollab: true },  })  ws.send(commandInfo)})

Types: ISocket

Package: @univerjs/network · Type definitions

FUniver.getNetwork

Get the network API of Univer, with the help of which you can send HTTP requests.

getNetwork(): FNetwork

Types: FNetwork

Package: @univerjs/network · Type definitions

@univerjs/sheets

FUniver.createWorkbook

Create a new spreadsheet and get the API handler of that spreadsheet.

createWorkbook(data: Partial<IWorkbookData>, options?: ICreateUnitOptions): FWorkbook

Parameters

• data — Required. The snapshot of the spreadsheet.
• options — Optional. The options of creating the spreadsheet.

Returns

The spreadsheet API instance.

Examples

const fWorkbook = univerAPI.createWorkbook({ id: 'workbook-01', name: 'Workbook1' })console.log(fWorkbook)

Add you can make the workbook not as the active workbook by setting options:

const fWorkbook = univerAPI.createWorkbook(  { id: 'workbook-01', name: 'Workbook1' },  { makeCurrent: false },)console.log(fWorkbook)

Types: FWorkbook · Partial · IWorkbookData · ICreateUnitOptions

Package: @univerjs/sheets · Type definitions

FUniver.getActiveSheet

Get the active sheet.

getActiveSheet(): { workbook: FWorkbook; worksheet: FWorksheet; } | null

Returns

The active sheet.

Examples

const target = univerAPI.getActiveSheet()if (!target) throw new Error('target is not available')const { workbook, worksheet } = targetconsole.log(workbook, worksheet)

Types: FWorkbook · FWorksheet

Package: @univerjs/sheets · Type definitions

FUniver.getActiveWorkbook

Get the currently focused Univer spreadsheet.

getActiveWorkbook(): FWorkbook | null

Returns

The currently focused Univer spreadsheet API instance, or null if there is no active spreadsheet.

Examples

const fWorkbook = univerAPI.getActiveWorkbook()console.log(fWorkbook)

Types: FWorkbook

Package: @univerjs/sheets · Type definitions

FUniver.getSheetCommandTarget

Get the target of the sheet.

getSheetCommandTarget(params?: { unitId?: string; subUnitId?: string; sheetId?: string; }): { workbook: FWorkbook; worksheet: FWorksheet; unitId: string; subUnitId: string; } | null

Parameters

• params — Optional. Default: {}. Target IDs from the command parameters. Omitted IDs use the current workbook and active sheet.

Returns

The resolved workbook, worksheet, and their IDs, or null if the target cannot be resolved.

Examples

univerAPI.addEvent(univerAPI.Event.CommandExecuted, (event) => {  const target = univerAPI.getSheetCommandTarget(event.params)  if (!target) return  const { workbook, worksheet } = target  console.log(workbook, worksheet)})

Types: FWorkbook · FWorksheet

Package: @univerjs/sheets · Type definitions

FUniver.getWorkbook

Get the spreadsheet API handler by the spreadsheet id.

getWorkbook(id: string): FWorkbook | null

Parameters

• id — Required. The spreadsheet id.

Returns

The spreadsheet API instance corresponding to the spreadsheet id, or null if not found.

Examples

const fWorkbook = univerAPI.getWorkbook('workbook-01')console.log(fWorkbook)

Types: FWorkbook

Package: @univerjs/sheets · Type definitions

FUniver.setFreezeSync

Set whether to enable synchronize the frozen state to other users in real-time collaboration.

setFreezeSync(enabled: boolean): void

Parameters

• enabled — Required. Whether to enable freeze sync. Default is true.

Examples

// Disable freeze syncuniverAPI.setFreezeSync(false)

Package: @univerjs/sheets · Type definitions

@univerjs/sheets-crosshair-highlight

FUniver.getCrosshairHighlightEnabled

Get whether the crosshair highlight is enabled.

getCrosshairHighlightEnabled(): boolean

Returns

Whether the crosshair highlight is enabled

Examples

console.log(univerAPI.getCrosshairHighlightEnabled())

Package: @univerjs/sheets-crosshair-highlight · Type definitions

FUniver.setCrosshairHighlightEnabled

Enable or disable crosshair highlight.

setCrosshairHighlightEnabled(enabled: boolean): FUniver

Parameters

• enabled — Required. Whether to enable the crosshair highlight

Returns

The FUniver instance for chaining

Examples

univerAPI.setCrosshairHighlightEnabled(true)

Types: FUniver

Package: @univerjs/sheets-crosshair-highlight · Type definitions

@univerjs/sheets-data-validation

FUniver.newDataValidation

Creates a new instance of FDataValidationBuilder

newDataValidation(): FDataValidationBuilder

Returns

A new instance of the FDataValidationBuilder class

Examples

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Create a new data validation rule that requires a number between 1 and 10 fot the range A1:B10const fRange = fWorksheet.getRange('A1:B10')const rule = univerAPI  .newDataValidation()  .requireNumberBetween(1, 10)  .setOptions({    allowBlank: true,    showErrorMessage: true,    error: 'Please enter a number between 1 and 10',  })  .build()fRange.setDataValidation(rule)

Types: FDataValidationBuilder

Package: @univerjs/sheets-data-validation · Type definitions

@univerjs/sheets-drawing-ui

FUniver.registerURLImageDownloader

Register a custom image downloader for URL images

registerURLImageDownloader(downloader: (url: string) => Promise<string>): IDisposable

Parameters

• downloader — Required. The downloader function that takes a URL and returns a base64 string

Returns

A disposable object to unregister the downloader

Examples

const disposable = univerAPI.registerURLImageDownloader(async (url) => {  const response = await fetch(url)  const blob = await response.blob()  const base64 = await new Promise<string>((resolve) => {    const reader = new FileReader()    reader.onloadend = () => resolve(reader.result as string)    reader.readAsDataURL(blob)  })  return base64})

Types: IDisposable · Promise

Package: @univerjs/sheets-drawing-ui · Type definitions

@univerjs/sheets-find-replace

FUniver.createTextFinderAsync

Create a text-finder for the current univer.

createTextFinderAsync(text: string): Promise<FTextFinder | null>

Parameters

• text — Required. The text to find.

Returns

A promise that resolves to the text-finder instance.

Examples

// Assume the current sheet is empty sheet.const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')// Set some values to the range A1:D10.const fRange = fWorksheet.getRange('A1:D10')fRange.setValues([  [1, 2, 3, 4],  [2, 3, 4, 5],  [3, 4, 5, 6],  [4, 5, 6, 7],  [5, 6, 7, 8],  [6, 7, 8, 9],  [7, 8, 9, 10],  [8, 9, 10, 11],  [9, 10, 11, 12],  [10, 11, 12, 13],])// Create a text-finder to find the text '5'.const textFinder = await univerAPI.createTextFinderAsync('5')// Find all cells that contain the text '5'.const matchCells = textFinder.findAll()matchCells.forEach((cell) => {  console.log(cell.getA1Notation()) // D2, C3, B4, A5})

Types: FTextFinder · Promise

Package: @univerjs/sheets-find-replace · Type definitions

@univerjs/sheets-formula-ui

FUniver.showRangeSelectorDialog

Shows the range selector dialog.

showRangeSelectorDialog(opts: IShowRangeSelectorDialogOptions): Promise<IUnitRangeName[]>

Parameters

• opts — Required. The options of the range selector dialog.

Returns

The selected ranges.

Examples

const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const unitId = fWorkbook.getId()await univerAPI.showRangeSelectorDialog({  unitId,  subUnitId: fWorksheet.getSheetId(),  initialValue: [    {      unitId,      sheetName: fWorksheet.getSheetName(),      range: fWorksheet.getRange('A1:B2').getRange(),    },  ],  maxRangeCount: 2,  supportAcrossSheet: true,  callback: (ranges, isCancel) => {    // Handle the selected ranges    console.log(ranges, isCancel)  },})

Types: IUnitRangeName · Promise · IShowRangeSelectorDialogOptions

Package: @univerjs/sheets-formula-ui · Type definitions

@univerjs/sheets-ui

FUniver.getProtectedRangeShadowStrategy

Get the current global strategy for showing the protected range shadow.

getProtectedRangeShadowStrategy(): 'always' | 'non-editable' | 'non-viewable' | 'none'

Returns

The current shadow strategy

Examples

const currentStrategy = univerAPI.getProtectedRangeShadowStrategy()console.log(currentStrategy) // 'none', 'always', 'non-editable', or 'non-viewable'

Package: @univerjs/sheets-ui · Type definitions

FUniver.getProtectedRangeShadowStrategy$

Get an observable of the global strategy for showing the protected range shadow. This allows you to listen for strategy changes across all workbooks.

getProtectedRangeShadowStrategy$(): Observable<'always' | 'non-editable' | 'non-viewable' | 'none'>

Returns

An observable that emits the current shadow strategy

Examples

const subscription = univerAPI.getProtectedRangeShadowStrategy$().subscribe((strategy) => {  console.log('Global strategy changed to:', strategy)  // Update UI or perform other actions})// Later, unsubscribe to clean upsubscription.unsubscribe()

Types: Observable

Package: @univerjs/sheets-ui · Type definitions

FUniver.pasteIntoSheet

Paste clipboard data or custom data into the active sheet at the current selection position.

pasteIntoSheet(htmlContent?: string, textContent?: string, files?: File[]): Promise<boolean>

Parameters

• htmlContent — Optional. The HTML content from the clipboard or custom data.
• textContent — Optional. The plain text content from the clipboard or custom data.
• files — Optional. The files from the clipboard or custom data.

Returns

A promise that resolves to true if the paste operation was successful, otherwise false.

Examples

// Listen for the paste event and call the pasteIntoSheet methoddocument.addEventListener('paste', async (event) => {  const htmlContent = event.clipboardData.getData('text/html')  const textContent = event.clipboardData.getData('text/plain')  const files = Array.from(event.clipboardData.items)    .map((item) => (item.kind === 'file' ? item.getAsFile() : undefined))    .filter(Boolean)  await univerAPI.pasteIntoSheet(htmlContent, textContent, files)})// Or paste custom datauniverAPI.pasteIntoSheet('<b>Bold Text</b>', 'Bold Text')

Types: Promise · File

Package: @univerjs/sheets-ui · Type definitions

FUniver.registerCellCustomRender

Register cell custom render.

registerCellCustomRender(customRender: Nullable<ICellCustomRender[]>, effect?: InterceptorEffectEnum, priority?: number): IDisposable

Parameters

• customRender — Required. Custom render function.
• effect — Optional. Default: InterceptorEffectEnum.Style. The effect of the interceptor, style or value.
• priority — Optional. The priority of the interceptor.

Types: IDisposable · Nullable · ICellCustomRender · InterceptorEffectEnum

Package: @univerjs/sheets-ui · Type definitions

FUniver.registerSheetColumnHeaderExtension

Register sheet column header render extensions.

registerSheetColumnHeaderExtension(unitId: string, ...extensions: SheetExtension[]): IDisposable

Parameters

• unitId — Required. The unit id of the spreadsheet.
• extensions — Required. The extensions to register.

Returns

The disposable instance.

Types: IDisposable · SheetExtension

Package: @univerjs/sheets-ui · Type definitions

FUniver.registerSheetMainExtension

Register sheet main render extensions.

registerSheetMainExtension(unitId: string, ...extensions: SheetExtension[]): IDisposable

Parameters

• unitId — Required. The unit id of the spreadsheet.
• extensions — Required. The extensions to register.

Returns

The disposable instance.

Types: IDisposable · SheetExtension

Package: @univerjs/sheets-ui · Type definitions

FUniver.registerSheetRowHeaderExtension

Register sheet row header render extensions.

registerSheetRowHeaderExtension(unitId: string, ...extensions: SheetExtension[]): IDisposable

Parameters

• unitId — Required. The unit id of the spreadsheet.
• extensions — Required. The extensions to register.

Returns

The disposable instance.

Types: IDisposable · SheetExtension

Package: @univerjs/sheets-ui · Type definitions

FUniver.setPermissionDialogVisible

Set visibility of unauthorized pop-up window

setPermissionDialogVisible(visible: boolean): void

Parameters

• visible — Required. visibility of unauthorized pop-up window

Examples

const univerAPI = FUniver.newAPI(univer)univerAPI.setPermissionDialogVisible(false)

Package: @univerjs/sheets-ui · Type definitions

FUniver.setProtectedRangeShadowStrategy

Set the global strategy for showing the protected range shadow. This will apply to all workbooks in the current Univer instance.

setProtectedRangeShadowStrategy(strategy: 'always' | 'non-editable' | 'non-viewable' | 'none'): void

Parameters

• strategy — Required. The shadow strategy to apply
• 'always': Show shadow for all protected ranges
• 'non-editable': Only show shadow for ranges that cannot be edited
• 'non-viewable': Only show shadow for ranges that cannot be viewed
• 'none': Never show shadow for protected ranges

Examples

// Always show shadows (default)univerAPI.setProtectedRangeShadowStrategy('always')// Only show shadows for non-editable rangesuniverAPI.setProtectedRangeShadowStrategy('non-editable')// Only show shadows for non-viewable rangesuniverAPI.setProtectedRangeShadowStrategy('non-viewable')// Never show shadowsuniverAPI.setProtectedRangeShadowStrategy('none')

Package: @univerjs/sheets-ui · Type definitions

@univerjs/thread-comment

FUniver.createCommentAsync

Creates a root comment on a drawing, page element, page position, or Base record anchor. For a sheet-cell comment, use FRange.addCommentAsync; for document text, use FDocumentTextRange.createCommentAsync.

createCommentAsync(options: ThreadComment.ICreateThreadCommentOptions): Promise<boolean>

Parameters

• options — Required. Comment content, owner IDs, stable anchor, and optional caller-controlled IDs.

Returns

true when the command succeeds; otherwise, false.

Throws

If the content is empty or the anchor is invalid.

Examples

const workbook = univerAPI.getActiveWorkbook()if (!workbook) {  throw new Error('No active workbook')}const sheet = workbook.getActiveSheet()const image = sheet.getImages()[0]if (!image) {  throw new Error('No image to comment on')}await univerAPI.createCommentAsync({  unitId: workbook.getId(),  subUnitId: sheet.getSheetId(),  anchor: {    kind: univerAPI.Enum.ThreadCommentAnchorKind.SHEET_DRAWING,    elementId: image.getId(),  },  content: 'Verify this value.',})

Types: Promise · ThreadComment.ICreateThreadCommentOptions

Package: @univerjs/thread-comment · Type definitions

FUniver.deleteCommentAsync

Deletes one comment, or the complete root and reply tree when deleteThread is true.

deleteCommentAsync(options: ThreadComment.IDeleteThreadCommentOptions): Promise<boolean>

Parameters

• options — Required. Owning IDs, target comment ID, and the optional whole-thread flag.

Returns

true when the delete command succeeds; otherwise, false.

Examples

const [comment] = univerAPI.getComments({ resolved: false })if (comment) {  await univerAPI.deleteCommentAsync({    unitId: comment.unitId,    subUnitId: comment.subUnitId,    commentId: comment.root.id,    deleteThread: true,  })}

Types: Promise · ThreadComment.IDeleteThreadCommentOptions

Package: @univerjs/thread-comment · Type definitions

FUniver.getComments

Queries locally loaded threads by unit, subunit, anchor kind, author, or resolution state.

getComments(query?: ThreadComment.IThreadCommentQuery): ThreadComment.IFacadeThreadCommentInfo[]

Parameters

• query — Optional. Default: {}. Optional filters. Omit the argument to return every locally loaded thread.

Returns

Matching root threads, their replies, anchor kinds, parsed anchors, and related user IDs.

Examples

const workbook = univerAPI.getActiveWorkbook()if (!workbook) {  throw new Error('No active workbook')}const openAgentReviews = univerAPI.getComments({  unitIds: [workbook.getId()],  authorIds: ['agent-reviewer'],  anchorKinds: [univerAPI.Enum.ThreadCommentAnchorKind.SHEET_DRAWING],  resolved: false,})const sheetCellReviews = univerAPI.getComments({  anchorKinds: [univerAPI.Enum.ThreadCommentAnchorKind.SHEET_CELL],})

Types: ThreadComment.IFacadeThreadCommentInfo · ThreadComment.IThreadCommentQuery

Package: @univerjs/thread-comment · Type definitions

FUniver.listCommentsAsync

Synchronizes locally known threads from the configured datasource, then applies the same filters as getComments. This method does not discover thread IDs that have never been loaded into the model.

listCommentsAsync(query?: ThreadComment.IThreadCommentQuery): Promise<ThreadComment.IFacadeThreadCommentInfo[]>

Parameters

• query — Optional. Default: {}. Optional filters. Omit the argument to synchronize and return every known thread.

Returns

A promise resolving to the synchronized matching threads.

Examples

const workbook = univerAPI.getActiveWorkbook()if (!workbook) {  throw new Error('No active workbook')}const comments = await univerAPI.listCommentsAsync({  unitIds: [workbook.getId()],  anchorKinds: [univerAPI.Enum.ThreadCommentAnchorKind.SHEET_DRAWING],  resolved: false,})comments.forEach(({ root, children, anchorKind, anchor }) => {  console.log(root.id, children.length, anchorKind, anchor)})

Types: ThreadComment.IFacadeThreadCommentInfo · Promise · ThreadComment.IThreadCommentQuery

Package: @univerjs/thread-comment · Type definitions

FUniver.replyCommentAsync

Adds a reply to an existing root thread.

replyCommentAsync(options: ThreadComment.IReplyThreadCommentOptions): Promise<boolean>

Parameters

• options — Required. Reply content and the owning unit, subunit, and thread IDs.

Returns

true when the reply is created. Returns false when the root thread is not loaded or the command fails.

Throws

If the content is empty.

Examples

const [thread] = univerAPI.getComments({ resolved: false })if (thread) {  await univerAPI.replyCommentAsync({    unitId: thread.unitId,    subUnitId: thread.subUnitId,    threadId: thread.threadId,    content: 'Verified.',  })}

Types: Promise · ThreadComment.IReplyThreadCommentOptions

Package: @univerjs/thread-comment · Type definitions

FUniver.resolveCommentAsync

Resolves a thread. Pass resolved: false to reopen it.

resolveCommentAsync(options: ThreadComment.IResolveThreadCommentOptions): Promise<boolean>

Parameters

• options — Required. Owning IDs, a comment ID in the thread, and the desired resolution state.

Returns

true when the resolve command succeeds; otherwise, false.

Examples

const [comment] = univerAPI.getComments({ resolved: false })if (comment) {  await univerAPI.resolveCommentAsync({    unitId: comment.unitId,    subUnitId: comment.subUnitId,    commentId: comment.root.id,  })}

Types: Promise · ThreadComment.IResolveThreadCommentOptions

Package: @univerjs/thread-comment · Type definitions

FUniver.updateCommentAsync

Updates the content or attachments of an existing root comment or reply.

updateCommentAsync(options: ThreadComment.IUpdateThreadCommentOptions): Promise<boolean>

Parameters

• options — Required. Updated content and the owning unit, subunit, and comment IDs.

Returns

true when the update command succeeds; otherwise, false.

Throws

If the content is empty.

Examples

const [comment] = univerAPI.getComments({ resolved: false })if (comment) {  await univerAPI.updateCommentAsync({    unitId: comment.unitId,    subUnitId: comment.subUnitId,    commentId: comment.root.id,    content: 'Updated review result.',  })}

Types: Promise · ThreadComment.IUpdateThreadCommentOptions

Package: @univerjs/thread-comment · Type definitions

@univerjs/ui

FUniver.addFonts

Append custom fonts to the font list.

addFonts(fonts: IFontConfig[]): void

Parameters

• fonts — Required. The array of font configurations to add.

Examples

univerAPI.addFonts([  {    value: 'CustomFont1',    label: 'Custom Font 1',    category: 'sans-serif',  },  {    value: 'CustomFont2',    label: 'Custom Font 2',    category: 'serif',  },])

Types: IFontConfig

Package: @univerjs/ui · Type definitions

FUniver.copy

Copy the current selected content of the currently focused unit into your system clipboard.

copy(): Promise<boolean>

Returns

whether the copy operation is successful

Examples

// Prevent failure due to loss of focus when executing copy and paste code in the console,// this example listens for the cell click event and executes the copy and paste code.univerAPI.addEvent(univerAPI.Event.CellClicked, async (params) => {  const fWorkbook = univerAPI.getActiveWorkbook()  const fWorksheet = fWorkbook.getSheetByName('Sheet1')  if (!fWorksheet) return  // Copy the range A1:B2 to the clipboard  const fRange = fWorksheet.getRange('A1:B2')  fRange.activate().setValues([    [1, 2],    [3, 4],  ])  await univerAPI.copy()  // Paste the copied content to the range C1:D2  const fRange2 = fWorksheet.getRange('C1')  fRange2.activate()  await univerAPI.paste()  // Check the pasted content  console.log(fWorksheet.getRange('C1:D2').getValues()) // [[1, 2], [3, 4]]})

Types: Promise

Package: @univerjs/ui · Type definitions

FUniver.createMenu

Create a menu build object. You can insert new menus into the UI.

createMenu(menuItem: IFacadeMenuItem): FMenu

Parameters

• menuItem — Required. the menu item

Returns

the FMenu object

Examples

// Univer Icon can be viewed at https://docs.univer.ai/iconsimport { SmileIcon } from '@univerjs/icons'// Create a custom menu with an univer iconuniverAPI.registerComponent('custom-menu-icon', SmileIcon)univerAPI  .createMenu({    id: 'custom-menu',    icon: 'custom-menu-icon',    title: 'Custom Menu',    tooltip: 'Custom Menu Tooltip',    action: () => {      console.log('Custom Menu Clicked')    },  })  .appendTo('ribbon.start.others')// Or// Create a custom menu with an image iconuniverAPI.registerComponent('custom-menu-icon', () => {  return (    <img      src="https://avatars.githubusercontent.com/u/61444807?s=48&v=4"      alt=""      style={{ width: '16px', height: '16px' }}    />  )})univerAPI  .createMenu({    id: 'custom-menu',    icon: 'custom-menu-icon',    title: 'Custom Menu',    tooltip: 'Custom Menu Tooltip',    action: () => {      console.log('Custom Menu Clicked')    },  })  .appendTo('ribbon.start.others')// Or// Create a custom menu without an iconuniverAPI  .createMenu({    id: 'custom-menu',    title: 'Custom Menu',    tooltip: 'Custom Menu Tooltip',    action: () => {      console.log('Custom Menu Clicked')    },  })  .appendTo('ribbon.start.others')

Types: FMenu · IFacadeMenuItem

Package: @univerjs/ui · Type definitions

FUniver.createSubmenu

Create a menu that contains submenus, and later you can append this menu and its submenus to the UI.

createSubmenu(submenuItem: IFacadeSubmenuItem): FSubmenu

Parameters

• submenuItem — Required. the submenu item

Returns

the FSubmenu object

Examples

// Create two leaf menus.const menu1 = univerAPI.createMenu({  id: 'submenu-nested-1',  title: 'Item 1',  action: () => {    console.log('Item 1 clicked')  },})const menu2 = univerAPI.createMenu({  id: 'submenu-nested-2',  title: 'Item 2',  action: () => {    console.log('Item 2 clicked')  },})// Add the leaf menus to a submenu.const submenu = univerAPI  .createSubmenu({ id: 'submenu-nested', title: 'Nested Submenu' })  .addSubmenu(menu1)  .addSeparator()  .addSubmenu(menu2)// Create a root submenu append to the `contextMenu.others` section.univerAPI  .createSubmenu({ id: 'custom-submenu', title: 'Custom Submenu' })  .addSubmenu(submenu)  .appendTo('contextMenu.others')

Types: FSubmenu · IFacadeSubmenuItem

Package: @univerjs/ui · Type definitions

FUniver.getComponentManager

Get the component manager

getComponentManager(): ComponentManager

Returns

The component manager

Examples

const componentManager = univerAPI.getComponentManager()console.log(componentManager)

Types: ComponentManager

Package: @univerjs/ui · Type definitions

FUniver.getShortcut

Get the Shortcut handler to interact with Univer's shortcut functionalities.

getShortcut(): FShortcut

Returns

the FShortcut object

Examples

const fShortcut = univerAPI.getShortcut()// Disable shortcuts of UniverfShortcut.disableShortcut()// Enable shortcuts of UniverfShortcut.enableShortcut()// Trigger a shortcutconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) throw new Error('fWorksheet is not available')const fRange = fWorksheet.getRange('A1')fRange.activate()fRange.setValue('Hello Univer')console.log(fRange.getCellStyle().bold) // falseconst pseudoEvent = new KeyboardEvent('keydown', {  key: 'b',  ctrlKey: true,  keyCode: univerAPI.Enum.KeyCode.B,})const ifShortcutItem = fShortcut.triggerShortcut(pseudoEvent)if (ifShortcutItem) {  const commandId = ifShortcutItem.id  console.log(fRange.getCellStyle().bold) // true}