# 通用 API

> 在 PDF 應用程式中使用通用的命令、事件、歷史記錄、剪貼簿、UI、WebSocket、列舉和工具。

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

根 Facade API 由 Univer 通用執行階段和目前 PDF 應用程式註冊的外掛程式共同擴充。本頁介紹跨品類機制，不假設讀者使用過其他 Univer 品類。PDF 單元和頁面入口請繼續閱讀 [Univer PDFs API](https://docs.univer.ai/zh-TW/guides/pdfs/features/core/pdfs-api.md)。

## 建立 API 物件

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

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

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

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

## 命令

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

## 事件

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

// 不再需要時移除監聽器。
commandLog.dispose()
```

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

## 復原與重做

復原和重做作用於目前聚焦的 Univer 單元，並傳回 Promise：

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

具有反向操作的 PDF Facade 變更會進入目前聚焦 PDF 單元的歷史記錄。

## 系統剪貼簿

註冊 `UniverPdfsUIPlugin` 並啟用 PDF 編輯後，UI Facade 的 `copy()` 和 `paste()` 會把剪貼簿命令分派到目前聚焦的 PDF 單元：

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

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

對於可編輯 PDF 物件，PDF UI 外掛程式會把複製內容保存在目前瀏覽器工作階段中，而不是寫入作業系統剪貼簿；瀏覽器原生文字編輯仍遵循瀏覽器的剪貼簿行為。

## UI

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

```ts
univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.TOOLBAR, true)
```

這些方法需要 `UniverUIPlugin`；PDF 編輯控制項還需要 `UniverPdfsUIPlugin`。

## WebSocket

WebSocket 是選用能力。建立 API 物件前，請註冊 Network 外掛程式並匯入其 Facade 入口：

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

import '@univerjs/network/facade'

univer.registerPlugin(UniverNetworkPlugin)

const socket = univerAPI.createSocket('wss://example.com/pdfs')
socket.open$.subscribe(() => socket.send('ready'))
```

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

## 列舉

`univerAPI.Enum` 提供通用執行階段列舉，以及 PDF Facade 擴充的列舉：

```ts
const lifecycle = univerAPI.Enum.LifecycleStages.Steady
const annotationType = univerAPI.Enum.PdfAnnotationType.HIGHLIGHT
```

## 工具

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

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

完整通用 API 請參閱 [Facade 參考](https://docs.univer.ai/zh-TW/reference/facade/univer.md)。