# Facade API

> 了解如何在應用中添加 Facade API，簡化對 Web SDK 的複雜架構的使用。

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/getting-started/facade.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/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-ui/facade'
```

> [!WARNING: 注意事項]
> 並非所有外掛都包含 facade 套件；我們會在每個功能的文件中加以說明。

### 使用

Facade API 是對 Univer 實例的封裝，因此你需要在建立 Univer 實例之後，再用 `FUniver` 包裹該實例：

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

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

## 預設模式引入 Facade API

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

## 注意事項

並非所有的 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 參考**](https://docs.univer.ai/zh-TW/reference/facade.md)