# Facade API

> 了解如何在应用中添加 Facade API，简化对 Web SDK 的复杂架构的使用。

- Human documentation: [https://docs.univer.ai/zh-CN/guides/docs/getting-started/facade](https://docs.univer.ai/zh-CN/guides/docs/getting-started/facade)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/docs/getting-started/facade.md](https://docs.univer.ai/zh-CN/guides/docs/getting-started/facade.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [docs/getting-started/facade.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/getting-started/facade.zh-CN.mdx)

---

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

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

> [!WARNING: 注意事项]
> 部分 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 实现。

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

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

> [!WARNING: 注意事项]
> 并非所有插件都包含了 facade 包，我们会在每个功能的文档对此进行说明。

### 使用

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

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

const univerAPI = FUniver.newAPI(univer)
```

### 注意事项

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

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