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 Bases application.
Importing
import { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/bases/facade'import '@univerjs/ui/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.
For more details on the design, see the Univer command system.
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 === 'base.command.set-base-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 Bases command renames the active Base:
const base = univerAPI.getActiveBase()if (base) { await univerAPI.executeCommand('base.command.set-base-name', { unitId: base.getId(), name: 'Product Tracker', })}Events API
The event names exposed through univerAPI.Event come from Univer core and the plugins registered in the current application. Core provides shared command and unit events; Bases plugins add events for tables, fields, records, views, and other Base changes. 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 === 'base.command.set-base-name') { console.log('The Base 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 Bases UI plugin is registered, copy and paste operate on the current Base selection and caret position.
await univerAPI.copy()await univerAPI.paste()Copy and paste rely on the browser's native clipboard API. They can fail when the page does not have focus, the call is not initiated by a user action, or clipboard permission is unavailable. See the MDN clipboard documentation.
UI
See Bases UI components to learn how to extend menus, the toolbar, and other Bases interface areas.
WebSocket
To use WebSocket APIs, install @univerjs/network, register UniverNetworkPlugin, and import its Facade extension.
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/bases')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_BASE)console.log(univerAPI.Enum.BaseFieldType.Text)Utility Method API
Facade exposes shared utilities through univerAPI.Util:
console.log(univerAPI.Util.tools.isString('Univer Bases')) // trueHow is this guide?