Facade API Reference

Introduction

To meet complex needs, the architecture of Univer is also relatively complex, which may cause some difficulties in use. Therefore, we provide a simpler and easier-to-use Facade API. To help the community better understand the Facade API, this document is a dedicated Facade API reference document, including the Univer SDK (OSS + Pro) and Univer Go Facade API.

Installation

Developers can install using Presets or manually combine installations.

Install using Presets

If you use Presets, it will automatically introduce the Facade API of the included functions and return a corresponding Facade API instance univerAPI when you create a Univer instance, which can be used directly.

npm install @univerjs/presets

pnpm add @univerjs/presets

yarn add @univerjs/presets

bun add @univerjs/presets

Here is an example of how to get the Facade API instance:

import { createUniver, defaultTheme, LocaleType, merge } from '@univerjs/presets'
import { UniverSheetsCorePreset } from '@univerjs/presets/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/presets/preset-sheets-core/locales/en-US'
 
import '@univerjs/presets/lib/styles/preset-sheets-core.css'
 
const { univer, univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: merge(
      {},
      UniverPresetSheetsCoreZhCN,
    ),
  },
  theme: defaultTheme,
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
})
 
univerAPI.createWorkbook({ name: 'Test Sheet' })

Piecemeal Installation

The implementation of the Facade API has been distributed to various plugins and mounted on the global Facade API root object. This means that for plugins that provide a Facade API, you need to introduce their corresponding Facade API implementation.

We will introduce whether each feature provides a Facade API implementation on its page. You need to introduce their corresponding Facade API according to the features you actually use:

Import

import '@univerjs/sheets/facade'
import '@univerjs/ui/facade'
import '@univerjs/docs-ui/facade'
import '@univerjs/sheets-ui/facade'
 
import '@univerjs/sheets-data-validation/facade'
import '@univerjs/engine-formula/facade'
import '@univerjs/sheets-filter/facade'
import '@univerjs/sheets-formula/facade'
import '@univerjs/sheets-numfmt/facade'
import '@univerjs/sheets-hyper-link-ui/facade'

The way to introduce Facade APIs with advanced features is now the same as the way to introduce open-source features, for example:

import '@univerjs-pro/sheets-pivot/facade'
import '@univerjs-pro/exchange-client/facade'

Usage

The Facade API is a wrapper for the Univer instance, so you need to wrap this instance with FUniver after creating the Univer instance:

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

Facade API Usage Guide

The Facade API provides instance creation, enumeration, events, and complex function builders. Here is a list of functions:

Enums & Interfaces

Developers can get the defined enums and interfaces in two ways:

Get through univerAPI.Enum.XXXX.xxx

const pivotAverageSubtotalType = univerAPI.Enum.PivotSubtotalTypeEnum.average
 
univerAPI.addEvent(univerAPI.Event.ActiveSheetChanged, (params) => {
  const { workbook, activeSheet } = params
  console.log('after active sheet changed', params)
})

Import to get

import { PivotSubtotalTypeEnum } from '@univerjs-pro/engine-pivot'
 
console.log(PivotSubtotalTypeEnum)

All events are exposed on univerAPI.Event. We define parameters for each event, and developers can refer to the parameters corresponding to each event in this document. We also provide a series of beforeXXX events. The parameters of these events include a cancel field, which you can set to true to prevent the upcoming action.

univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (param) => {
  const { text, html } = param
  console.log('debugger', text, html)
  // Cancel the paste action
  param.cancel = true
})

Builder

Since some functions are relatively complex and the parameters required for construction can be numerous, to simplify the use of the API, we provide builders to complete this function. Developers need to understand that the builder works by calling the corresponding build method and setting the returned result to the corresponding host.

// Set the data validation for cell A1 to require a value from B1:B10
const range = FRange.create('Sheet1', 'B1:B10')
const rule = FUniver.newDataValidation().requireValueInRange(range).build()
cell.setDataValidation(rule)

In the above example, we created a data validation builder instance that can be chained by FUniver.newDataValidation(), then called the specific method requireValueInRange provided by the builder instance, passed in the specified validation range, and executed the build method to return the parameters required by setDataValidation.

Here is an example of a chain call:

const fWorkbook = univerAPI.getActiveWorkbook()
const fSheet = fWorkbook.getActiveSheet()
const chartBuilder = fSheet.newChart()
const chartInfo = chartBuilder
  // Set data source range
  .addRange('A1:D6')
  // Set chart type
  .setChartType(ChartTypeBits.Column)
  // Set chart position
  .setPosition(1, 1, 0, 0)
  // Execute the build method and assign the result to the chartInfo variable
  .build()
  // Insert the chart into the corresponding sheet
fSheet.insertChart(chartInfo)

Currently supported builders are as follows: