通用 API

根 Facade API 將通用 Univer 執行環境與目前應用程式註冊的 Slides 外掛程式組合在一起。本頁介紹命令、事件、歷史記錄和 Unit 生命週期，不假設讀者使用過其他 Univer 品類。簡報物件請繼續閱讀 Univer Slides API。

建立 API 物件

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

TypeScript

import { FUniver } from '@univerjs/core/facade'const univerAPI = FUniver.newAPI(univer)

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

命令

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

事件

TypeScript

const commandLog = univerAPI.addEvent(  univerAPI.Event.CommandExecuted,  ({ id }) => console.log('Executed:', id))// 不再需要監聽時釋放它。commandLog.dispose()

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

復原與重做

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

TypeScript

await univerAPI.undo()await univerAPI.redo()

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

系統剪貼簿

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

TypeScript

import '@univerjs/ui/facade'await univerAPI.copy()await univerAPI.paste()

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

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

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

UI

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

TypeScript

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

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

WebSocket

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

TypeScript

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 擴充的列舉：

TypeScript

const lifecycle = univerAPI.Enum.LifecycleStages.Steadyconst transition = univerAPI.Enum.SlideTransitionTypeEnum.Fadeconst elementType = univerAPI.Enum.SlidePageElementTypeEnum.Shape

工具

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

TypeScript

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

你覺得這篇文檔如何？