# 通用 API

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

Univer 可用的 Facade API 取決於目前的單元類型和已註冊的外掛。本文介紹 Univer Boards 應用程式會使用的通用 API。

## 導入

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

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

## 命令

Univer 中的大多數操作都會註冊到命令系統。統一的執行路徑為復原、重做和協同等能力提供基礎。

> [!NOTE]
> 如需瞭解設計細節，請閱讀 [Univer 命令系統](/blog/univer#command-system)。

### 監聽命令

使用 `Event.BeforeCommandExecute` 在命令執行前執行邏輯，使用 `Event.CommandExecuted` 在命令執行後執行邏輯。

```typescript
const beforeDisposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, ({ id, params }) => {
  console.log('命令執行前：', id, params)
})

const afterDisposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, params }) => {
  console.log('命令執行後：', id, params)
})
```

如需阻止命令執行，請在 `BeforeCommandExecute` 監聽器中將 `event.cancel` 設為 `true`。

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {
  if (event.id === 'board.command.set-name') {
    event.cancel = true
  }
})
```

監聽器會傳回 `IDisposable`，不再需要時應及時銷毀。

```typescript
beforeDisposable.dispose()
afterDisposable.dispose()
disposable.dispose()
```

### 執行命令

如果已知命令 ID 和參數，可以透過 `FUniver.executeCommand` 執行命令。例如，以下 Boards 命令會重新命名目前的Board：

```typescript
const board = univerAPI.getActiveBoard()

if (board) {
  await univerAPI.executeCommand('board.command.set-name', {
    unitId: board.getId(),
    name: '專案筆記',
  })
}
```

## 事件 API

`univerAPI.Event` 公開的事件來自 Univer Core 和目前應用程式已註冊的外掛。Core 提供通用的命令和單元事件，已註冊的外掛可以繼續擴充事件集合。使用事件前，請先確認提供該事件的外掛已經註冊。

目前版本可用的事件名稱和參數類型請參閱 [Facade Events 參考](https://docs.univer.ai/zh-TW/reference/facade/events.md)。

使用 `addEvent` 訂閱事件，並銷毀傳回的物件來取消訂閱：

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id }) => {
  if (id === 'board.command.set-name') {
    console.log('Board名稱已變更')
  }
})

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

## 復原和重做

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

## UI

如需擴充選單、工具列和其他 Boards 介面區域，請參閱 [Boards UI 元件](https://docs.univer.ai/zh-TW/guides/boards/ui/components.md)。

## WebSocket

如需使用 WebSocket API，請安裝 `@univerjs/network`、註冊 `UniverNetworkPlugin`，並導入它的 Facade 擴充。

```typescript
import { UniverNetworkPlugin } from '@univerjs/network'
import '@univerjs/network/facade'

univer.registerPlugin(UniverNetworkPlugin)
```

之後即可訂閱 Socket 事件、傳送訊息並關閉連線：

```typescript
const socket = univerAPI.createSocket('wss://example.com/boards')

socket.open$.subscribe(() => socket.send('hello'))
socket.message$.subscribe((message) => console.log('WebSocket 訊息：', message.data))
socket.error$.subscribe((error) => console.error('WebSocket 錯誤：', error))
socket.close()
```

## 列舉 API

通用列舉類型透過 `univerAPI.Enum` 公開：

```typescript
console.log(univerAPI.Enum.UniverInstanceType.UNIVER_BOARD)
console.log(univerAPI.Enum.BoardElementType.Shape)
```

## 工具方法 API

通用工具方法透過 `univerAPI.Util` 公開：

```typescript
console.log(univerAPI.Util.tools.isString('Univer Boards')) // true
```