Web SDK

編輯歷史

插件信息

修改 元素位置、文字或連接線 後，可開啟歷史記錄檢視較早的版本、比較變更，並在權限允許時還原版本。歷史記錄讀取的是伺服器持久化的版本；復原與重做只作用於目前的編輯工作階段，不需要歷史服務。

準備協同與歷史服務

完成協同整合與授權設定。確認兩個工作階段可以共同編輯同一份 Boards 文件，且重新載入後修改仍然保留。

參考 Office 協同擴充與歷史範例，接入歷史儲存與權限。核心協同功能不會自動啟用歷史記錄；後端還必須支援歷史清單、版本內容與還原操作。

加入歷史外掛

在現有產品、授權與協同設定上加入以下設定。若預設集或現有設定已註冊這些外掛，請修改原有設定，不要重複註冊。

Shell
pnpm add @univerjs-pro/edit-history @univerjs-pro/edit-history-ui @univerjs-pro/boards-history @univerjs-pro/boards-history-ui
TypeScript
import { UniverEditHistoryPlugin } from '@univerjs-pro/edit-history'import EditHistoryLocale from '@univerjs-pro/edit-history-ui/locale/en-US'import { UniverBoardsHistoryPlugin } from '@univerjs-pro/boards-history'import { UniverBoardsHistoryUIPlugin } from '@univerjs-pro/boards-history-ui'import HistoryLocale from '@univerjs-pro/boards-history-ui/locale/en-US'import { LocaleType, mergeLocales } from '@univerjs/core'import '@univerjs-pro/edit-history-ui/lib/index.css'import '@univerjs-pro/boards-history-ui/lib/index.css'const historyServerUrl = '/api/history'univerAPI.loadLocales(LocaleType.EN_US, mergeLocales(EditHistoryLocale, HistoryLocale))univer.registerPlugin(UniverEditHistoryPlugin, { historyServerUrl })univer.registerPlugin(UniverBoardsHistoryPlugin)univer.registerPlugin(UniverBoardsHistoryUIPlugin, {  univerContainerId: 'app',  historyServerUrl,})

將 /api/history 換成應用程式的歷史端點，並確認其 API 符合用戶端請求。兩處 historyServerUrl 必須一致。將 univerContainerId 設為編輯器容器的 DOM ID，並載入與編輯器一致的語言套件。

歷史檢視器會建立獨立的唯讀編輯器。若有自訂內容，可透過 viewerPlugins 加入檢視器尚未包含的外掛，不要再次註冊內建的檢視器外掛。

檢視與還原版本

從編輯器選單開啟歷史記錄，選擇版本以檢視內容與差異。還原會修改目前共用的文件；只有具備還原權限的使用者才能操作，且伺服器必須強制檢查此權限。

驗證整合時，修改 元素位置、文字或連接線，等待協同確認後，檢查歷史清單與版本內容。重新開啟應用程式並重啟服務，以確認資料持久化。還原較早的版本，並確認另一個瀏覽器工作階段收到還原後的狀態。

若清單為空，先確認此文件是否已產生歷史記錄，再檢查文件 ID 與服務 URL。若可檢視但無法還原，請檢查還原權限與協同連線。讀取歷史記錄也需要授權，因為舊版本可能包含已刪除的資料。

比較快照

若要建立審閱介面或向 AI Agent 提供變更資訊，可呼叫 compareUnitData()，或用 prepareUnitComparison() 計算一次後重複查詢。先註冊此品類的 History 外掛並匯入 Facade 入口，再將同一文件的兩份完整快照作為 beforeSnapshot 和 afterSnapshot 傳入。唯讀比較不需要歷史服務，也不會還原或合併內容。

TypeScript
import { UnitComparisonDetailLevel, UnitComparisonFidelity } from '@univerjs-pro/edit-history'import { UniverInstanceType } from '@univerjs/core'import '@univerjs-pro/edit-history/facade'const comparison = univerAPI.prepareUnitComparison({  comparisonId: 'review-1',  unitId: beforeSnapshot.id,  type: UniverInstanceType.UNIVER_BOARD,  fidelity: UnitComparisonFidelity.SNAPSHOT,  leftData: beforeSnapshot,  rightData: afterSnapshot,})const overview = comparison.query({ detail: UnitComparisonDetailLevel.SUMMARY })const scope = overview.scopes[0]const page = comparison.query({ scope, offset: 0, limit: 100 })console.log(page.items, page.page.hasMore, page.diagnostics)

透過 scopes 取得可用檢視，將選定範圍傳入 query() 即可篩選結果，無須重新計算差異。預設每頁 100 項，上限 1,000 項；搭配 page.hasMore 與 offset 取得後續項目。summary 始終描述整體比較，不受項目篩選影響。使用前應檢查 diagnostics.readiness 與 diagnostics.codes，不要將降級結果視為完整比較。不建立編輯器的 Node.js 或 CLI 用法請見無介面比較 API。

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.