# 通用 API

- Human documentation: [https://docs.univer.ai/zh-TW/guides/slides/features/core/general-api](https://docs.univer.ai/zh-TW/guides/slides/features/core/general-api)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/slides/features/core/general-api.md](https://docs.univer.ai/zh-TW/guides/slides/features/core/general-api.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [slides/features/core/general-api.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/slides/features/core/general-api.zh-TW.mdx)

---

根 Facade API 將通用 Univer 執行環境與目前應用程式註冊的 Slides 外掛程式組合在一起。本頁介紹命令、事件、歷史記錄和 Unit 生命週期，不假設讀者使用過其他 Univer 品類。簡報物件請繼續閱讀 [Univer Slides API](https://docs.univer.ai/zh-TW/guides/slides/features/core/slides-api.md)。

## 建立 API 物件

註冊 Univer 執行個體及所需外掛程式後，建立一個 `FUniver` 包裝物件：

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

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

在此之前匯入的 Facade 入口會在同一個物件上擴充 Slides 方法。

## 命令

`executeCommand()` 會非同步執行已註冊的命令。只有命令明確支援同步執行時才使用 `syncExecuteCommand()`。常用 Slides 操作應優先使用 Facade 方法。

## 事件

```ts
const commandLog = univerAPI.addEvent(
  univerAPI.Event.CommandExecuted,
  ({ id }) => console.log('Executed:', id)
)

// 不再需要監聽時釋放它。
commandLog.dispose()
```

應用程式需要檢查或取消命令時，可以監聽 `BeforeCommandExecute`。`LifeCycleChanged` 會回報編輯器進入 `Rendered`、`Steady` 等階段。

## 復原與重做

復原和重做作用於目前取得焦點的 Univer Unit，並傳回 Promise：

```ts
await univerAPI.undo()
await univerAPI.redo()
```

Slides Facade 變更透過命令管線執行，因此支援的變更會進入同一份歷史記錄。

## 系統剪貼簿

註冊 `UniverSlidesUIPlugin` 並讓 Slides 畫布取得焦點後，`copy()` 複製目前選取內容，`paste()` 透過 Slides UI 命令插入剪貼簿內容。

```ts
import '@univerjs/ui/facade'

await univerAPI.copy()
await univerAPI.paste()
```

畫布右鍵選單支援一般貼上、貼上為文字及貼上為圖片。文字模式依剪貼簿文字建立可編輯文字方塊；圖片模式使用剪貼簿中的圖片檔案或 HTML 中可用的圖片資源，不會將任意內容自動轉成圖片。

編輯形狀或表格內的文字時，文字編輯器提供**保留來源格式**、**符合目標格式**與**只保留文字**，貼上後也可透過格式選單調整。

這些操作需要瀏覽器編輯器取得焦點及剪貼簿權限，不適用於僅模型的 Node.js 環境。瀏覽器阻止讀取剪貼簿時，可使用系統貼上快速鍵。

## UI

UI Facade 可以顯示訊息、開啟對話方塊或側邊欄、註冊元件，並控制內建 UI 區域：

```ts
univerAPI
  .showMessage({ content: 'Presentation saved', type: 'success' })
  .setUIVisible(univerAPI.Enum.BuiltInUIPart.TOOLBAR, true)
```

這些方法依賴 `UniverUIPlugin`；Slides 編輯控制項還需要 `UniverSlidesUIPlugin`。

## WebSocket

WebSocket 是由 Network Facade 提供的選用能力：

```ts
import { UniverNetworkPlugin } from '@univerjs/network'

import '@univerjs/network/facade'

univer.registerPlugin(UniverNetworkPlugin)

const socket = univerAPI.createSocket('wss://example.com/slides')

socket.open$.subscribe(() => socket.send('ready'))
```

訊息協定、身分驗證、重新連線和協作衝突處理仍由宿主應用程式負責。

## 列舉

`univerAPI.Enum` 提供通用執行環境列舉，以及 Slides 擴充的列舉：

```ts
const lifecycle = univerAPI.Enum.LifecycleStages.Steady
const transition = univerAPI.Enum.SlideTransitionTypeEnum.Fade
const elementType = univerAPI.Enum.SlidePageElementTypeEnum.Shape
```

## 工具

`univerAPI.Util` 提供數字格式化、矩形運算和通用工具等共享輔助能力：

```ts
const payload = univerAPI.Util.tools.deepClone({
  slideId: 'slide-1',
  selectedElementIds: ['element-1'],
})
```