# Facade API

> 瞭解如何在應用中新增 Facade API，簡化對 Web SDK 的複雜架構的使用。

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [docs/getting-started/facade.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/getting-started/facade.zh-TW.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 的實現被分散到各個外掛中，並掛載到全域性的 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 時執行的程式碼
  }
})
```

## 預設模式引入 Facade API

如果你透過預設模式安裝 Univer，它會自動引入所含功能的 Facade API，並在你建立 Univer 例項時返回一個對應的 Facade API 例項 `univerAPI`，直接使用即可。