Skip to Content
Facade API Reference

Facade API 参考

简介

为了应对复杂的需求，Univer 的架构也较为复杂，这可能会给使用造成一些困难，为此我们提供了一个更加简单易用的面板 API（Facade API）。为了帮助社区更好的理解 Facade API， 本文档是专属的 Facade API 参考文档， 包含了 Univer SDK（OSS + Pro） 及 Univer Go 的 Facade API 。

安装

开发者可以使用 Presets 安装或者手动组合安装。

使用 Presets 安装

如果你使用 Presets，它会自动引入所含功能的 Facade API，并在你创建 Univer 实例时返回一个对应的 Facade API 实例 univerAPI，直接使用即可。

npm install @univerjs/presets

以下是一个示例如何获取 Facade API 实例：

main.ts
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/zh-CN'
 
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' })

使用手动组合安装

Facade API 的实现被分散到各个插件中，并挂载到全局的 Facade API 根对象上，这意味着对于那些提供了 Facade API 的插件，你需要引入他们对应的 Facade API 实现。

我们会在每个功能的页面介绍它是否提供了 Facade API 实现，你需要按照你实际使用的功能来引入它们对应的 Facade API：

引入

main.ts
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'

引入高级功能的 Facade API 的方式现在与引入开源功能的方式相同，例如：

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

使用

Facade API 是对 Univer 实例的封装，因此你需要在创建了 Univer 实例之后，再用 FUniver 包裹这个实例：

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

Facade API 使用指南

Facade API 提供了创建实例、枚举、事件以及复杂功能的 builder。以下是一份功能列表

类对应功能包
FUniverUniver@univerjs/core
FChart图表@univerjs-pro/sheets-chart
FBlob数据流@univerjs/core
FCollaboration协同@univerjs-pro/collaboration-client
FDataValidation数据验证@univerjs/sheets-data-validation
FDefinedName自定义公式@univerjs/sheets
FDocument文档@univerjs/docs-ui
FFilter筛选@univerjs/sheets-filter
FFormula公式@univerjs/engine-formula
FMenu & FSubmenu菜单@univerjs/ui
FNetwork网络@univerjs/network
FPermission权限@univerjs/sheets
FOverGridImage图片@univerjs/sheets-drawing-ui
FPivotTable透视表@univerjs-pro/sheets-pivot
FRange区域@univerjs/sheets
FSelection选区@univerjs/sheets
FShortcut快捷键@univerjs/ui
FSparkline迷你图@univerjs-pro/sheets-sparkline
FThreadComment批注@univerjs/thread-comment
FWorkbook工作簿@univerjs/sheets
FWorksheet工作表@univerjs/sheets

枚举 & 接口

开发者可以通过两种方式获取定义的枚举和接口

通过 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 来导入

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

所有的事件都暴露在 univerAPI.Event 上， 我们为每个事件定义了参数，开发者可以在本文档上查阅到每个事件对应的参数。 同时我们提供了一系列的 beforeXXX 事件， 在该事件的参数中会包含 cancel 字段， 您可通过设置 该字段为 true 的方式来阻止即将发生的事。

univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (param) => {
  const { text, html } = param
  console.log('debugger', text, html)
  // 取消粘贴行为发生
  param.cancel = true
})

Builder

由于部分功能比较复杂并且构建需要的参数会很多，为了化简使用 API，我们提供了builder来完成这个功能，开发者需要理解builder是调用对应的build 方法并且把返回结果设置到对应的宿主才可以工作的。

// 设置 A1 单元格的数据验证，要求值来自 B1:B10
const range = FRange.create('Sheet1', 'B1:B10')
const rule = FUniver.newDataValidation().requireValueInRange(range).build()
cell.setDataValidation(rule)

在以上的示例中，我们通过 FUniver.newDataValidation() 创建了一个可以 链式调用 数据验证构造器实例，然后调用构造器实例提供的特有方法 requireValueInRange 传入指定验证范围后执行 build 方法返回 setDataValidation 需要的参数。

以下是一个链式调用的示例:

const fWorkbook = univerAPI.getActiveWorkbook()
const fSheet = fWorkbook.getActiveSheet()
const chartBuilder = fSheet.newChart()
const chartInfo = chartBuilder
  // 设置数据源范围
  .addRange('A1:D6')
  // 设置 chart 类型
  .setChartType(ChartTypeBits.Column)
  // 设置 chart 位置
  .setPosition(1, 1, 0, 0)
  // 执行构造参数赋值给 chartInfo 变量
  .build()
  // 插入对应表格
fSheet.insertChart(chartInfo)

目前支持的 builder 有以下：

Builder功能
ConditionalFormatColorScaleRuleBuilder色阶
ConditionalFormatDataBarRuleBuilder数据条
ConditionalFormatHighlightRuleBuilder条件格式高亮
ConditionalFormatIconSetRuleBuilder图表集
FDataValidationBuilder数据验证
FDefinedNameBuilder自定义name
FTheadCommentBuilder评论
FChartBuilderBase图表
LineChartBuilder线型图
PieChartBuilder饼图
RadarChartBuilder雷达图
Globals