Facade API
Learn how to add Facade API to your application to simplify the usage of Web SDK.
Univer's architecture has to accommodate complex requirements, and the core API reflects that complexity. Univer therefore also provides the Facade API, a simpler layer that application code calls directly.
This page describes how to add the Facade API to an application. The pages in the Features section list the main Facade APIs for each feature; for the complete set, see the API reference of each plugin.
Caution
Some Facade APIs are asynchronous, and the ones that modify data often return a Promise. When data is read immediately after it is changed, await the call or chain .then(); otherwise the results may be unexpected. To determine whether an API returns a Promise, consult the corresponding API reference.
Integrating Facade API in Plugin Mode
Installation
In plugin mode, each plugin ships its own Facade API implementation, and all of them attach to one global Facade API object. For every plugin that provides a Facade API, import the matching implementation as needed.
import { FUniver } from '@univerjs/core/facade'import '@univerjs/ui/facade'import '@univerjs/docs-ui/facade'Caution
Not every plugin includes a facade package. Each feature page states whether it does.
Usage
The Facade API wraps a Univer instance. Create the instance first, then wrap it with FUniver:
import { FUniver } from '@univerjs/core/facade'const univerAPI = FUniver.newAPI(univer)Integrating Facade API in Preset Mode
In preset mode, the presets import the Facade API for the features they contain. Creating a Univer instance returns a matching univerAPI instance, which can be used immediately.
Cautions
Not every Facade API can be called immediately. Some take effect only at a specific lifecycle stage. When an immediate call does not take effect, select the appropriate stage as follows:
const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => { if (stage === univerAPI.Enum.LifecycleStages.Rendered) { // Code to be executed when the lifecycle stage is Rendered } if (stage === univerAPI.Enum.LifecycleStages.Steady) { // Code to be executed when the lifecycle stage is Steady }})How is this guide?