General API

The Facade API available in Univer depends on the current unit type and the plugins you register. This page covers the common APIs used in a Univer Docs application.

Importing

import { FUniver } from '@univerjs/core/facade'const univerAPI = FUniver.newAPI(univer)

Commands

Most operations in Univer are registered with the command system. This unified execution path supports features such as undo, redo, and collaboration.

Listening to commands

Use Event.BeforeCommandExecute to run logic before a command, or Event.CommandExecuted to run logic after it finishes.

const beforeDisposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, ({ id, params }) => {  console.log('Before command:', id, params)})const afterDisposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, params }) => {  console.log('Command executed:', id, params)})

To prevent a command from running, set event.cancel to true in a BeforeCommandExecute listener.

const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {  if (event.id === 'doc.command.set-name') {    event.cancel = true  }})

Event listeners return an IDisposable. Dispose listeners when you no longer need them.

beforeDisposable.dispose()afterDisposable.dispose()disposable.dispose()

Executing commands

If you know a command ID and its parameters, run it with FUniver.executeCommand. For example, the following Docs command renames the active document:

const document = univerAPI.getActiveDocument()if (document) {  await univerAPI.executeCommand('doc.command.set-name', {    unitId: document.getId(),    name: 'Project Notes',  })}

Events API

The event names exposed through univerAPI.Event come from Univer core and the plugins registered in the current application. Core provides command and document lifecycle events, while Docs plugins can extend the event surface with their own events. Check that an event belongs to a plugin you have registered before using it.

See the Facade Events reference for the event names and parameter types available in the current release.

Use addEvent to subscribe and dispose the returned object to unsubscribe:

const disposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id }) => {  if (id === 'doc.command.set-name') {    console.log('The document name changed')  }})// Remove the listener when it is no longer neededdisposable.dispose()

Undo and Redo

await univerAPI.undo()await univerAPI.redo()

System Clipboard

After the Docs UI plugin is registered, copy and paste operate on the current document selection and caret position.

await univerAPI.copy()await univerAPI.paste()

UI

See Docs UI components to learn how to extend menus, the toolbar, and other Docs interface areas.

WebSocket

Preset installations expose univerAPI.createSocket(url). In plugin mode, install @univerjs/network, register UniverNetworkPlugin, and import its Facade extension first.

import { UniverNetworkPlugin } from '@univerjs/network'import '@univerjs/network/facade'univer.registerPlugin(UniverNetworkPlugin)

You can then subscribe to socket events, send messages, and close the connection:

const socket = univerAPI.createSocket('wss://example.com/docs')socket.open$.subscribe(() => {  socket.send('hello')})socket.message$.subscribe((message) => {  console.log('WebSocket message:', message.data)})socket.error$.subscribe((error) => {  console.error('WebSocket error:', error)})socket.close()

Enum API

Facade exposes common enum types through univerAPI.Enum:

console.log(univerAPI.Enum.UniverInstanceType.UNIVER_DOC)console.log(univerAPI.Enum.LifecycleStages.Rendered)

Utility Method API

Facade exposes shared utilities through univerAPI.Util:

console.log(univerAPI.Util.tools.isString('Univer Docs')) // true