# 編輯歷史

- Human documentation: [https://docs.univer.ai/zh-TW/guides/docs/features/edit-history](https://docs.univer.ai/zh-TW/guides/docs/features/edit-history)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/docs/features/edit-history.md](https://docs.univer.ai/zh-TW/guides/docs/features/edit-history.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [docs/features/edit-history.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/edit-history.zh-TW.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-docs-collaboration",
      "locale": "@univerjs/preset-docs-collaboration/locales/zh-TW",
      "style": "@univerjs/preset-docs-collaboration/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/edit-history",
      "facade": "@univerjs-pro/edit-history/facade"
    },
    {
      "client": "@univerjs-pro/edit-history-ui",
      "locale": "@univerjs-pro/edit-history-ui/locale/zh-TW",
      "style": "@univerjs-pro/edit-history-ui/lib/index.css"
    },
    {
      "client": "@univerjs-pro/docs-history"
    },
    {
      "client": "@univerjs-pro/docs-history-ui",
      "locale": "@univerjs-pro/docs-history-ui/locale/zh-TW"
    }
  ],
  "license": true,
  "server": true
}
```

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

## 準備協同與歷史服務

完成[協同整合](https://docs.univer.ai/zh-TW/server/collaboration/browser-integration.md)與[授權設定](https://docs.univer.ai/zh-TW/server/license.md)。確認兩個工作階段可以共同編輯同一份 Docs 文件，且重新載入後修改仍然保留。

參考 [Office 協同擴充](https://docs.univer.ai/zh-TW/server/collaboration/extensions.md)與[歷史範例](https://docs.univer.ai/zh-TW/server/collaboration/examples.md#history)，接入歷史儲存與權限。核心協同功能不會自動啟用歷史記錄；後端還必須支援歷史清單、版本內容與還原操作。

## 加入歷史外掛

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

#### npm

```bash
npm install @univerjs-pro/edit-history @univerjs-pro/edit-history-ui @univerjs-pro/docs-history @univerjs-pro/docs-history-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/edit-history @univerjs-pro/edit-history-ui @univerjs-pro/docs-history @univerjs-pro/docs-history-ui
```

#### yarn

```bash
yarn add @univerjs-pro/edit-history @univerjs-pro/edit-history-ui @univerjs-pro/docs-history @univerjs-pro/docs-history-ui
```

#### bun

```bash
bun add @univerjs-pro/edit-history @univerjs-pro/edit-history-ui @univerjs-pro/docs-history @univerjs-pro/docs-history-ui
```

```ts
import { UniverEditHistoryPlugin } from '@univerjs-pro/edit-history'
import EditHistoryLocale from '@univerjs-pro/edit-history-ui/locale/en-US'
import { UniverDocsHistoryPlugin } from '@univerjs-pro/docs-history'
import { UniverDocsHistoryUIPlugin } from '@univerjs-pro/docs-history-ui'
import HistoryLocale from '@univerjs-pro/docs-history-ui/locale/en-US'
import { LocaleType, mergeLocales } from '@univerjs/core'

import '@univerjs-pro/edit-history-ui/lib/index.css'

const historyServerUrl = '/api/history'

univerAPI.loadLocales(LocaleType.EN_US, mergeLocales(EditHistoryLocale, HistoryLocale))
univer.registerPlugin(UniverEditHistoryPlugin, { historyServerUrl })
univer.registerPlugin(UniverDocsHistoryPlugin)
univer.registerPlugin(UniverDocsHistoryUIPlugin, {
  univerContainerId: 'app',
  historyServerUrl,
})
```

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

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

## 檢視與還原版本

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

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

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

## 比較快照

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

```ts
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_DOC,
  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](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs-pro/edit-history.md#headless-comparison)。