Facade API

了解如何在应用中添加 Facade API,简化对 Univer 的复杂架构的使用。

GitHub在 GitHub 上编辑

为了应对复杂的需求,Univer 的架构也较为复杂,这可能会给使用造成一些困难,为此我们提供了一个更加简单易用的面板 API(Facade API)。

本小节将详细介绍如何在应用中添加 Facade API,后续的 “功能” 章节中,我们将列出每个功能的主要 Facade API,如果你想查看所有的 Facade API,请参考各个插件的 API 文档。

注意事项

部分 Facade API 是异步的,特别是修改数据的 API,它们大多会返回一个 Promise。如果你需要再修改数据后立即获取数据,请使用 await 或者 .then(),否则可能会获取到不符合预期的结果。想要了解具体有哪些 API 会返回 Promise,请查看对应的 API 参考手册。

预设模式引入 Facade API

如果你通过预设模式安装 Univer,它会自动引入所含功能的 Facade API,并在你创建 Univer 实例时返回一个对应的 Facade API 实例 univerAPI,直接使用即可。

插件模式引入 Facade API

安装

对于通过插件模式安装 Univer 的情况下,Facade API 的实现被分散到各个插件中,并挂载到全局的 Facade API 根对象上,这意味着对于那些提供了 Facade API 的插件,你可以按需引入他们对应的 Facade API 实现。

import { FUniver } from '@univerjs/core/facade'

import '@univerjs/ui/facade'
import '@univerjs/docs-ui/facade'

注意事项

并非所有插件都包含了 facade 包,我们会在每个功能的文档对此进行说明。

使用

Facade API 是对 Univer 实例的封装,因此你需要在创建了 Univer 实例之后,再用 FUniver 包裹该实例:

import { FUniver } from '@univerjs/core/facade'

const univerAPI = FUniver.newAPI(univer)

注意事项

并非所有的 Facade API 都可以被即时调用,有些 API 需要在特定的生命周期阶段才能使用,遇到即时执行无法生效的情况,请参照以下方式选择合适的生命周期执行:

const disposable = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {
  if (stage === univerAPI.Enum.LifecycleStages.Steady) {
    // 在生命周期阶段为 Steady 时执行的代码
  }
})

你觉得这篇文档如何?